GETFILE()

Displays a dialog box from which the user can choose, or enter, an existing file name, and returns this file name.

Syntax

GETFILE([<filename skeleton expC>
[, <title expC>
[, <suppress database expL>],
[<file types list expC> | <file type group name expC> (<file types list expC>)]]])

A character string that matches selected file names with the wildcard characters ? and *. The GETFILE( ) dialog box initially lists only those file names in the current directory that match the file name skeleton. Without <filename skeleton expC>, the dialog box lists all file names.

A title displayed in the top of the dialog box. Without <title expC>, the GETFILE( ) dialog box displays the default title. If you want to specify a value for <title expC>, you must also specify a value or empty string ("") for <filename skeleton expC>.

Whether to suppress the combobox from which you can choose a database. The default is true; the Database combobox is not displayed. If you want to specify a value for <suppress database expL>, you must also specify a value or empty string ("") for <filename skeleton expC> and <title expC>.

A character expression containing zero, or more, file types to be displayed in the "Files of Type" combobox. If this parameter is not specified, the following file types will be loaded into the “Files of Type” combobox:

Projects (*.prj)

Forms (*.wfm;*.wfo)

Custom Forms (*.cfm;*.cfo)

Menus (*.mnu;*.mno)

Popup (*.pop;*.poo)

Reports (*.rep;*.reo)

Custom Reports (*.crp;*.cro)

Labels (*.lab;*.lao)

Programs (*.prg;*.pro)

Tables (*.dbf;*.db)

SQL (*.sql)

Data Modules (*.dmd;*.dmo)

Custom Data Modules (*.cdm;*.cdo)

Images (*.bmp;*.ico;*.gif;*.jpg;*.jpeg;*.pje;*.xbm)

Custom Components (*.cc;*.co)

Include (*.h)

Executable (*.exe)

Sound (*.wav)

Text (*.txt)

All (*.*)

A character expression denoting a custom or built in file type goup name to use in the dialog.

For a custom file type group name

Specify the group name followed by a list of one or more file types within parenthesis

For example, "Web Images (*.jpg,*.jpeg,*.bmp)"

For a built-in file type group name

Specify the group name followed by a set of empty parenthesis

For example, "Images ()"

dBASE will detect the left and right parenthesis and search for a matching built-in group name. If found, the list of file types associated with the built-in group will be added to the string that is added to the File Types combobox in the GetFile() or PutFile() dialog.

File Types between parenthesis must be separated by either a comma or a semi-colon and can be specified in any of the following formats:

where <ext> means a file extension such as jpg or txt. If a File Type List string is specified that contains unbalanced parenthesis or right parenthesis before left parenthesis, a new error will be triggered with the message:

"Unbalanced parenthesis in file type list"

Examples using file group name:

f = GETFILE("","Title",true,"Web Images (*.jpg,*.png,*.gif,*.bmp)")

or if you want to use one of the built in file type groups:

f = GETFILE("","Title",true,"FILE ()")

If an empty string is specified, "All (*.*)" will be loaded into the Files of Type combobox.

If one or more file types are specified, dBASE will check each file type specified against an internal table.

If a match is found, a descriptive character string will be loaded into the "Files of Type" combobox.

If a matching file type is not found, a descriptive string will be built, using the specified file type, in the form

"<File Type> files (*.<File Type>)"

and will be loaded into the "Files of Type" combobox.

When the expression contains more than one file type, they must be separated by either commas or semicolons.

File types may be specified with, or without, a leading period.

The special extension ".*" may be included in the expression to specify that "All (*.*)" be included in the Files of Type combobox.

File types will be listed in the Files of Type combobox, in the order specified in the expression.

Note: In Visual dBASE 5.x, the GETFILE( ) and PUTFILE( ) functions accepted a logical value as a parameter in the same position as the new <file types list expC> parameter. This logical value has no function in dBASE Plus. However, for backward compatibility, dBASE Plus will ignore a logical value if passed in place of the <file types list expC>

Examples of <file types list expC> syntax.can be viewed here

Description

Use GETFILE( ) to present the user with a dialog box from which they can choose an existing file or table. GETFILE( ) does not open any files.

The GETFILE( ) dialog box includes names of files whether they are currently open or closed. dBASE Plus returns the full path name of the file whether SET FULLPATH is ON or OFF.

By default, the dialog box opened with GETFILE( ) displays file names from the current directory the first time you issue GETFILE( ). After the first time you use and exit GETFILE( ) successfully, the subdirectory you choose becomes the default the next time you use GETFILE( ).

If <suppress database expL> is false, you can also choose from a list of databases. When a database is selected, the dialog box displays a list of tables in that database instead of files in the current directory.

The dialog box is a standard Windows dialog box. The user can perform many Windows Explorer-like activities in this dialog box, including renaming files, deleting files, and creating new folders. They can also right-click on a file to get its context menu. These features are disabled when the dialog is displaying tables in a database instead of files in a directory.

GETFILE( ) returns an empty string if the user chooses the Cancel button or presses Esc.