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.Dlg, Lister.Dlg, Tab.Dlg, Func.Dlg and Command.Dlg methods.

See the 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.

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

Property Name	Return Type	Description
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"
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.
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).
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.)
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.
icon	string	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.
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.
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.
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. 1 - bold (indicates the default item) 2 - checked (a checkmark will appear next to the item) 4 - radio (a radio button will appear next to the item) 8 - disabled (the user will not be able to select the 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.
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.
password	bool	In a text entry dialog, set this property to True to make the text entry field a password field. In a password field the characters the user enters are not displayed.
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.
select	bool	In a text entry dialog, set this property to True to automatically select the contents of the input field (as specified by the default property) when the dialog opens.
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.
title	string	Specifies the title text of the dialog.
window	object:Lister or object:Tab or int	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 Listeror a Tab object. If you are showing this dialog in response to the OnAboutScript event, you can also pass the value of the AboutData.window property. You only need to set this property if you obtain the Dialog option from the DOpus.Dlg method - if the Dialog object comes from one of the other objects (e.g. Tab.Dlg) then its parent window will be set automatically.

Method Name	Arguments	Return Type	Description
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). You can also set the window property of the Dialog object before calling this method. 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). You can also set the window property of the Dialog object before calling this method. 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 input 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.
Multi	<string:title> <string:default> <object:window>	collection:Item	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). You can also set the window property of the Dialog object before calling this method. A collection of Item objects 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.
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). You can also set the window property of the Dialog object before calling this method. 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.
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). You can also set the window property of the Dialog object before calling this method. 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.
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. 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>	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 - 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). You can also set the window property of the Dialog object before calling this method. 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 - the other normal Path properties will only be valid if result is True.