GETFILENAME$ function

Purpose:

GETFILENAME$ opens a File Open or Save dialog box and returns the chosen file name. GETFILENAME$ may be used to retrieve a file name for opening, saving or performing any other action on files.

Syntax:

FileName = GETFILENAME$(FileTitle AS STRING, _
                    FileExtension AS STRING  _
                     [, OpenSave AS INTEGER] _
                         [, HndlWnd AS HWND] _
                        [, Flags AS INTEGER] _
                    [, InitialDir AS STRING] _
                   [, InitialFile AS STRING] _
                    [, &ExtIndex AS INTEGER])

Return Value:

Data type: STRING
FileName The full path and file name.

Parameters:

Data type: STRING
FileTitle Text to be placed in the title bar of the dialog box. If this member is NULL, the system uses the default title (that is, Open).
Data type: STRING
FileExtension The filter pattern of the extensions of the files to be displayed in the dialog box. The pattern is Description|File extension, for example,
```
"Text Files|*.txt".
```
To specify multiple filter patterns use a semicolon to separate the File extension patterns, for example,
```
"Text Document and Backup Files|*.TXT;*.DOC;*.BAK".
```
A pattern string can be a combination of valid file name characters and the asterisk(*) wildcard character. do not include spaces in the pattern string.
Data type: INTEGER
OpenSave [OPTIONAL] Set to 0 for Open or 1 for Save. The default is 0 if neither is specified.
Data type: HWND
HndlWnd [OPTIONAL] The handle of the window that owns the dialog box. This can be any valid window handle, or it can be NULL if the dialog box has no owner.
Data type: INTEGER
Flags [OPTIONAL] Win32 API OPENFILENAME stucture integer bit flags which can be used to initialize the dialog box. When the dialog box returns, it sets OPENFILENAME.flags to the Flags parameter value. For more information, see the flags OPENFILENAMEA structure member on the Microsoft OPENFILENAMEA structure webpage.
Data type: STRING
InitialDir [OPTIONAL] The path to and name of the directory to be displayed when the dialog box is opened.
Data type: STRING
InitialFile [OPTIONAL] A file name to be displayed in the 'File name' dropdown when the dialog box is opened.

Data type: INTEGER
&ExtIndex [OPTIONAL] The index of the user selected FileExtension. For example, when the code below is executed, if .png is chosen in the 'Save as type' dropdown in the dialog box, "4" would be stored in the "Ndx" variable.

DIM F$, Filter$, Ndx%

          Filter$ = "Bmp Files(*.bmp)|*.Bmp|"
Filter$ = Filter$ & "Gif Files(*.gif)|*.Gif|"
Filter$ = Filter$ & "Jpg Files(*.jpg)|*.Jpg|"
Filter$ = Filter$ & "Png Files(*.png)|*.Png|"
Filter$ = Filter$ & "Tiff Files(*.Tif)|*.Tif"

F$ = TRIM$(UCASE$(GETFILENAME$("Save", _
                              Filter$, _
                                    1, _
                                    0, _
                                    0, _
                                    0, _
                                    0, _
                                 &Ndx)))   

IF F$ <> "" AND NOT INCHR(F$, ".") THEN
  SELECT CASE Ndx%
  CASE 1 : F$ = F$ + ".bmp"
  CASE 2 : F$ = F$ + ".gif"
  CASE 3 : F$ = F$ + ".jpg"
  CASE 4 : F$ = F$ + ".png"
  CASE 5 : F$ = F$ + ".tif"
  END SELECT  
END IF

PRINT Ndx
PAUSE

Example:

DIM FileName$
DIM Mask$
 Mask$ = ".HTML Documents(.Htm;.Html)|*.Htm;*.Html|"
 Mask$ = Mask$ & "Active Server Pages(.Asp)|*.Asp|"
 Mask$ = Mask$ & "Text Files(.Txt)|*.Txt|"
 Mask$ = Mask$ & "All Supported Files(.Htm;.Html;.Asp;.Txt;)"
 Mask$ = Mask$ & "|*.Htm;*.Html;*.Asp;*.Txt;|"
 Mask$ = Mask$ & "All Files(*.*)|*.*|"

FileName$ = GETFILENAME$("OPEN", Mask$)   ' defaults to OPEN Dialog
IF LEN(FileName$) THEN
 MSGBOX FileName$
ELSE
 MSGBOX "Cancelled"
END IF

FileName$ = GETFILENAME$("OPEN", Mask$, 0) ' set flag to use OPEN Dialog
IF LEN(FileName$) THEN
 MSGBOX FileName$
ELSE
 MSGBOX "Cancelled"
END IF

FileName$ = GETFILENAME$("SAVE", Mask$, 1) ' set flag to use SAVE Dialog
IF LEN(FileName$) THEN
 MSGBOX FileName$
ELSE
 MSGBOX "Cancelled"
END IF

Remarks:

The above example will open a file dialog box with the default directory being that in which the executable was started. It will list files with .bas and .c extensions. To list all files, use *.* as the Extension$. The OPTIONAL HndlWnd (handle of the window that owns the dialog box) is not used in this example.

BCX Console Sample Programs using the GETFILENAME$ function.

S149.bas