buttons

string

Specifies the buttons that are displayed at the bottom of the dialog. These buttons are used to close the dialog. The Show method returns a value indicating which button was chosen (and this value is also available in the result property).

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:

dlg.buttons = "OK|Retry|Cancel"

To specify accelerators for the buttons prefix the desired key with an ampersand (&) character. For example:

dlg.buttons = "&OK|&Retry|&Cancel"

Buttons can also have drop-down menus attached to them, by separating the drop-down items with plus signs (+). For example:

dlg.buttons = "OK|Retry+Retry All|Cancel"

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:

dlg.buttons = "OK|Retry+Retry All=Retry All|Skip+Skip if same modified time=Skip Same Time|Cancel"

confirm

bool

In a text entry dialog (i.e. the max property has been specified) setting confirm to True will require that the user types the entered text again (in a second text field) to confirm it (e.g. for a password).

cy

int

For script dialogs 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.

defid

int

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 defid of 1. The second button would have a defid 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 defid of 0.

disable_window

object:Lister
or object:Tab 
or object:Dialog\\ or int

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 window property.

You can provide either a Lister or a Tab object, or another Dialog. If you are showing this dialog in response to the OnAboutScript event, you can also pass the value of the AboutData.window property.

input

string

In a text entry dialog, this property returns the text string that the user entered (i.e. once the Show method has returned).

list

object:Vector(bool)
or array(bool)\\ or int

In conjunction with the choices property, this will cause the choices to be presented as a checkbox list. You can initialize this Vector or array with the same number of items as the choices property, and set each one to True or False 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.

When the Show method returns, this property will return a Vector of bools that provide the state of each checkbox as set by the user.

menu

object:Vector(int)
or array(int)
or int

In conjunction with the choices 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.

You can initialize this Vector 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.

You can also simply set this value to 0 or 1 to activate the popup menu without having to provide flags for each item (if set to 1, the top item in the menu will appear bolded).

The Show method returns the index of the menu item the user chose (with 1 being the first item), or 0 if the menu was cancelled.

msgonly

bool

Set to True before creating the dialog to create a message-only dialog. A message-only dialog will never be visible, but still runs a normal message loop. This lets you use things like WatchTab or HTTPRequest 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.

options

collection:DialogOption 

This is a collection of five options that will be displayed as checkboxes in the dialog. Unlike the choices / list 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.

When the Show method returns you can obtain the state of the checkboxes using the state property of each DialogOption object.

position

string

When used with a script dialog this property lets you control the dialog's position on screen. Accepted values are:

Except when set to "center" the x and y properties can be used to adjust the dialog's position. 

result

int

This property returns the index of the button chosen by the user to close the dialog. The left-most button is index 1, the next button is index 2, 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 0.

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.

selection

int

In a drop-down list dialog (one with the choices property set without either list or menu), this property returns the index of the item chosen from the drop-down list after the Show method returns.

sort

bool

Set this property to True if the list of choices given by the choices property should be sorted alphabetically.

template

string

Lets you create a script dialog. The template 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.

top

bool

Set this property to True to make the dialog "top level", or False to allow it to go behind other non-top level windows.

want_resize

bool

Set this property to True if you want the script dialog to generate resize events in your message loop when the user resizes the dialog.

x

int

Specifies the x-position of a script dialog. Use the position 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.

AddCustomMsg

<string:name>
[<bool:force>]

bool

Lets a script dialog register one or more custom messages that can then be sent to it from other scripts.

Messages are registered by name. If a message is already registered the method will fail unless you set the optional force parameter to true.

Use DOpus.SendCustomMsg to send messages to dialogs. The dialog will receive a "custom" Msg in their message loop.

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.

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.

CreateFont

<string:name>
[<int:size>]
[<string:styles>]

int

Creates a font object that can be given to dialog controls to make them use a non-standard font. The name parameter specifies the name of the font (e.g. "Arial") - you can also use "*" which means the default dialog font. The size parameter specifies the desired point size (use 0 to get the default dialog font size). The styles string can consist of one or more characters indicating the desired font style - "b" for bold, "i" for italic, "u" for underline.

The return value can be used with the Control.SetFont method.

Fonts you create are automatically destroyed when the dialog closes but if you want to delete them manually to free up resources, use the DestroyFont method.

DelHotkey

<string:name>

bool

Deletes a hotkey you previously created with the AddHotkey method.

This method returns true if successful, or false on failure (e.g. if the hotkey does not exist).

DestroyFont

<int:id>

none

Destroys the specified font using the ID that was returned by the CreateFont method.

Folder

<string:title>
<string:default>
<bool:expand>
<object:window>

object:Path 

Displays a "Browse for Folder" dialog letting the user select a folder. The optional parameters are:

• title - specify title of the dialog
• default - specify the default path selected in the dialog
• expand - specify True to automatically expand the initial path
• window - specify parent window for the dialog (a Lister or a Tab). If not specified, the Dialog object's window property will be used.

A Path object is returned to indicate the folder chosen by the user. This object will have an additional result property that will be False if the user cancelled the dialog - the other normal Path properties will only be valid if result is True.

GetMsg

none

object:Msg 

Returns a Msg object representing the most recent input event in a script dialog (only used in detached mode).

The return value will evaluate to False when the dialog is closed, which is when you should exit your message loop.

If the dialog is not already visible (because Show has not been called) then it will become visible when you first call GetMsg.

KillTimer

<string:name>

none

