(Engine-Level Function)
| Description: | Displays a threaded system common file dialog box. |
| Returns: | Numeric (1 = failure, 0 = success) In addition, see the Result parameter. |
Usage:  |
Script Only. |
| Function Groups: | File I/O, Graphics |
| Related to: | FontDialog | PrintDialogBox | Dir |
| Threaded: | Yes |
| Format: |
FileDialogBox(Save, FilterPattern, FilterDesc, File, Directory, Title, Extension, Result) |
| Parameters: |
| Save | ||||||||
Required. Any expression that evaluates to one of the following values
(please read Comments below if you require a "Browse for Folder" dialog). |
| FilterPattern |
| Required. Either a statically-declared array, or a semi-colon separated list of wildcard file patterns for the file types that will be offered to the user. Defaults to an empty string if invalid. |
| FilterDesc |
| Required. Either a statically-declared array, or a semi-colon separated list of text values that are the descriptions corresponding to the FilePattern values (e.g. "Text Files"). Defaults to an empty string if invalid. |
| File |
| Required. Any text expression giving the initial file name for the dialog box. In any 'Save' mode, an initial directory may be included as part of the file name. If the path is valid, the Directory parameter will be ignored. A known path alias may be provided in the form, {KnownPathAlias}. Defaults to "" if invalid. |
| Directory |
| Required. Any text expression giving the initial directory for the dialog box. A known path alias may be provided in the form, :{KnownPathAlias} . (A table of known path aliases is provided in the Reference chapter). Defaults to "" if invalid. See comments for more detail. |
| Title |
| Required. Any text expression giving the title of the window containing the dialog box. Defaults to "" if invalid. |
| Extension |
| Required. Any text expression giving the default file extension to use if the user does not specify one. Defaults to "" if invalid. |
| Result |
| Required. A variable where the resulting file name, including its path, will be returned. |
| Comments: | This statement displays a threaded system dialog box for opening or saving a file, depending on the value of the Save parameter, however, it does not actually perform the requested action, but simply displays the dialog. If successful, the Result parameter will be set to the full path and file name of the chosen file, or 0 if it fails or is canceled. It is the user's responsibility to act upon the value of Result and save or open the file by using such commands as FWrite or FRead. In addition to the Result parameter, the function itself will return an error code to indicate whether the dialog was successfully opened. A "1" indicates failure to open while a "0" indicates success. The Directory parameter is ignored for Open and Save operations if the File parameter contains a path. You can use this feature to define the initial directory, but return to the selected file if the user re-opens the dialog. For example: FileDialogBox(1, "", "", SelectedFile, InitialDirectory, ....); SelectedFile can be initialized to "SomeFile.txt", in which case the InitialDirectory will be used. After the user has selected a file ("C:\AnotherFile.txt") , and reopens the dialog, then it will reopen to the path in SelectedFile. This avoids having to parse a user selection result (SelectedFile) into a filename and path to achieve the same effect. For Save -1 (directory browser mode) the Directory parameter means something different. Directory defines the root of the selectable directories. For example, you can use this feature to restrict the user from selecting a directory outside their VTScada application folder. Passing the VTScada application path as Directory, means that operators would only be able to select that folder, or any sub-folders. This option can be used in conjunction with 'File' to restrict the selectable path and also have an initial selection. If either the FilterPattern or FilterDesc parameters use dynamically allocated arrays (i.e. created using the New function), the dialog box will not open - these two parameters must use statically declared arrays. If using a single text value instead, you may specify as many wildcard patterns as needed by adding a semi-colon separator between each: "*.BMP;*.JPG;*.PNG;*.TIF". If the Save parameter is a negative value, indicating that a "Browse for Folder" dialog is required, the Directory and Title parameters must be set. Title will be displayed above the tree view control in the dialog box. This string can be used to specify instructions to the user. Directory can either be a string containing the starting root directory to begin browsing, or a CSIDL value to specify a special folder (a CSIDL is a number, the definitions of which can be found in the Platform SDK). The remaining parameters may be set to any valid value, including empty strings (""). FTP sites may not be browsed depending if the server is running an older Windows operating system. Within an Anywhere Client session, this function does nothing. |
Example:
If ZButton(100, 176, 200, 146, "Browse", 1);
[
FileDialogBox(0 { An "Open File" dialog box },
"*.*" { All files is only option },
\GetPhrase("AllFilesLabel") { Option label },
"APPROOT.SRC" { Default file name },
"C:\VTScada\APP" { Default path },
\GetPhrase("FindLabel") { Window title },
".SRC" { Default extension },
selectedApp { Chosen file });
]
When the button is pressed a file dialog box that shows all files (and directories) in the C:\VTScada\App folder will open. When a file is chosen, its path and name will be stored in selectedApp.
