GETFILENAME$ function

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$, _
                       FileExtension$  _
                           [,OpenSave] _
                               [,hWnd] _
                             [,Flags%] _
                        [,InitialDir$] _
                       [,InitialFile$] _
                          [,ExtIndex%])

Parameters:

FileTitle$ Pointer to a string 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).
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.
OpenSave [OPTIONAL] flag which can be set to 0 for open or 1 for save. The default if neither are specified is 0.
hWnd OPTIONAL handle to 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.
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. See your Win32 SDK or PSDK Reference help for more information about the OPENFILENAME.flags which, with some restrictions based on the operating system, can be any combination of
- OFN_ALLOWMULTISELECT
- OFN_CREATEPROMPT
- OFN_DONTADDTORECENT
- OFN_ENABLEHOOK
- OFN_ENABLEINCLUDENOTIFY
- OFN_ENABLESIZING
- OFN_ENABLETEMPLATE
- OFN_ENABLETEMPLATEHANDLE
- OFN_EXPLORER
- OFN_EXTENSIONDIFFERENT
- OFN_FILEMUSTEXIST
- OFN_FORCESHOWHIDDEN
- OFN_HIDEREADONLY
- OFN_LONGNAMES
- OFN_NOCHANGEDIR
- OFN_NODEREFERENCELINKS
- OFN_NOLONGNAMES
- OFN_NONETWORKBUTTON
- OFN_NOREADONLYRETURN
- OFN_NOTESTFILECREATE
- OFN_NOVALIDATE
- OFN_OVERWRITEPROMPT
- OFN_PATHMUSTEXIST
- OFN_READONLY
- OFN_SHAREAWARE
- OFN_SHOWHELP
InitialDir$ [OPTIONAL] String literal or variable containing path to and name of the default folder in which the dialog is to be opened.
InitialFile$ [OPTIONAL] String literal or variable containing the name of the default file which the dialog to open.

ExtIndex% [OPTIONAL] is an integer pointer which returns the index of the user selected file type. For example,


 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, _
                                    Form1, _
                                        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

Return Value:

FileName$, the return value, is a string containing the full path and file name specified by the user.

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 folder 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 hWnd(handle to the window that owns the dialog box) is not used in this example.