# Dialog

The **Dialog** object allows you to display dialogs that prompt the user for confirmation, allow them to input text strings or passwords, and select checkbox options or choose from a drop-down list. You can also use this object to display a popup menu on screen.

You can create a **Dialog** object from the [**DOpus**](dopus)**.Dlg**, [**Lister**](lister)**.Dlg**, [**Tab**](tab)**.Dlg**, [**Func**](func)**.Dlg** and [**Command**](command)**.Dlg** methods.

See the [Example Scripts](../../../scripting/example_scripts) section for an example of its use.

There are two different ways to use the **Dialog** object. You can either:

* Use the one-shot methods (**Folder**, **GetString**, **Multi**, **Open**, **Request** or **Save**) to display a simple dialog of various types, or
* Configure the dialog first by setting the values of the various properties, and then call the **Show** function to display it. This method also lets you create and use [script dialogs](../../../scripting/script_dialogs).

The one-shot methods accept several parameters but are generally not as flexible as building up the dialog and then calling **Show**.

<table><thead><tr><th>Property Name</th><th>Return Type</th><th>Description</th></tr></thead><tbody><tr><td>buttons</td><td><em>string</em></td><td><p>Specifies the buttons that are displayed at the bottom of the dialog. These buttons are used to close the dialog. The <strong>Show</strong> method returns a value indicating which button was chosen (and this value is also available in the <strong>result</strong> property).</p><p>Multiple button strings must be separated with vertical bar characters (|). If a button has more than one button then by definition the last one is the "cancel" button. For example:</p><pre><code>dlg.buttons = "OK|Retry|Cancel"
</code></pre><p>To specify <em>accelerators</em> for the buttons prefix the desired key with an ampersand (&#x26;) character. For example:</p><pre><code>dlg.buttons = "&#x26;OK|&#x26;Retry|&#x26;Cancel"
</code></pre><p>Buttons can also have drop-down menus attached to them, by separating the drop-down items with plus signs (+). For example:</p><pre><code>dlg.buttons = "OK|Retry+Retry All|Cancel"
</code></pre><p>Within drop-down menus, you can specify that certain menu items can be accessed directly from the main button by holding Shift, Ctrl or Shift+Ctrl. This is done by adding an equals sign and then the label the button should display when the key is held down (usually an abbreviated version of the menu item label, or a repetition of the label itself if it is already short enough). The keys are automatically assigned and you can only do this for at most three items. For example:</p><p>&#x3C;WRAP prewrap></p><pre><code>dlg.buttons = "OK|Retry+Retry All=Retry All|Skip+Skip if same modified time=Skip Same Time|Cancel"
</code></pre><p>&#x3C;/WRAP></p></td></tr><tr><td>choices</td><td><em>object:</em><a href="vector"><strong>Vector</strong></a><em>(string)</em><br>or <em>array(string)</em></td><td><p>This property uses either a <a href="vector"><strong>Vector</strong></a> or an array of strings to provide a list of multiple options that can be shown to the user. The list can be presented in one of three ways:</p><ul><li><strong>Drop-down list</strong>: By default, the dialog will display a drop-down list allowing the user to select one option. The index of the chosen selection is available via the <strong>selection</strong> property when the <strong>Show</strong> method returns.</li><li><strong>Checkbox list</strong>: If the <strong>list</strong> property is also given the dialog will display a scrolling list of items, each with a checkbox allowing it to be turned on or off.</li><li><strong>Popup menu</strong>: If the <strong>menu</strong> property is also given, a popup menu will be displayed at the current mouse coordinates. Use a single hyphen ("-") as a menu label to insert a separator.</li></ul><p>When shown as a checkbox list the dialog is resizable; you can set the initial size using the <strong>cx</strong> and <strong>cy</strong> properties (and retrieve them afterwards if you want to save the size).</p></td></tr><tr><td>confirm</td><td><em>bool</em></td><td>In a text entry dialog (i.e. the <strong>max</strong> property has been specified) setting <strong>confirm</strong> to <strong>True</strong> will require that the user types the entered text again (in a second text field) to confirm it (e.g. for a password).</td></tr><tr><td>cx</td><td><em>int</em></td><td>For <a href="../../../scripting/script_dialogs">script dialogs</a> marked as resizable, this property lets you override the width of the dialog defined in the resource - although note you can't resize a dialog smaller than its initial size.</td></tr><tr><td>cy</td><td><em>int</em></td><td>For <a href="../../../scripting/script_dialogs">script dialogs</a> marked as resizable, this property lets you override the height of the dialog defined in the resource - although note you can't resize a dialog smaller than its initial size.</td></tr><tr><td>defvalue</td><td><em>string</em></td><td><p>In a text entry dialog (i.e. the <strong>max</strong> property has been specified) this property allows you to initialize the text field with a default value.</p><p>(Old scripts may use "default" instead of "defvalue"; this is deprecated because it does not work in JScript where "default" is a reserved keyword.)</p></td></tr><tr><td>defid</td><td><em>int</em></td><td>Allows you to change the default button (i.e. the action that will occur if the user hits enter) in the dialog. Normally the first button is the default - this has a <strong>defid</strong> of 1. The second button would have a <strong>defid</strong> of 2, and so on. If a dialog has more than one button then by definition the very last button is the "cancel" button, and this has a <strong>defid</strong> of 0.</td></tr><tr><td>detach</td><td><em>bool</em></td><td>Set to <strong>True</strong> if you want a <a href="../../../scripting/script_dialogs">script dialog</a> to run in “detached” mode, where your script provides its <a href="../../../scripting/script_dialogs/the_dialog_message_loop">message loop</a>.</td></tr><tr><td>disable_window</td><td><em>object:</em><a href="lister"><strong>Lister</strong></a><br>or <em>object:</em><a href="tab"><strong>Tab</strong></a> <br>*or object:*<strong>Dialog\</strong> or <em>int</em></td><td><p>Use this to cause the dialog to automatically disable another window when it's displayed. The user will be unable to click or type in the disabled window until the dialog is closed. Normally if you use this you would set this to the same value as the <strong>window</strong> property.</p><p>You can provide either a <a href="lister"><strong>Lister</strong></a> or a <a href="tab"><strong>Tab</strong></a> object, or another <strong>Dialog</strong>. If you are showing this dialog in response to the <a href="../scripting_events/onaboutscript"><strong>OnAboutScript</strong></a> event, you can also pass the value of the <a href="aboutdata"><strong>AboutData</strong></a><strong>.window</strong> property.</p></td></tr><tr><td>icon</td><td><em>string</em> or<br><em>object:</em><a href="image"><strong>Image</strong></a></td><td><p>Displays one of several standard icons in the top-left corner of the dialog, which can be used, for example, to indicate the severity of an error condition. The valid values for this property are <em>warning</em>, <em>error</em>, <em>info</em> and <em>question</em>.</p><p>When used with a <a href="../../../scripting/script_dialogs">script dialog</a> this property lets you control the icon shown in the dialog's title bar. In this instance, instead of a string you can also provide an <a href="image"><strong>Image</strong></a> object that you obtained from the <a href="dopus"><strong>DOpus</strong></a><strong>.LoadImage</strong> or <a href="script"><strong>Script</strong></a><strong>.LoadImage</strong> methods. Note that the image must have been loaded from a <strong>.ico</strong> file.</p></td></tr><tr><td>input</td><td><em>string</em></td><td>In a text entry dialog, this property returns the text string that the user entered (i.e. once the <strong>Show</strong> method has returned).</td></tr><tr><td>language</td><td><em>string</em></td><td>Set this property to create a <a href="../../../scripting/script_dialogs">script dialog</a> in a particular language (if one or more <a href="../../../scripting/script_editor/editors/dialog_editor/language_overlays">language overlays</a> have been provided), rather than the currently selected language.</td></tr><tr><td>list</td><td><em>object:</em><a href="vector"><strong>Vector</strong></a><em>(bool)</em><br>or <em>array(bool)\</em> or// int//</td><td><p>In conjunction with the <strong>choices</strong> property, this will cause the choices to be presented as a checkbox list. You can initialize this <strong>Vector</strong> or array with the same number of items as the choices property, and set each one to <strong>True</strong> or <strong>False</strong> to control the default state of each checkbox. Or, simply set this value to** 0** to activate the checkbox list without having to initialize the state of each checkbox.</p><p>When the <strong>Show</strong> method returns, this property will return a <a href="vector"><strong>Vector</strong></a> of <em>bools</em> that provide the state of each checkbox as set by the user.</p></td></tr><tr><td>max</td><td><em>int</em></td><td><p>This property enables text entry in the dialog - a text field will be displayed allowing the user to enter a string. Set this property to the maximum length of the string you want the user to be able to enter (or <strong>0</strong> to have no limit).</p><p>When the <strong>Show</strong> method returns the text the user entered will be available in the <strong>input</strong> property.</p></td></tr><tr><td>menu</td><td><em>object:</em><a href="vector"><strong>Vector</strong></a><em>(int)</em><br>or <em>array(int)</em><br>or <em>int</em></td><td><p>In conjunction with the <strong>choices</strong> property, this will cause the choices to be presented as a popup menu rather than in a dialog. The menu will be displayed at the current mouse coordinates.</p><p>You can initialize this <strong>Vector</strong> or array with the same number of items as the choices property, and set each one to a value representing various flags that control the appearance of the menu item. The available flags are as follows - their values must be added together if you need to specify more than one flag per item.</p><table><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>1</strong></td><td>bold (indicates the default item)</td></tr><tr><td><strong>2</strong></td><td>checked (a checkmark will appear next to the item)</td></tr><tr><td><strong>4</strong></td><td>radio (a radio button will appear next to the item)</td></tr><tr><td><strong>8</strong></td><td>disabled (the user will not be able to select the item)</td></tr></tbody></table><p>You can also simply set this value to <strong>0</strong> or <strong>1</strong> to activate the popup menu without having to provide flags for each item (if set to <strong>1</strong>, the top item in the menu will appear bolded).</p><p>The <strong>Show</strong> method returns the index of the menu item the user chose (with <strong>1</strong> being the first item), or <strong>0</strong> if the menu was cancelled.</p></td></tr><tr><td></td><td></td><td></td></tr><tr><td><strong>1</strong></td><td>bold (indicates the default item)</td><td></td></tr><tr><td><strong>2</strong></td><td>checked (a checkmark will appear next to the item)</td><td></td></tr><tr><td><strong>4</strong></td><td>radio (a radio button will appear next to the item)</td><td></td></tr><tr><td><strong>8</strong></td><td>disabled (the user will not be able to select the item)</td><td></td></tr><tr><td>message</td><td><em>string</em></td><td>Specifies the message text displayed in the dialog.</td></tr><tr><td>msgonly</td><td><em>bool</em></td><td>Set to <strong>True</strong> before creating the dialog to create a <em>message-only</em> dialog. A message-only dialog will never be visible, but still runs a normal message loop. This lets you use things like <code>WatchTab</code> or <code>HTTPRequest</code> without needing a visible dialog (or resorting to opacity tricks). No dialog template is needed when using this mode. Note that only detached dialogs support this option.</td></tr><tr><td>opacity</td><td><em>int</em></td><td>For <a href="../../../scripting/script_dialogs">script dialogs</a> this property retrieves or sets the current dialog opacity level, from <strong>0</strong> (totally transparent) to <strong>255</strong> (totally opaque).</td></tr><tr><td>options</td><td><em>collection:</em><a href="dialogoption"><strong>DialogOption</strong></a></td><td><p>This is a collection of five options that will be displayed as checkboxes in the dialog. Unlike the <strong>choices</strong> / <strong>list</strong> scrolling checkbox list, these options are displayed as physical checkbox controls. By default the five checkboxes are uninitialized and won't be displayed, but if you assign a label to any of them they will be shown to the user.</p><p>When the <strong>Show</strong> method returns you can obtain the state of the checkboxes using the <strong>state</strong> property of each <a href="dialogoption"><strong>DialogOption</strong></a> object.</p></td></tr><tr><td>password</td><td><em>bool</em></td><td>In a text entry dialog, set this property to <strong>True</strong> to make the text entry field a password field. In a password field the characters the user enters are not displayed.</td></tr><tr><td>position</td><td><em>string</em></td><td><p>When used with a <a href="../../../scripting/script_dialogs">script dialog</a> this property lets you control the dialog's position on screen. Accepted values are:</p><table><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>center</strong></td><td>center the dialog over the parent window (the default)</td></tr><tr><td><strong>absolute</strong></td><td>specify an absolute position using the <strong>x</strong> and <strong>y</strong> properties</td></tr><tr><td><strong>parent</strong></td><td>position relative to the parent window (using <strong>x</strong> and <strong>y</strong>)</td></tr><tr><td><strong>monitor</strong></td><td>position relative to the current monitor (using <strong>x</strong> and <strong>y</strong>)</td></tr></tbody></table><p>Except when set to "center" the <strong>x</strong> and <strong>y</strong> properties can be used to adjust the dialog's position.</p></td></tr><tr><td></td><td></td><td></td></tr><tr><td><strong>center</strong></td><td>center the dialog over the parent window (the default)</td><td></td></tr><tr><td><strong>absolute</strong></td><td>specify an absolute position using the <strong>x</strong> and <strong>y</strong> properties</td><td></td></tr><tr><td><strong>parent</strong></td><td>position relative to the parent window (using <strong>x</strong> and <strong>y</strong>)</td><td></td></tr><tr><td><strong>monitor</strong></td><td>position relative to the current monitor (using <strong>x</strong> and <strong>y</strong>)</td><td></td></tr><tr><td>position_fix</td><td><em>bool</em></td><td>By default, Opus checks the size and position of your dialog just before it opens and fixing them if they would place any of the dialog off-screen. Positioning a dialog off-screen is usually an accident caused by saving window positions on one system and restoring them on another with different monitor resolutions or arrangements. In the rare cases where you want your dialog to open off-screen, where the user cannot see some of all of it, set this property to <strong>False</strong>.</td></tr><tr><td>result</td><td><em>int</em></td><td><p>This property returns the index of the button chosen by the user to close the dialog. The left-most button is index <strong>1</strong>, the next button is index <strong>2</strong>, and so on. If a dialog has more than one button then by definition the last (right-most) button is the "cancel" button and so this will return index <strong>0</strong>.</p><p>If any buttons have associated drop-down menus then the contents of the menus also contribute to the index value. For example, if button index 2 has an additional item in a drop-down menu, then that item would be index 3, and the next button would be index 4.</p></td></tr><tr><td>select</td><td><em>bool</em></td><td>In a text entry dialog, set this property to <strong>True</strong> to automatically select the contents of the input field (as specified by the <strong>defvalue</strong> property) when the dialog opens.</td></tr><tr><td>selection</td><td><em>int</em></td><td>In a drop-down list dialog (one with the <strong>choices</strong> property set without either <strong>list</strong> or <strong>menu</strong>), this property returns the index of the item chosen from the drop-down list after the <strong>Show</strong> method returns.</td></tr><tr><td>singleton</td><td><em>string</em></td><td>If you only want one instance of your dialog to be open at once, set this property to a unique name before creating the dialog. When the dialog is created, Opus will check if another dialog with same singleton name is already open. If it is, the existing dialog will be brought to the front and your script will receive a <strong>False</strong> return from the <code>Create</code> or <code>Show</code> methods. You should check for this an exit your script in that case.</td></tr><tr><td>sort</td><td><em>bool</em></td><td>Set this property to <strong>True</strong> if the list of choices given by the <strong>choices</strong> property should be sorted alphabetically.</td></tr><tr><td>state</td><td><em>string</em></td><td>Returns a string indicating the current state of the dialog. Possible values are "visible" (normal state, open and visible), "hidden" (dialog has been hidden), "min" (dialog is minimized), "max" (dialog is visible and maximized).</td></tr><tr><td>template</td><td><em>string</em></td><td>Lets you create a <a href="../../../scripting/script_dialogs">script dialog</a>. The <strong>template</strong> property can be set to the name of the script dialog to display (as defined in your script resources), or a string that contains raw XML defining the dialog.</td></tr><tr><td>title</td><td><em>string</em></td><td>Specifies the title text of the dialog.</td></tr><tr><td>top</td><td>bool</td><td>Set this property to <strong>True</strong> to make the dialog "top level", or <strong>False</strong> to allow it to go behind other non-top level windows.</td></tr><tr><td>want_close</td><td><em>bool</em></td><td>Set this property to <strong>True</strong> if you want the script dialog to generate close events in your message loop when the user clicks the window close button. You'll need to close the dialog yourself using the <strong>EndDlg</strong> method.</td></tr><tr><td>want_resize</td><td><em>bool</em></td><td>Set this property to <strong>True</strong> if you want the script dialog to generate <strong>resize</strong> events in your message loop when the user resizes the dialog.</td></tr><tr><td>window</td><td><em>object:</em><a href="lister"><strong>Lister</strong></a><br>or <em>object:</em><a href="tab"><strong>Tab</strong></a><br>or *object:*<strong>Dialog</strong><br>or <em>int</em></td><td><p>Use this to specify the parent window of the dialog. The dialog will appear centered over the top of the specified window. You can provide either a <a href="lister"><strong>Lister</strong></a> or a <a href="tab"><strong>Tab</strong></a> object, or another <strong>Dialog</strong>. If you are showing this dialog in response to the <a href="../scripting_events/onaboutscript"><strong>OnAboutScript</strong></a> event, you can also pass the value of the <a href="aboutdata"><strong>AboutData</strong></a><strong>.window</strong> property.</p><p>You only need to set this property if you obtain the <strong>Dialog</strong> option from the <a href="dopus"><strong>DOpus</strong></a><strong>.Dlg</strong> method. If the <strong>Dialog</strong> object comes from one of the other objects (e.g. <a href="tab"><strong>Tab</strong></a><strong>.Dlg</strong>) then its parent window will already be set to the window which launched the action your script is responding to.</p></td></tr><tr><td>x</td><td><em>int</em></td><td>Specifies the x-position of a <a href="../../../scripting/script_dialogs">script dialog</a>. Use the <strong>position</strong> property to control how the position is interpreted. After the dialog has been displayed you can change this property to move the dialog around on-screen.</td></tr><tr><td>y</td><td><em>int</em></td><td>Specifies the y-position of a <a href="../../../scripting/script_dialogs">script dialog</a>. Use the <strong>position</strong> property to control how the position is interpreted. After the dialog has been displayed you can change this property to move the dialog around on-screen.</td></tr></tbody></table>

| Method Name          | **Arguments**                                                                                                                                                                    | Return Type                                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |   |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| AddCustomMsg         | <p>&#x3C;string:name><br>[&#x3C;bool:force>]</p>                                                                                                                                 | _bool_                                                                   | <p>Lets a script dialog register one or more custom messages that can then be sent to it from other scripts.</p><p>Messages are registered by name. If a message is already registered the method will fail unless you set the optional <em>force</em> parameter to true.</p><p>Use <a href="dopus"><strong>DOpus</strong></a><strong>.SendCustomMsg</strong> to send messages to dialogs. The dialog will receive a "custom" <a href="msg"><strong>Msg</strong></a> in their message loop.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| AddHotkey            | <p>&#x3C;string:name><br>&#x3C;string:key></p>                                                                                                                                   | _bool_                                                                   | <p>Creates a hotkey (or keyboard accelerator) for the specified key combination. When the user presses this key combination in your dialog, a <strong>hotkey</strong> event will be triggered.</p><p>The name parameter is a name you assign that lets you identify the hotkey. The key parameter specified the actual key combination; this can optionally combine the qualifiers <strong>ctrl</strong>, <strong>shift</strong> and <strong>alt</strong> with a character or name of a special key. For example, <strong>ctrl+t</strong> or <strong>alt+shift+F7</strong>.</p><p>This method returns true if successful, or false on failure (e.g. if the hotkey already exists).</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |   |
| AutoSize             | _none_                                                                                                                                                                           | _none_                                                                   | If a dialog has auto-sizing controls that depend on the sizes of other controls, and you make changes to their sizes at runtime, you can call this method to force the dialog to recalculate all relative control sizes once you've made the required changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |   |
| CancelWatchClipboard | _none_                                                                                                                                                                           | _none_                                                                   | Cancels monitoring of the system clipboard for changes previously established by a call to the **WatchClipboard** method.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |   |
| CancelWatchDir       | \<string:id>                                                                                                                                                                     | _none_                                                                   | Cancels folder or file change monitoring previously established by a call to the **WatchDir** method. The **id** parameter is the ID you assigned to your watcher when it was created.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |   |
| Create               | _none_                                                                                                                                                                           | _none_                                                                   | <p>When creating a <a href="../../../scripting/script_dialogs">script dialog</a>, calling this method creates the underlying dialog but does not display it. This lets you create the dialog and then initialize its controls before it is shown to the user.</p><p>Using <strong>Create</strong> implies a <a href="../../../scripting/script_dialogs/the_dialog_message_loop/detached_dialogs">detached dialog</a>; the <strong>detach</strong> property will be set <strong>True</strong> automatically. However, you can call <strong>RunDlg</strong> afterwards if you don't need a custom message loop and just want to set up some controls before displaying the dialog.</p><p>Once the dialog has been created and its controls initialized, you should call <strong>Show</strong> or <strong>RunDlg</strong> to make it visible to the user. It will also go visible at the first <strong>GetMsg</strong> call if it hasn't already been shown.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |   |
| CreateFont           | <p>&#x3C;string:name><br>[&#x3C;int:size>]<br>[&#x3C;string:styles>]</p>                                                                                                         | _int_                                                                    | <p>Creates a font object that can be given to dialog controls to make them use a non-standard font. The <em>name</em> parameter specifies the name of the font (e.g. "Arial") - you can also use "*" which means the default dialog font. The <em>size</em> parameter specifies the desired point size (use 0 to get the default dialog font size). The <em>styles</em> string can consist of one or more characters indicating the desired font style - "b" for bold, "i" for italic, "u" for underline.</p><p>The return value can be used with the <a href="control"><strong>Control</strong></a><strong>.SetFont</strong> method.</p><p>Fonts you create are automatically destroyed when the dialog closes but if you want to delete them manually to free up resources, use the <strong>DestroyFont</strong> method.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |   |
| Control              | <p>&#x3C;string:name><br>[&#x3C;string:dialog>]<br>[&#x3C;string:tab>]</p>                                                                                                       | _object:_[**Control**](control)                                          | <p>Returns a <a href="control"><strong>Control</strong></a> object corresponding to one of the controls on a script dialog. The control is identified by its <em>name</em>, as defined in the script dialog resource.</p><p>The optional second and third parameters are only used when the control is in a <em>tab control</em> (that is, when it's in a dialog that's a child of another dialog). The <em>dialog</em> parameter specifies the name of its parent dialog. The <em>tab</em> parameter specifies the name of the tab control hosting the child dialog. You would only need to specify the name of the tab if you have multiple tab controls and the same dialog is hosted inside more than one of them (this would be quite a rare occurrence).</p><p>Note that none of the controls will exist until <strong>Create</strong> has been called.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |   |
| DelHotkey            | \<string:name>                                                                                                                                                                   | _bool_                                                                   | <p>Deletes a hotkey you previously created with the <strong>AddHotkey</strong> method.</p><p>This method returns true if successful, or false on failure (e.g. if the hotkey does not exist).</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |   |
| Drag                 | <p><em>object:</em><a href="items"><strong>Items</strong></a><br>&#x3C;string:actions></p>                                                                                       | _string_                                                                 | <p>Allows the user to drag and drop one or more files from your dialog (and drop them in another window or application).</p><p>You would usually call this in response to a <strong>drag</strong> event you receive from a <strong>static</strong> or list view control.</p><p>The first parameter is an <a href="items"><strong>Items</strong></a> object representing the files to be dragged. (You can also pass a <a href="vector"><strong>Vector</strong></a> of <a href="item"><strong>Item</strong></a> or <a href="path"><strong>Path</strong></a> objects, or full path strings, instead of an <a href="items"><strong>Items</strong></a> object. Or a <a href="stringset"><strong>StringSet</strong></a> or <a href="unorderedset"><strong>UnorderedSet</strong></a> of full path strings.)</p><p>The optional second parameter lets you control which actions are available. This should be a string containing one or more of <strong>copy</strong>, <strong>move</strong>, <strong>link</strong>. The default action can be indicated by prefixing it with a * (e.g. <strong>copy,*move,link</strong>). If you don't specify this parameter the default is to only allow <strong>copy</strong>.</p><p>The string this method returns indicates the result of the drag. For a left button drag, this will be "copy", "move", "link" or "drop". For a right-button drag it will always be "drop". If the drag is cancelled it will return "cancel".</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |   |
| DestroyFont          | \<int:id>                                                                                                                                                                        | _none_                                                                   | Destroys the specified font using the ID that was returned by the **CreateFont** method.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |   |
| EndDlg               | \<int:result>                                                                                                                                                                    | _none_                                                                   | Ends a [script dialog](../../../scripting/script_dialogs) running in detached mode. Normally dialogs end automatically when the user clicks the close button or another button that has its **Close Dialog** property set to **True**. This method lets you end a dialog under script control. The optional parameter specifies the result code that the **Dialog.result** property will return.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |   |
| Folder               | <p>&#x3C;string:title><br>&#x3C;string:default><br>&#x3C;bool:expand><br>&#x3C;object:window></p>                                                                                | _object:_[**Path**](path)                                                | <p>Displays a "Browse for Folder" dialog letting the user select a folder. The optional parameters are:</p><ul><li><em>title</em> - specify title of the dialog</li><li><em>default</em> - specify the default path selected in the dialog</li><li><em>expand</em> - specify <strong>True</strong> to automatically expand the initial path</li><li><em>window</em> - specify parent window for the dialog (a <a href="lister"><strong>Lister</strong></a> or a <a href="tab"><strong>Tab</strong></a>). If not specified, the <strong>Dialog</strong> object's <strong>window</strong> property will be used.</li></ul><p>A <a href="path"><strong>Path</strong></a> object is returned to indicate the folder chosen by the user. This object will have an additional <strong>result</strong> property that will be <strong>False</strong> if the user cancelled the dialog - the other normal <strong>Path</strong> properties will only be valid if <strong>result</strong> is <strong>True</strong>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |   |
| FlushMsg             | _none_                                                                                                                                                                           | _int_                                                                    | Flushes the dialog's message queue. Any unretrieved messages will be discarded. The return value tells you how many messages were in the queue.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| GetMsg               | _none_                                                                                                                                                                           | _object:_[**Msg**](msg)                                                  | <p>Returns a <a href="msg"><strong>Msg</strong></a> object representing the most recent input event in a <a href="../../../scripting/script_dialogs">script dialog</a> (only used in <a href="../../../scripting/script_dialogs/the_dialog_message_loop/detached_dialogs">detached mode</a>).</p><p>The return value will evaluate to <strong>False</strong> when the dialog is closed, which is when you should exit your <a href="../../../scripting/script_dialogs/the_dialog_message_loop">message loop</a>.</p><p>If the dialog is not already visible (because <strong>Show</strong> has not been called) then it will become visible when you first call <strong>GetMsg</strong>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |   |
| GetString            | <p>&#x3C;string:message><br>&#x3C;string:default><br>&#x3C;string:max><br>&#x3C;string:buttons><br>&#x3C;string:title><br>&#x3C;object:window><br>&#x3C;byref string:result></p> | _string_                                                                 | <p>Displays a text entry dialog allowing the user to enter a string. The optional parameters are:</p><ul><li><em>message</em> - specify message string in the dialog</li><li><em>default</em> - specify default string value</li><li><em>max</em> - specify maximum string length</li><li><em>buttons</em> - specify button labels (in the same format as the <strong>buttons</strong> property described above)</li><li><em>title</em> - specify dialog window title</li><li><em>window</em> - specify parent window for the dialog (a <a href="lister"><strong>Lister</strong></a> or a <a href="tab"><strong>Tab</strong></a>). If not specified, the <strong>Dialog</strong> object's <strong>window</strong> property will be used.</li><li><em>result</em> - for scripting languages that support <em>ByRef</em> parameters, this can specify a variable to receive the string the user enters.</li></ul><p>The return value is the entered string, or an empty value if the dialog was cancelled. The index of the button selected by the user will be available via the <strong>result</strong> property once this method returns. The left-most button is index <strong>1</strong>, the next button is index <strong>2</strong>, and so on. If a dialog has more than one button then by definition the last (right-most) button is the "cancel" button and so this will return index <strong>0</strong>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |   |
| KillTimer            | \<string:name>                                                                                                                                                                   | _none_                                                                   | Stops the specified timer. The timer must previously have been created by a call to the **SetTimer** method.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |   |
| LoadPosition         | <p>&#x3C;string:id><br>&#x3C;string:type></p>                                                                                                                                    | _none_                                                                   | <p>Restores the previously saved position of a <a href="../../../scripting/script_dialogs">script dialog</a>. The position must have previously been saved by a call to the <strong>SavePosition</strong> method.</p><p>The <strong>id</strong> string is a string that Opus can use to identify your dialog or the script it comes from. The template name of the dialog will be automatically appended to this. For example, you might specify <strong>id</strong> as <em>"kundal"</em> - Opus would then internally save the position of a dialog called <em>"dialog1"</em> as <em>"kundal!dialog1"</em>. Make sure you pick a string that other script authors are unlikely to use as Opus has no other way of telling the saved positions apart.</p><p>The optional type parameter lets you control which position elements are restored - specify <em>"pos"</em> to only restore the position, <em>"size"</em> to only restore the size, or <em>"pos,size"</em> to restore both (this is also the default, so you can also omit the argument all together).</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |   |
| Multi                | <p>&#x3C;string:title><br>&#x3C;string:default><br>&#x3C;object:window><br>&#x3C;string:type></p>                                                                                | _object:_[**Items**](items)                                              | <p>Displays a "Browse to Open File" dialog that lets the user select one or more files. The optional parameters are:</p><ul><li><em>title</em> - specify title of the dialog</li><li><em>default</em> - specify the default file selected in the dialog (if a folder is specified this specifies the default location but no file will be selected)</li><li><em>window</em> - specify parent window for the dialog (a <a href="lister"><strong>Lister</strong></a> or a <a href="tab"><strong>Tab</strong></a>). If not specified, the <strong>Dialog</strong> object's <strong>window</strong> property will be used. (Omit the <em>window</em> argument entirely if you don't want to use it; the <em>type</em> argument, if used, works whether third or fourth.)</li><li><em>type</em> - A list of filetypes to populate the "Save as Type" dropdown in the save dialog. (See below.)</li></ul><p>The optional <em>type</em> parameter consists of one or more pairs of strings, separated by exclamation marks (<strong>!</strong>). The first string of each pair is the plain text string shown in the drop-down, and the second string of each pair is the actual file extension. You can also specify multiple extensions for the one type by separating them with semicolon. If you want the default "All files" item to be added to the list, add a <strong>#</strong> character at the start of the string. For example, <em>#Text Files!*.txt!Doc Files!*.doc.</em></p><p>An <a href="items"><strong>Items</strong></a> object is returned to indicate the files selected by the user. The returned object will have a <strong>result</strong> property that you should check first - the collection of items is only valid if <strong>result</strong> returns <strong>True</strong>. If it returns <strong>False</strong> it means the user cancelled the dialog.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |   |
| NewHTTPReq           | _none_                                                                                                                                                                           | _object:_[**HTTPRequest**](httprequest)                                  | <p>Creates a new <a href="httprequest">HTTPRequest</a> object attached to this dialog. This object provides a simple way to send an HTTP request to a server asynchronously, and retrieve the response.</p><p>Events from HTTP requests will come through your dialog's message loop, so you must use a detached dialog in order to use this functionality.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| NotifyIcon           | <p>&#x3C;string:method><br><em>arguments...</em></p>                                                                                                                             | _none_                                                                   | <p>Allows a script to add an icon to the system taskbar notification area.</p><p>The <em>method</em> argument specifies one of four actions, each of which has its own set of arguments.</p><table><thead><tr><th>method</th><th>Arguments</th><th>Description</th></tr></thead><tbody><tr><td><strong>add</strong></td><td>&#x3C;icon>,<br>&#x3C;tooltip></td><td>Add icon to the toolbar.</td></tr><tr><td><strong>update</strong></td><td>&#x3C;icon>,<br>&#x3C;tooltip></td><td>Updates icon or tooltip.</td></tr><tr><td><strong>remove</strong></td><td><em>none</em></td><td>Removes the icon.</td></tr><tr><td><strong>notify</strong></td><td>&#x3C;title>,<br>&#x3C;message>,<br>&#x3C;flags></td><td>Displays a system notification message (or bubble tooltip in Windows 7).</td></tr></tbody></table><p>For the <strong>add</strong> and <strong>update</strong> methods, the <em>icon</em> argument can be a string or <a href="image"><strong>Image</strong></a> object - see the documentation for the <strong>icon</strong> property above for more details. If the dialog has been assigned an icon via this property then that icon will be used automatically if none is provided.</p><p>The <em>tooltip</em> argument provides a tooltip string that the system will display when the user moves the mouse over the icon. If the dialog's <strong>title</strong> property has been set then the title will be used if no explicit tooltip is given.</p><p>The <strong>notify</strong> method lets you show a system notification associated with your dialog. This method is similar to the <a href="dopus"><strong>DOpus</strong></a><strong>.Notify</strong> method - see the description of that method for more information on the arguments.</p><p>Once your script has added an icon, the user can interact with it using the mouse. Mouse activity will generate <strong>click</strong>, <strong>dblclk</strong> and <strong>rclick</strong> events in your dialog's message loop. The <a href="msg"><strong>Msg</strong></a><strong>.control</strong> property will be set to <strong>notifyicon</strong>.</p><p>The icon is automatically removed when your dialog closes. It's also restored automatically if Explorer restarts after the icon has been added.</p><p>Please note that only one icon per dialog is supported.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| method               | Arguments                                                                                                                                                                        | Description                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **add**              | <p>&#x3C;icon>,<br>&#x3C;tooltip></p>                                                                                                                                            | Add icon to the toolbar.                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **update**           | <p>&#x3C;icon>,<br>&#x3C;tooltip></p>                                                                                                                                            | Updates icon or tooltip.                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **remove**           | _none_                                                                                                                                                                           | Removes the icon.                                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **notify**           | <p>&#x3C;title>,<br>&#x3C;message>,<br>&#x3C;flags></p>                                                                                                                          | Displays a system notification message (or bubble tooltip in Windows 7). |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| Open                 | <p>&#x3C;string:title><br>&#x3C;string:default><br>&#x3C;object:window><br>&#x3C;string:type></p>                                                                                | _object:_[**Item**](item)                                                | <p>Displays a "Browse to Open File" dialog that lets the user select a single file. The optional parameters are:</p><ul><li><em>title</em> - specify title of the dialog</li><li><em>default</em> - specify the default file selected in the dialog (if a folder is specified this specifies the default location but no file will be selected)</li><li><em>window</em> - specify parent window for the dialog (a <a href="lister"><strong>Lister</strong></a> or a <a href="tab"><strong>Tab</strong></a>). If not specified, the <strong>Dialog</strong> object's <strong>window</strong> property will be used. (Omit the <em>window</em> argument entirely if you don't want to use it; the <em>type</em> argument, if used, works whether third or fourth.)</li><li><em>type</em> - A list of filetypes to populate the "Save as Type" dropdown in the save dialog. (See below.)</li></ul><p>The optional <em>type</em> parameter consists of one or more pairs of strings, separated by exclamation marks (<strong>!</strong>). The first string of each pair is the plain text string shown in the drop-down, and the second string of each pair is the actual file extension. You can also specify multiple extensions for the one type by separating them with semicolon. If you want the default "All files" item to be added to the list, add a <strong>#</strong> character at the start of the string. For example, <em>#Text Files!*.txt!Doc Files!*.doc.</em></p><p>A single <a href="item"><strong>Item</strong></a> object is returned to indicate the file selected by the user. This object will have an additional <strong>result</strong> property that will be <strong>False</strong> if the user cancelled the dialog - the other normal <strong>Item</strong> properties will only be valid if <strong>result</strong> is <strong>True</strong>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |   |
| Request              | <p>&#x3C;string:message><br>&#x3C;string:buttons><br>&#x3C;string:title><br>&#x3C;object:window></p>                                                                             | _int_                                                                    | <p>Displays a dialog with one or more buttons. The optional parameters are:</p><ul><li><em>message</em> - specify message string in the dialog</li><li><em>buttons</em> - specify button labels (in the same format as the <strong>buttons</strong> property described above)</li><li><em>title</em> - specify dialog window title</li><li><em>window</em> - specify parent window for the dialog (a <a href="lister"><strong>Lister</strong></a> or a <a href="tab"><strong>Tab</strong></a>). If not specified, the <strong>Dialog</strong> object's <strong>window</strong> property will be used.</li></ul><p>The return value is the index of the button selected by the user, and this is also available in the <strong>result</strong> property once the method returns. The left-most button is index <strong>1</strong>, the next button is index <strong>2</strong>, and so on. If a dialog has more than one button then by definition the last (right-most) button is the "cancel" button and so this will return index <strong>0</strong>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |   |
| RunDlg               | _none_                                                                                                                                                                           | _int_                                                                    | <p>Turns a previously <a href="../../../scripting/script_dialogs/the_dialog_message_loop/detached_dialogs">detached dialog</a> into a non-detached one, by taking over and running the default message loop. The <strong>RunDlg</strong> method won't return until the dialog has closed. You might use this if you created a dialog using <strong>Create</strong>, in order to initialize its controls, but don't actually want to run an interactive message loop.</p><p>The return value is the same as the object's <strong>result</strong> property, and represents the index of the close button selected by the user.</p><p>If the dialog is not already visible (because neither <strong>Show</strong> nor <strong>GetMsg</strong> were called) then it will become visible when you call <strong>RunDlg</strong>. (Compatibility note: Prior to Opus 12.22, scripts needed to call <strong>Show</strong> explicitly.)</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |   |
| Save                 | <p>&#x3C;string:title><br>&#x3C;string:default><br>&#x3C;object:window><br>&#x3C;string:type></p>                                                                                | _object:_[**Path**](path)                                                | <p>Displays a "Browse to Save File" dialog that lets the user select a single file or enter a new filename to save. The optional parameters are:</p><ul><li><em>title</em> - The dialog's title.</li><li><em>default</em> - The default file selected in the dialog. (If a folder is given, it sets the dialog's starting location, but no file will be selected.)</li><li><em>window</em> - The dialog's parent window (a <a href="lister"><strong>Lister</strong></a> or a <a href="tab"><strong>Tab</strong></a>). If not specified, the <strong>Dialog</strong> object's <strong>window</strong> property will be used. (Omit the <em>window</em> argument entirely if you don't want to use it; the <em>type</em> argument, if used, works whether third or fourth.)</li><li><em>type</em> - A list of filetypes to populate the "Save as Type" dropdown in the save dialog. (See below.)</li></ul><p>The optional <em>type</em> parameter consists of one or more pairs of strings, separated by exclamation marks (<strong>!</strong>). The first string of each pair is the plain text string shown in the drop-down, and the second string of each pair is the actual file extension. You can also specify multiple extensions for the one type by separating them with semicolon. If you want the default "All files" item to be added to the list, add a <strong>#</strong> character at the start of the string. For example, <em>#Text Files!*.txt!Doc Files!*.doc.</em></p><p>A <a href="path"><strong>Path</strong></a> object is returned to indicate the file chosen by the user. This object will have an additional <strong>result</strong> property that will be <strong>False</strong> if the user cancelled the dialog, and the other normal <strong>Path</strong> properties will only be valid if <strong>result</strong> is <strong>True.</strong></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| SavePosition         | \<string:id>                                                                                                                                                                     | _none_                                                                   | <p>Saves the position (and size) of the dialog to your Opus configuration. The position can then be restored later on by a call to <strong>LoadPosition</strong>.</p><p>Normally you would call <strong>LoadPosition</strong> before displaying your dialog, and <strong>SavePosition</strong> after the dialog has been closed.</p><p>The <strong>id</strong> string is a string that Opus can use to identify your dialog or the script it comes from. The template name of the dialog will be automatically appended to this. For example, you might specify <strong>id</strong> as <em>"kundal"</em> - Opus would then internally save the position of a dialog called <em>"dialog1"</em> as <em>"kundal!dialog1"</em>. Make sure you pick a string that other script authors are unlikely to use as Opus has no other way of telling the saved positions apart.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |   |
| SetTimer             | <p>&#x3C;int:period><br>&#x3C;string:name></p>                                                                                                                                   | _string_                                                                 | <p>Creates a timer that will generate a periodic <strong>timer</strong> event for your script. The <strong>period</strong> must be specified in milliseconds (e.g. 1000 would equal one second).</p><p>You can optionally specify a <strong>name</strong> for the timer - if you don't provide a name, one will be generated automatically (and the name of the new timer will be returned).</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |   |
| Show                 | _none_                                                                                                                                                                           | _int_                                                                    | <p>Displays the dialog that has been pre-configured using the various properties of this object. See the properties section above for a full description of these.</p><p>If the <strong>detach</strong> property is <strong>False</strong>, the call will not return until the dialog has been closed. The return value is the index of the button selected by the user, and this is also available in the <strong>result</strong> property once the method returns. The left-most button is index <strong>1</strong>, the next button is index <strong>2</strong>, and so on. If a dialog has more than one button then by definition the last (right-most) button is the "cancel" button and so this will return index <strong>0</strong>.</p><p>If the <strong>detach</strong> property is <strong>True</strong>, the call will return immediately and the return value is meaningless. You should then either run a message loop for the “detached” dialog, or call <strong>RunDlg</strong> to run the standard loop.</p><p>Note that calling <strong>Create</strong> implicitly sets the <strong>detach</strong> property to <strong>True</strong>. If you need to create the dialog to modify some of its controls before it is displayed, but do not want to run your own message loop once it is displayed, you should call <strong>RunDlg</strong> rather than <strong>Show</strong>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |   |
| SetTaskbarGroup      | \<string:group>                                                                                                                                                                  | _bool_                                                                   | <p>Used to change how custom dialogs are grouped with other Opus windows on the taskbar. Specify a group name to move the window into an alternative group, or omit the group argument to reset back to the default group. If one or more windows are moved into the same group, they will be grouped together, separate from other the default group.</p><p>This only works on Windows 7 and above, and only when taskbar grouping is enabled. Group names are limited to 103 characters and will be truncated if longer. Spaces and dots in group names are automatically converted to underscores.</p><p>Only works with custom script dialogs (i.e. when you are using the <strong>template</strong> property). Must be called after the dialog has been created (i.e. after <strong>Show</strong> has been called -- see the <strong>RunDlg</strong> method if you want to avoid writing your own message loop just for this).<br>Returns true on success.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |   |
| Vars                 | \<string:id>                                                                                                                                                                     | _object:_[**Vars**](vars)                                                | <p>Returns a <a href="vars"><strong>Vars</strong></a> object that represents the variables that are scoped to this particular dialog. This allows scripts to use variables that persist from one use of the dialog to another.</p><p>The <strong>id</strong> string is a string that Opus can use to identify your dialog or the script it comes from. The template name of the dialog will be automatically appended to this. For example, you might specify <strong>id</strong> as <em>"kundal"</em> - Opus would then internally save these variables for a dialog called <em>"dialog1"</em> as <em>"kundal!dialog1"</em>. Make sure you pick a string that other script authors are unlikely to use as Opus has no other way of telling the saved variables apart.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |   |
| WatchClipboard       | _none_                                                                                                                                                                           | _bool_                                                                   | <p>Establish monitoring of the system clipboard. Whenever the system clipboard contents change, the dialog's message loop receives a <strong>clipboard</strong> event.</p><p>Use the <strong>CancelWatchClipboard</strong> method to cancel monitoring.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |   |
| WatchDir             | <p>&#x3C;string:id><br>&#x3C;string:path><br>&#x3C;string:flags></p>                                                                                                             | _int_                                                                    | <p>Establish monitoring of a folder or file for changes. Returns <strong>0</strong> for success or an error code on failure.</p><p>The <strong>id</strong> argument lets you provide an ID for this watcher that's used to identify it when changes occur. <strong>dir</strong> is the full path to a filesystem folder, or a file if the <strong>i</strong> flag is set.</p><p>The optional flags are:</p><table><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>f</strong></td><td>monitor for file change in folder (e.g. file created)</td></tr><tr><td><strong>d</strong></td><td>monitor for directory change in folder (e.g. directory created)</td></tr><tr><td><strong>r</strong></td><td>recursive - monitor sub-folders</td></tr><tr><td><strong>a</strong></td><td>monitor for file attribute changes</td></tr><tr><td><strong>s</strong></td><td>monitor for file size changes</td></tr><tr><td><strong>w</strong></td><td>monitor for last write time changes</td></tr><tr><td><strong>i</strong></td><td>monitor a single file rather than a folder</td></tr></tbody></table><p>When a change occurs to a monitored file or folder, the dialog's message loop receives a <strong>dirchange</strong> event. The <a href="msg"><strong>Msg</strong></a><strong>.control</strong> property identifies the watcher's ID.</p><p>Use the <strong>CancelWatchDir</strong> method to cancel monitoring.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |   |
|                      |                                                                                                                                                                                  |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **f**                | monitor for file change in folder (e.g. file created)                                                                                                                            |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **d**                | monitor for directory change in folder (e.g. directory created)                                                                                                                  |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **r**                | recursive - monitor sub-folders                                                                                                                                                  |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **a**                | monitor for file attribute changes                                                                                                                                               |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **s**                | monitor for file size changes                                                                                                                                                    |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **w**                | monitor for last write time changes                                                                                                                                              |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **i**                | monitor a single file rather than a folder                                                                                                                                       |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| WatchTab             | <p>&#x3C;object:<a href="tab"><strong>Tab</strong></a>><br>&#x3C;string:events><br>&#x3C;string:id></p>                                                                          | _bool_                                                                   | <p>Allows a <a href="../../../scripting/script_dialogs">script dialog</a> to monitor events in a folder tab. You will receive notifications of the requested events through your message loop.</p><p>The <strong>tab</strong> parameter specifies the <a href="tab"><strong>Tab</strong></a> you want to watch. The <strong>events</strong> string is a comma-separated list of events you want to watch for. The <strong>id</strong> string is an optional parameter; it lets you assign your own ID to the tab to make it easier to tell where events are coming from (if you're monitoring multiple tabs, for instance).</p><p>These are the events you can watch for. Note that some are equivalent to the existing script events (e.g. <strong>OnActivateTab</strong>):</p><table><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>select</strong></td><td>items in the tab are selected or deselected</td></tr><tr><td><strong>navigate</strong></td><td>the folder is changed in the tab</td></tr><tr><td><strong>add</strong></td><td>items are added to the folder</td></tr><tr><td><strong>delete</strong></td><td>items are deleted from the folder</td></tr><tr><td><strong>change</strong></td><td>items in the folder are changed (size, date, name, etc)</td></tr><tr><td><strong>activate</strong></td><td>tab activated or deactivated</td></tr><tr><td><strong>srcdst</strong></td><td>source/destination state changed</td></tr><tr><td><strong>view</strong></td><td>view mode changed</td></tr><tr><td><strong>flat</strong></td><td>flat view state changed</td></tr><tr><td><strong>filter</strong></td><td>quick filter changed</td></tr></tbody></table><p>Once notification has been established you will be notified of all requested events when they occur. Note that no specific information is sent with notifications - e.g. for the "change" event, you aren't told which items have changed, only that something has.</p><p>You will receive notification events in your message loop. The various properties of the <a href="msg"><strong>Msg</strong></a> object let you determine what happened.</p><p>The <a href="msg"><strong>Msg</strong></a><strong>.event</strong> property will be set to <strong>tab</strong> for notifications from a watched folder tab.</p><p>The <a href="msg"><strong>Msg</strong></a><strong>.control</strong> property tells you which tab the change occurred in; if you specified an ID when you called the <strong>WatchTab</strong> function, this will be in the <a href="msg">Msg</a><strong>.control</strong> property - otherwise, it will be the numeric handle of the tab. Note that it's *not* the actual <a href="tab"><strong>Tab</strong></a> object. You can access the <a href="tab"><strong>Tab</strong></a> object via the <a href="msg">Msg</a><strong>.tab</strong> property but this can be inefficient, as it requires a new <a href="tab"><strong>Tab</strong></a> object to be created every time. If you're only monitoring one tab it's better to store the <a href="tab"><strong>Tab</strong></a> object in your own variable - and if you're monitoring multiple tabs you could, e.g. use a unique ID for each one and keep the objects in a <a href="map"><strong>Map</strong></a>.</p><p>The <a href="msg"><strong>Msg</strong></a><strong>.value</strong> property tells you which notification event occurred. Possible values are <strong>select</strong>, <strong>navigate</strong>, <strong>filechange</strong>, <strong>activate</strong>, <strong>srcdst</strong>, <strong>view</strong>, <strong>flat</strong>, <strong>filter</strong> and <strong>close</strong> (sent if the tab is closed while you are monitoring it).</p><p>For the <strong>filechange</strong> event, the <a href="msg"><strong>Msg</strong></a><strong>.data</strong> property contains a bit mask indicating which file events occurred. <strong>1</strong> = add, <strong>2</strong> = delete, <strong>4</strong> = change. The values will be added together (so e.g. <strong>6</strong> indicates at least one item was changed and at least one was deleted). It's up to your script to determine exactly what changed.</p><p>You can change the events you're monitoring for by calling the <strong>WatchTab</strong> method again with the same tab and new event list.</p><p>To stop monitoring an existing tab, call <strong>WatchTab</strong> with the second parameter set to <strong>stop</strong>. Monitoring is automatically cancelled if your dialog closes (and also if the tab closes).</p> |   |
|                      |                                                                                                                                                                                  |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **select**           | items in the tab are selected or deselected                                                                                                                                      |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **navigate**         | the folder is changed in the tab                                                                                                                                                 |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **add**              | items are added to the folder                                                                                                                                                    |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **delete**           | items are deleted from the folder                                                                                                                                                |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **change**           | items in the folder are changed (size, date, name, etc)                                                                                                                          |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **activate**         | tab activated or deactivated                                                                                                                                                     |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **srcdst**           | source/destination state changed                                                                                                                                                 |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **view**             | view mode changed                                                                                                                                                                |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **flat**             | flat view state changed                                                                                                                                                          |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **filter**           | quick filter changed                                                                                                                                                             |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| WindowCmd            | \<string:command>                                                                                                                                                                | _none_                                                                   | <p>Sends a command to the dialog window to change how it's displayed. Possible commands are:</p><table><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>min</strong></td><td>minimize the window</td></tr><tr><td><strong>max</strong></td><td>maximize the window</td></tr><tr><td><strong>restore</strong></td><td>restore the window (from minimize/maximize)</td></tr><tr><td><strong>show</strong></td><td>show the window if it's currently hidden</td></tr><tr><td><strong>showna</strong></td><td>show the window but don't activate it</td></tr><tr><td><strong>hide</strong></td><td>hide the window</td></tr><tr><td><strong>front</strong></td><td>activate the window and bring it to the front</td></tr><tr><td></td><td></td></tr><tr><td></td><td></td></tr><tr><td></td><td></td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |   |
|                      |                                                                                                                                                                                  |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **min**              | minimize the window                                                                                                                                                              |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **max**              | maximize the window                                                                                                                                                              |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **restore**          | restore the window (from minimize/maximize)                                                                                                                                      |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **show**             | show the window if it's currently hidden                                                                                                                                         |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **showna**           | show the window but don't activate it                                                                                                                                            |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **hide**             | hide the window                                                                                                                                                                  |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
| **front**            | activate the window and bring it to the front                                                                                                                                    |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
|                      |                                                                                                                                                                                  |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
|                      |                                                                                                                                                                                  |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
|                      |                                                                                                                                                                                  |                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |   |
