The getfile() function creates a dialog box that allows the user to select a file. It returns a boolean value indicating whether the user clicked OK or Cancel in the dialog box. If the user clicks OK or Open, the file name and path will be returned to the variable named in the path parameter.
The files displayed in the dialog can be filtered so that only certain types of files are displayed. You can use a predefined filter, or create your own filter.
getfile(prompt, default_filter, path {, custom_filter})
• prompt – A string that will be displayed in the title bar of the dialog box.
• default_filter – An integer indicating the type of file you’re searching for. If you are using one of the predefined filters, this value corresponds to one of the following constants:
![[spacer]](1p.gif){kind=small}
|
Constant |
Description |
|---|---|
|
APPFILE |
Displays only application files |
|
DICTIONARY |
Displays only dictionary files (.DIC) |
|
LAUNCH |
Displays only launch files (.SET) |
|
MACROFILE |
Displays only Dexterity macro files (.MAC) |
|
TEXTFILE |
Displays all files |
If you are using a custom filter, the default_filter parameter indicates which filter in the custom filter set will be used by default. For instance, assume three filter types are defined in the custom filter. To specify that the second filter type be used as the default, use 2 for this parameter.
• path – A string variable to which the file path and name will be returned. The returned path will be in generic format. You can supply a default value to be displayed in the file dialog by setting the path variable before opening the dialog. If you supply only a filename, the current path will be used. If you supply a complete path (in native format) the default location will also be set in the dialog.
• custom_filter – An optional string that specifies a set of custom filters to use. The set of custom filters is defined using the following syntax:
description |filter{;filter}|
The description parameter is a string that describes the filter, such as “Dictionaries (*.DIC)”. It must be followed by a pipe (|) character.
The filter parameter specifies a file extension, such as “*.DIC”. When this filter is used, files that match this extension will be displayed in the dialog box. The filter parameter should not contain spaces. To specify multiple filters, separate them with a semicolon (;). End the list of filters with a pipe (|) character.
Several custom filters can be concatenated within the custom_filter string.
A boolean value indicating which button was clicked. If Open is clicked, the value of true is returned, and the file name and path (a string value) are returned to the variable named in the path parameter. If Cancel is clicked, the value false is returned.
If you will be using custom filters, consider creating messages or constants for each type of filter. You can then easily concatenate the filter types together and build the custom_filter string. This is shown in the fourth example.