GetFileOpenName

Description

Displays the system's Open File dialog box and allows the user to select a file or enter a file name.

Syntax

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.


Return value

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.

Usage

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.

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 network 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.


Opening a file

Use the FileOpen function to open a selected file.

Examples

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\Appeon. 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\Appeon", 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)   

See also

DirList

DirSelect

GetFileSaveName

GetFolder