Stops the specified timer. The timer must previously have been created by a call to the SetTimer method.

Multi

<string:title>
<string:default>
<object:window>
<string:type>

object:Items 

Displays a "Browse to Open File" dialog that lets the user select one or more files. The optional parameters are:

• title - specify title of the dialog
• default - specify the default file selected in the dialog (if a folder is specified this specifies the default location but no file will be selected)
• window - specify parent window for the dialog (a Lister or a Tab). If not specified, the Dialog object's window property will be used. (Omit the window argument entirely if you don't want to use it; the type argument, if used, works whether third or fourth.)
• type - A list of filetypes to populate the "Save as Type" dropdown in the save dialog. (See below.)

The optional type parameter consists of one or more pairs of strings, separated by exclamation marks (!). 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 # character at the start of the string. For example, #Text Files!*.txt!Doc Files!*.doc.

An Items object is returned to indicate the files selected by the user. The returned object will have a result property that you should check first - the collection of items is only valid if result returns True. If it returns False it means the user cancelled the dialog.

NotifyIcon

<string:method>
arguments…

none

Allows a script to add an icon to the system taskbar notification area.

The method argument specifies one of four actions, each of which has its own set of arguments.

For the add and update methods, the icon argument can be a string or Image object - see the documentation for the icon 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.

The tooltip argument provides a tooltip string that the system will display when the user moves the mouse over the icon. If the dialog's title property has been set then the title will be used if no explicit tooltip is given.

The notify method lets you show a system notification associated with your dialog. This method is similar to the DOpus.Notify method - see the description of that method for more information on the arguments.

Once your script has added an icon, the user can interact with it using the mouse. Mouse activity will generate click, dblclk and rclick events in your dialog's message loop. The Msg.control property will be set to notifyicon.

The icon is automatically removed when your dialog closes. It's also restored automatically if Explorer restarts after the icon has been added.

Please note that only one icon per dialog is supported.

Request

<string:message>
<string:buttons>
<string:title>
<object:window>

int

Displays a dialog with one or more buttons. The optional parameters are:

• message - specify message string in the dialog
• buttons - specify button labels (in the same format as the buttons property described above)
• title - specify dialog window title
• window - specify parent window for the dialog (a Lister or a Tab). If not specified, the Dialog object's window property will be used.

The return value is the index of the button selected by the user, and this is also available in the result property once the method returns. The left-most button is index 1, the next button is index 2, 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 0.

Save

<string:title>
<string:default>
<object:window>
<string:type>

object:Path 

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:

• title - The dialog's title.
• default - 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.)
• window - The dialog's parent window (a Lister or a Tab). If not specified, the Dialog object's window property will be used. (Omit the window argument entirely if you don't want to use it; the type argument, if used, works whether third or fourth.)
• type - A list of filetypes to populate the "Save as Type" dropdown in the save dialog. (See below.)

The optional type parameter consists of one or more pairs of strings, separated by exclamation marks (!). 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 # character at the start of the string. For example, #Text Files!*.txt!Doc Files!*.doc.

A Path object is returned to indicate the file chosen by the user. This object will have an additional result property that will be False if the user cancelled the dialog, and the other normal Path properties will only be valid if result is True.

SetTimer

<int:period>
<string:name>

string

Creates a timer that will generate a periodic timer event for your script. The period must be specified in milliseconds (e.g. 1000 would equal one second).

You can optionally specify a name 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).

SetTaskbarGroup

<string:group>

bool

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.

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.

Only works with custom script dialogs (i.e. when you are using the template property). Must be called after the dialog has been created (i.e. after Show has been called – see the RunDlg method if you want to avoid writing your own message loop just for this).
Returns true on success.

WatchClipboard

none

bool

Establish monitoring of the system clipboard. Whenever the system clipboard contents change, the dialog's message loop receives a clipboard event.

Use the CancelWatchClipboard method to cancel monitoring.

WatchTab

<object:Tab>
<string:events>
<string:id>

bool

Allows a script dialog to monitor events in a folder tab. You will receive notifications of the requested events through your message loop.

The tab parameter specifies the Tab you want to watch. The events string is a comma-separated list of events you want to watch for. The id 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).

These are the events you can watch for. Note that some are equivalent to the script events (e.g. OnActivateTab):

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.

You will receive notification events in your message loop. The various properties of the Msg object let you determine what happened.

The Msg.event property will be set to tab for notifications from a watched folder tab.

The Msg.control property tells you which tab the change occurred in; if you specified an ID when you called the WatchTab function, this will be in the Msg.control property - otherwise, it will be the numeric handle of the tab. Note that it's *not* the actual Tab object. You can access the Tab object via the Msg.tab property but this can be inefficient, as it requires a new Tab object to be created every time. If you're only monitoring one tab it's better to store the Tab 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 Map.

The Msg.value property tells you which notification event occurred. Possible values are select, navigate, filechange, activate, srcdst, view, flat, filter and close (sent if the tab is closed while you are monitoring it).

For the filechange event, the Msg.data property contains a bit mask indicating which file events occurred. 1 = add, 2 = delete, 4 = change. The values will be added together (so e.g. 6 indicates at least one item was changed and at least one was deleted). It's up to your script to determine exactly what changed.

You can change the events you're monitoring for by calling the WatchTab method again with the same tab and new event list.

To stop monitoring an existing tab, call WatchTab with the second parameter set to stop. Monitoring is automatically cancelled if your dialog closes (and also if the tab closes).