FileDialogBox

Description:              This statement displays a threaded system common file dialog box.

Returns:                    Numeric (1 = failure, 0 = success) In addition, see the Result parameter.

Usage:                       Script

Format:                      FileDialogBox(Save, FilterPattern, FilterDesc, File, Directory, Title, Extension, Result)

Parameters:             Save    { numeric }  { required }  { no default: }

                                      Any expression that evaluates to the following values:

                             (please read Comments below if you require a "Browse for Folder" dialog).

                                    FilterPattern    { text array }  { required }  { no default: }

                                      A statically declared array of text values that are the wildcard file patterns that are offered to the user in the dialog box (e.g. "*.TXT", "*.DOC", "*.BAK"). This can be a single text value if only one type is used. Defaults to "" if invalid.

                                    FilterDesc    { text array }  { required }  { no default: }

                                      A statically declared array of text values that are the descriptions corresponding to the FilePattern values (e.g. "Text Files"). This can be a single text value if only one type is used. Defaults to "" if invalid.

                                    File    { text }  { required }  { no default: }

                                      Any text expression giving the initial file name for the dialog box. Defaults to "" if invalid.

                                    Directory   { text }  { required }  { no default: }

                                      Any text expression giving the initial directory for the dialog box. Defaults to "" if invalid.

                                    Title    { text }  { required }  { no default: }

                                      Any text expression giving the title of the window containing the dialog box. Defaults to "" if invalid.

                                    Extension    { text }  { required }  { no default: }

                                      Any text expression giving the default file extension to use if the user does not specify one. Defaults to "" if invalid.

                                    Result    { text }  { required }  { no default: }

                                      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.

                             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 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 ("").

Example:

If ZButton(100, 176, 200, 146, "Browse", 1);

[

  FileDialogBox(0 { An "Open File" dialog box }, 

                "*.*" { All files is only option }, 

                "All Files" { Option label }, 

                "APPMOD.SRC" { Default file name }, 

                "C:\VTS5\APP" { Default path }, 

                "Find Application" { Window title }, 

                ".SRC" { Default extension }, 

                selectedApp { Chosen file }); 

]

When the button labeled "Browse" is pressed a file dialog box that shows all files (and directories) in the C:\VTS5\App directory will open. The title of the window will be "Find Application" and when a file is chosen, its path and name will be stored in selectedApp.

See Also:

FontDialog | PrintDialogBox | DIR