Displays the system’s Open File dialog box and allows the user to select a file or enter a file name.
GetFileOpenName ( title, pathname, filename {, extension {, filter { , initdir { , aFlag } } } } )
GetFileOpenName ( title, pathname, filename[ ] {, extension {, filter { , initdir { , aFlag } } } } )
Argument |
Description |
|---|---|
title |
A string whose value is the title of the dialog box. |
pathname |
A string variable in which you want to store the returned path. If the user selects a single file, the pathname variable contains the path name and file name. |
filename, filename[ ] |
A string variable in which the returned file name is stored or an array of string variables in which multiple selected file names are stored. Specifying an array of string variables enables multiple selection in the dialog box. |
extension (optional) |
A string whose value is a 1- to 3-character default file extension. The default is no extension. |
filter (optional) |
A string whose value is a text description of the files to include in the list box and the file mask that you want to use to select the displayed files (for example, *.* or *.exe). The format for filter is: description,*. ext
To specify multiple filter patterns for a single display string, use a semicolon to separate the patterns, for example: "Graphic Files (*.bmp;*.gif;*.jpg;*.jpeg), *.bmp;*.gif;*.jpg;*.jpeg"
The default is: "All Files (*.*),*.*"
|
initdir (optional) |
A string whose value is the initial directory name. The default is the current directory. |
aFlag (optional) |
An unsigned long whose value determines which options are enabled in the dialog box. The value of each option’s flag is calculated as 2 to the power of (index -1), where index is the integer associated with the option. The value of the aggregate flag passed to GetFileOpenName is the sum of the individual option flags. See the table in the Usage section for a list of options, the index associated with each option, and the option’s meaning. |
Integer. Returns 1 if it succeeds, 0 if the user clicks the Cancel button or Windows cancels the display, and -1 if an error occurs. If any argument’s value is null, GetFileOpenName returns null.
If you specify a DOS-style file extension and the user enters a file name with no extension, PowerBuilder appends the default extension to the file name. If you specify a file mask to act as a filter, PowerBuilder displays only files that match the mask.
If you specify a string for the filename argument, the user can select only one file. The pathname argument contains the path name and the file name, for example C:\temp\test.txt.
If you specify a string array for the filename argument, the user can select more than one file. If the user selects multiple files, the pathname argument contains the path only, for example C:\temp. If the user selects a single file, its name is appended to the pathname argument, for example C:\temp\test.txt.
You use the filter argument to limit the types of files displayed in the list box and to let the user know what those limits are. For example, to display the description Text Files (*.TXT) and only files with the extension .TXT, specify the following for filter:
"Text Files (*.TXT),*.TXT"
To specify more than one file extension in filter, enter multiple descriptions and extension combinations and separate them with commas. For example:
"PIF files, *.PIF, Batch files, *.BAT"
The dialog boxes presented by GetFileOpenName and GetFileSaveName are system dialog boxes. They provide standard system behavior, including control over the current directory. When users change the drive, directory, or folder in the dialog box, they change the current directory or folder. The newly selected directory or folder becomes the default for file operations until they exit the application, unless the optional initdir argument is passed.
The aFlag argument is used to pass one
or more options that determine the appearance of the dialog box.
For each option, the value of the flag is 2^(index -1),
where index is an integer associated with each
option as shown in the following table. You can pass multiple options
by passing an aggregate flag, calculated by adding the values of
the individual flags.
If you do not pass an aFlag, the Explorer-style open file dialog box is used. If you do pass a flag, the old-style dialog box is used by default. Some options do not apply when the Explorer-style dialog box is used. For those that do apply, add the option value for using the Explorer-style dialog box (2) to the value of the option if you want to display an Explorer-style dialog box.
For example, passing the flag 32768 (2^15) to the GetFileSaveName function opens the old-style dialog box with the Read Only check box selected by default. Passing the flag 32770 opens the Explorer-style dialog box with the Read Only check box selected by default.
Index |
Constant name |
Description |
|---|---|---|
1 |
OFN_CREATEPROMPT |
If the specified file does not exist, prompt for permission to create the file. If the user chooses to create the file, the dialog box closes; otherwise the dialog box remains open. |
2 |
OFN_EXPLORER |
Use an Explorer-style dialog box. |
3 |
OFN_EXTENSIONDIFFERENT |
The file extension entered differed from the extensions specified in extension. |
4 |
OFN_FILEMUSTEXIST |
Only the names of existing files can be entered. |
5 |
OFN_HIDEREADONLY |
Hide the Read Only check box. |
6 |
OFN_LONGNAMES |
Use long file names. Ignored for Explorer-style dialog boxes. |
7 |
OFN_NOCHANGEDIR |
Restore the current directory to its original value if the user changed the directory while searching for files. This option has no effect for GetFileOpenName on Windows NT, 2000, and XP. |
8 |
OFN_NODEREFERENCELINKS |
Return the path and file name of the selected shortcut (.lnk file); otherwise the path and file name pointed to by the shortcut are returned. |
9 |
OFN_NOLONGNAMES |
Use short file names (8.3 format). Ignored for Explorer-style dialog boxes. |
10 |
OFN_NONETWORKBUTTON |
Hide the Network button. Ignored for Explorer-style dialog boxes. |
11 |
OFN_NOREADONLYRETURN |
The file returned is not read only and is not in a write-protected directory. |
12 |
OFN_NOTESTFILECREATE |
Do not create the file before the dialog box is closed. This option should be specified if the application saves the file on a netwrok share where files can be created but not modified. No check is made for write protection, a full disk, an open drive door, or network protection. A file cannot be reopened once it is closed. |
13 |
OFN_NOVALIDATE |
Invalid characters are allowed in file names. |
14 |
OFN_OVERWRITEPROMPT |
Used in Save As dialog boxes. Generates a message box if the selected file already exists. |
15 |
OFN_PATHMUSTEXIST |
Only valid paths and file names can be entered. |
16 |
OFN_READONLY |
Select the Read Only check box when the Save dialog box is created. |
The following example displays a Select File dialog box that allows multiple selection. The file types are TXT, DOC, and all files, and the initial directory is C:\Program Files\Sybase. The option flag 18 specifies that the Explorer-style dialog box is used (2^1 = 2), and the Read Only check box is hidden (2^4 = 16). The selected filenames are displayed in a MultiLineEdit control.
If the user selects a single file, the docpath variable contains both the path and the file name. The example contains an IF clause to allow for this.
string docpath, docname[] integer i, li_cnt, li_rtn, li_filenum
li_rtn = GetFileOpenName("Select File", &
docpath, docname[], "DOC", &
+ "Text Files (*.TXT),*.TXT," &
+ "Doc Files (*.DOC),*.DOC," &
+ "All Files (*.*), *.*", &
"C:\Program Files\Sybase", 18)
mle_selected.text = ""
IF li_rtn < 1 THEN return
li_cnt = Upperbound(docname)
// if only one file is picked, docpath contains the
// path and file name
if li_cnt = 1 then
mle_selected.text = string(docpath)
else
// if multiple files are picked, docpath contains the
// path only - concatenate docpath and docname
for i=1 to li_cnt
mle_selected.text += string(docpath) &
+ "\" +(string(docname[i]))+"~r~n"
next
end if
In the following example, the dialog box has the title Open and displays text files, batch files, and INI files in the Files of Type drop-down list. The initial directory is d:\temp. The option flag 512 specifies that the old-style dialog box is used and the Network button is hidden (2^9 = 512).
// instance variables
// string is_filename, is_fullname
int li_fileid
if GetFileOpenName ("Open", is_fullname, is_filename, &
"txt", "Text Files (*.txt),*.txt,INI Files " &
+ "(*.ini), *.ini,Batch Files (*.bat),*.bat", &
"d:\temp", 512) < 1 then return
li_fileid = FileOpen (is_fullname, StreamMode!)
FileRead (li_fileid, mle_notepad.text)
FileClose (li_fileid)
