?dialogName s_dialogName

SKILL symbol that is the handle to the file dialog box.

When the dialog box is destroyed (that is, when the hiFileDialogDone command is executed), this symbol is reset to nil. Do not reference a deleted file dialog; it can cause undefined behavior.

?workingDir t_workingDir

Text string specifying the working directory. This is the directory that appears in the Look in field.

The default value of this argument is "." (the current working directory).

?filter t_filter

Text string specifying the filters that can be used in the File type field. For example:

"Images (*.png *.xpm *.jpg)"

If you want to specify multiple filters, separate them with two semicolons. For example:

"Images (*.png *.xpm *.jpg);;Text Files (*.txt);;XML Files (*.xml)"

If you do not specify a filter, the default is “All Files (*)”.

If s_mode is ’directory or ’directoryOnly, this argument is ignored.

?mode s_mode

Symbol specifying what the user is allowed to select in the file dialog box. Legal values are:

• ’anyFile: Selects any file, whether it exists or not.
  This option is typically used for "Save As" dialog boxes.
• ’existingFile: Selects an existing file.
  This option is typically used for Open File dialog boxes.
• ’existingFiles: Selects zero or more existing files
• This option is typically used for Open File dialog boxes.
• ’directory: Selects a directory; the file dialog displays both files and directories
• ’directoryOnly: Selects a directory; the file dialog displays both files and directories

The default value is ’existingFile.

If s_mode is set to ’anyFile and s_acceptMode equals ’save, then the first suffix in the selected name filter is added to the filename if no other suffix has been specified in the file dialog. For example, if the selected name filter is "Images (*.png *.xpn *.jpg)", and any type-in field is "/tmp/foobar", then hiFileDialogSelection is returned ("/tmp" "foobar.png"). Note however that if the type-in field is "/tmp/foobar.txt", Qt considers that a suffix already exists and HI would not be able to return "/tmp/foobar.txt.png".

?modal g_modal

non-nil or nil. Specify any non-nil value if you want the dialog box to be modal (blocking) or nil if you want the dialog box to be modeless (non-blocking).

If the dialog box is modal, calls to hiDisplayFileDialog do not return until the user clicks one of the buttons on the dialog box. In this case, you can either handle the user selection immediately, or in a callback as you would with a modeless dialog box.

If the dialog box is modeless, calls to hiDisplayFileDialog return a value of nil immediately after the dialog is displayed. Therefore, you must specify a callback to handle the user selection.

?defaultValue t_defaultValue

Text string specifying a file or directory that is selected by default.

?callback t_callback

Text string specifying the SKILL function to be called when the user makes a selection in the dialog box.

The callback function is passed either two or three arguments. The first argument is &_dialog, the handle to the file dialog box.

The second argument is s_event, indicating which button the user clicked after making a selection. s_event is one of ’done or ’cancel, corresponding to the Open/Save/OK and Cancel buttons.

The third argument, l_userData, is passed only if you specify the s_userData argument to this function.

If the dialog box is modeless, you must specify a callback to handle the user selection, as hiDisplayFileDialog returns nil immediately after the dialog box is displayed.

?userData s_userData

Symbol specifying user data for the callback. If you specify this argument, an additional argument, userData, is passed to the callback function. Otherwise, the callback is passed only two arguments.

?caption t_caption

Text string that is displayed in the file dialog box banner.

?location l_location

The location of the dialog box on the screen, specified as a list of the x and y coordinates of the upper left corner of the box:

list(x-coordinate y-coordinate)

If this argument is not specified or if it is specified incorrectly, then the default location set by hiSetDBoxDefaultLocation is used. If the default location has not been set, then the toolkit that implements the dialog box determines the location (usually the center of the screen).

?acceptMode s_acceptMode

One of the following symbols: ’open or ’save, that specify the button to display on the dialog box. Specify ’open if you are creating a dialog for opening files (an Open button appears on the dialog) or ’save if you are creating a dialog for saving files (a Save button appears on the dialog).

Default value: ’save if ?mode is ’anyFile, else ’open

?labelText t_labelText

Specify the optional argument ?labelText as an association list of s_key/t_value pairs. Accepted keys are 'LookIn, 'FileName, 'FileType, 'Accept, and 'Reject. The 'Accept and 'Reject keys are for specifying Open/Save and Cancel button labels respectively. The defaul value is nil.

?confirmOverwrite g_confirmOverwrite

Set this optional argument to nil if you do not want to display a dialog box that asks for a file overwrite confirmation when an existing file is selected , and argument s_mode equals 'anyFile.

Set it to t to display the overwrite confirmation dialog box but this only applies when the argument s_mode equals 'anyFile.

Default value: t

l_userSelection

Returns l_userSelection if the file dialog box is modal and the user makes a selection. l_userSelection is a list of two elements, each of which is a string:

("dir" "file")

dir is a path relative to t_workingDir if the selection is either in t_workingDir or in a directory ascending or descending from t_workingDir. Otherwise, dir is an absolute path.

file is the file that was selected. If the s_mode argument is ’directory or ’directoryOnly, file is an empty string.

If s_mode is ’existingFiles, l_userSelection is a list of directory-file pairs, such as:

(("dir1" "file1") ("dir2" "file2") ...)

nil

Returns nil if the file dialog box is modeless, or if the file dialog box is modal and has been canceled.