~~Title: Codes to display dialogs ~~
<pageheader/>

The following codes can be used to display various simple dialogs when the command is run. This lets you provide information (like selecting a file or a folder, or entering a string) at "run-time" rather than incorporating the value into the command itself. For more flexibility, you can use a [[:scripting:script_dialogs|script dialog]].

<commandtable columns="3" id="cmdtable_1">
$$ Long form
$$ Short form
$$ Description
$$ {dlgopen}
$$ {Rf}
$$ Displays an **Open File** dialog, which lets you select an existing filename to pass to the command.
$$ {dlgmulti}
$$ {Rm}
$$ Displays an **Open File** dialog in multiple selection mode, which lets you select one or more existing files.
$$ {dlgsave}
$$ {RF}
$$ Displays a **Save File** dialog, which lets you enter a new filename to pass to the command.
$$ {dlgfolder}
$$ {Rd}
$$ Displays a **Select Folder** dialog, which lets you select a folder to pass to the command.
$$ {dlgstring}
$$ {Rs}
$$ Displays a dialog that lets you enter an arbitrary string.
$$ {dlgstringS}
$$ {RS}
$$ The same as `{dlgstring}` except the contents of the string field are automatically selected (only applies if a default value is specified - see below).
$$ {dlgpassword}
$$ {Rp}
$$ The same as `{dlgstring}` except the contents of the string field are obscured - useful for entering passwords.
$$ {dlgchoose}
$$ {Rc}
$$ Displays a drop-down list that lets you choose from a list of values.
$$ {dlgchooseS}
$$ {RC}
$$ The same as `{dlgchoose}` except the value list is automatically sorted.
</commandtable>


==Parameters for {dlgopen}, {dlgmulti}, {dlgsize}==

The template for these codes is `{code|<title>|<default>}`.

//<title>// specifies the title of the dialog box (a default title will be used if not provided), and //<default>// specifies the default filename.

For example, `{dlgopen|Select filename|dopus.txt}` would set the title to **Select filename** and the default filename to **dopus.txt**.

For `{dlgopen}` and `{dlgmulti}` you can specify a wildcard for //<default>// to set the filter type of the file dialog.

For example, `{dlgopen||*.jpg;*.bmp;*.gif}` would leave the dialog title as its default, and set the dialog to filter on **.jpg**,  **.bmp** and **.gif** files.

For `{dlgsave}` you can specify an additional parameter to populate the "Save as Type" dropdown list in the save dialog.

For example, `{dlgsave|Title|Default Name.txt|type=#Text Files!*.txt!Doc Files!*.doc}`.

The `#` following the **type=** causes the default "All files" items to be added to the drop-down - take out the `#` if you don't want this. 

Following that are 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 semicolons - for example, `type=JPEG Files!*.jpg;*.jpeg`.

These codes also support the modifiers listed under [[codes_for_passing_filenames|Codes for passing filenames]]. To use  these modifiers, you must also include the //<title>// and  //<default>// parameters (they can be left blank if  desired).

For example `{dlgopen|||noext}` would strip the extension from the selected filename.


==Parameters for {dlgfolder}==

The template for this codes is  `{dlgfolder|<title>|<default>}`.

//<title>// specifies the title of the dialog box (a default title  will be used if not provided), and //<default>// specifies the  default  filename.

For  example, `{dlgfolder|Select folder|C:\Users}` would set the  title to **Select folder** and the initial selected folder  would be **C:\Users**.

This code supports the modifiers listed under [[codes_for_passing_paths|Codes for passing paths]]. To use these  modifiers, you must also include the //<title>// and  //<default>// parameters (they can be left blank if desired). An  additional modifier, `expand`, is also supported. This causes the initially  selected folder to be automatically  expanded.

For  example `{dlgfolder||C:\Program Files|expand}` would set **C:\Program Files** as the default folder and automatically expand it in the displayed dialog.


==Parameters for {dlgstring}, {dlgstringS} and {dlgpassword}==

The template for these codes is `{code|<message>|<default>}`.

//<message>// specifies the message displayed in the dialog box, and //<default>// specifies the default value of the string field.

You can include line-breaks in the message text using the special code `\n` (and if you need to include a literal `\n` sequence in the text you must escape the `\` character, as in `\\`).

{{:media:dlgstring.png?nolink|}}

For example, `{dlgstring|Please enter the string.\nThen click OK.|default string}`.

The optional `doublequotes` modifier can be used if you want any quote characters the user types to be doubled (`"` turns into `""`). This must follow the //<default>// parameter, which should be blank if it is not used. Doubling quotes allows quote characters the user types to be included inside command parameters, provided there are explicit quotes around parameter itself.

For example, `SetAttr META "comment:{dlgstring|Enter Comment||doublequotes}"`

Additionally,  `{dlgpassword}` accepts an optional `confirm`  modifier, which must also follow the //<default>// parameter. If  this is specified, the dialog will display two password fields, and you must  enter the same value in both fields (as a confirmation) before the OK button  will be  enabled.

For  example, `{dlgpassword|Please enter your password twice.||confirm}`.

If both `doublequotes` and `confirm` are needed at once, they can be specified in any order.

For example, `{dlgpassword|Please enter your password twice.||confirm|doublequotes}`.


==Parameters for {dlgchoose}, {dlgchooseS}==
 
The  template for these codes is `{code|<message>|<option 1>[=<value 1>][+<option 2>[=<value 2>]...]}`.

//<message>// specifies  the message displayed in the dialog box. You can include line-breaks in the  message text using the special code `\n` (and if you need to  include a literal `\n` sequence in the text you must escape the `\` character, as in `\\n`.

//<option 1>// is the text displayed for the first option in the drop-down list, //<option 2>// is the second option, and so on. Multiple options  are separated with a `+` sign.

//<value 1>// is an optional value associated with the first option. If provided, the //option// is displayed in the drop-down list, and the //value// is  what is passed through on the command line. If //values// aren't  provided, the //option// text is used for both.

You can specify the option which is selected by default by adding `default:`  before it; otherwise, the first option (after sorting) will be the initial  selection. You can also use the `notdefault:` prefix, which  will simply be removed, if you need to use `default:` or `notdefault:` as a  literal prefix.

{{:media:dlgchoose.png?nolink|}}

For example, `{dlgchoose|Select encoding quality|default:High=320+Medium=256+Low=128}` would add the options **High**, **Medium** and **Low** to the  drop-down list, with **High** as the initial selection, and would  pass one of the values **320**, **256** or  **128** (respectively) through to the command  line.

If you need to include a `+` or `=` character in either an option name or its value, you can do  this by doubling the character up.