choices

object:Vector(string)
or array(string)

This property uses either a Vector 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:

• Drop-down list: 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 selection property when the Show method returns.
• Checkbox list: If the list 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.
• Popup menu: If the menu 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.
   

When shown as a checkbox list the dialog is resizable; you can set the initial size using the cx and cy properties (and retrieve them afterwards if you want to save the size).

cx

int

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

defvalue

string

In a text entry dialog (i.e. the max property has been specified) this property allows you to initialize the text field with a default value.

(Old scripts may use "default" instead of "defvalue"; this is deprecated because it does not work in JScript where "default" is a reserved keyword.)

detach

bool

Set to True if you want a script dialog to run in “detached” mode, where your script provides its message loop.

icon

string or
object:Image 

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 warning, error, info and question.

When used with a script dialog 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 Image object that you obtained from the DOpus.LoadImage or Script.LoadImage methods. Note that the image must have been loaded from a .ico file.

language

string

Set this property to create a script dialog in a particular language (if one or more language overlays have been provided), rather than the currently selected language.

max

int

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 0 to have no limit).

When the Show method returns the text the user entered will be available in the input property.

message

string

Specifies the message text displayed in the dialog.

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:

center - center the dialog over the parent window (the default)

absolute - specify an absolute position using the x and y properties

parent - position relative to the parent window (using x and y)

monitor - position relative to the current monitor (using x and y)

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.

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.

AddHotkey

<string:name>

<string:key>

none

Creates a hotkey (or keyboard accelerator) for the specified key combination. When the user presses this key combination in your dialog, a hotkey event will be triggered.

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 ctrl, shift and alt with a character or name of a special key. For example, ctrl+t or alt+shift+F7.

Control

<string:name>
[<string:dialog>]
[<string:tab>]

object:Control 

Returns a Control object corresponding to one of the controls on a script dialog. The control is identified by its name, as defined in the script dialog resource.
 

The optional second and third parameters are only used when the control is in a tab control (that is, when it's in a dialog that's a child of another dialog). The dialog parameter specifies the name of its parent dialog. The tab 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).

Note that none of the controls will exist until Create has been called.

Drag

collection:Item

<string:actions>

string

Allows the user to drag and drop one or more files from your dialog (and drop them in another window or application).

You would usually call this in response to a drag event you receive from a static or list view control.

The first parameter is an Item collection (or Vector of Item objects) representing the files to be dragged.

The optional second parameter lets you control which actions are available. This should be a string containing one or more of copy, move, link. The default action can be indicated by prefixing it with a * (e.g. copy,*move,link). If you don't specify this parameter the default is to only allow copy.

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".

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.

GetString

<string:message>
<string:default>
<string:max>
<string:buttons>
<string:title>
<object:window>
<byref string:result>

string

Displays a text entry dialog allowing the user to enter a string. The optional parameters are:

message - specify message string in the dialog
default - specify default string value
max - specify maximum string length
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.
result - for scripting languages that support ByRef parameters, this can specify a variable to receive the string the user enters.

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 result property once this 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.

LoadPosition

<string:id>
<string:type>

none

Restores the previously saved position of a script dialog. The position must have previously been saved by a call to the SavePosition method.
 

The id 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 id as "kundal" - Opus would then internally save the position of a dialog called "dialog1" as "kundal!dialog1". 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.
 

The optional type parameter lets you control which position elements are restored - specify "pos" to only restore the position, "size" to only restore the size, or "pos,size" to restore both (this is also the default, so you can also omit the argument all together).

Open

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

object:Item 

Displays a "Browse to Open File" dialog that lets the user select a single file. 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.

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

RunDlg

none

int

Turns a previously detached dialog into a non-detached one, by taking over and running the default message loop. The RunDlg method won't return until the dialog has closed. You might use this if you created a dialog using Create, in order to initialize its controls, but don't actually want to run an interactive message loop.

The return value is the same as the object's result property, and represents the index of the close button selected by the user.

If the dialog is not already visible (because neither Show nor GetMsg were called) then it will become visible when you call RunDlg. (Compatibility note: Prior to Opus 12.22, scripts needed to call Show explicitly.)

SavePosition

<string:id>

none

Saves the position (and size) of the dialog to your Opus configuration. The position can then be restored later on by a call to LoadPosition.

Normally you would call LoadPosition before displaying your dialog, and SavePosition after the dialog has been closed.

The id 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 id as "kundal" - Opus would then internally save the position of a dialog called "dialog1" as "kundal!dialog1". 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.

Show

none

int

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.
 

If the detach property is False, 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 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.

If the detach property is True, 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 RunDlg to run the standard loop.

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.

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 are. Note that some are equivalent to the existing script events (e.g. OnActivateTab):

• 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

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).