Question: How do I prompt the user for a filename?

Answer: Use the fileBrowser() or FileBrowserEx() methods in the System class. We usually do as a two-step process:

1. Create a custom method to handle the FileBrowser() call
2. Trigger that using the specific conditions for for the task at hand.

Each step is illustrated in the following sections.

Step 1: Custom Method for Calling FileBrowser()

The following code sample shows a custom method that displays the File Browser dialog using information passed as the parameters:

method getFileName( var strFileName String,
                    fbiInput FileBrowserInfo ) Logical
;-----------------------------------------------------------
; This routine lets the user choose a filename from a
; dialog.  When called, strFileName indicates the default
; file to be selected in the dialog.  On output, it contains
; the file actually selected by the user.  The second
; parameter defines the appearance of the dialog, as well as
; the options it supports.
;
; The return value indicates whether or not the user selected
; an existing file.
;----------------------------------------------------------------

var
   strValue  String            ; Fully qualified file name
   fbi       FileBrowserInfo   ; Structure for FileBrowser()
   loRetval  Logical           ; value returned to caller.
   dynParts  Dynarray[] String ; Parts of selected file.
   loRepeat  Logical           ; Variable for the while loop
endVar

   ; Initialize local variables
   loRetval = TRUE         ; assume user will choose a new name.
   loRepeat = TRUE         ; loop control variable
   strValue = strFileName  ; default selected file

   ; Initialize the file browser info structure
   fbi = fbiInput

   while loRepeat

      loRetval = fileBrowser( strValue, fbi )
      If loRetval then

         ; the user selected a file or the user selected an
         ; alias that no longer exists.  So, we need to determine
         ; If the user actually selected a file.

         ; Start by building the final file name from the
         ; components of the fileBroswerInfo structure.

         If fbi.Path <> "" then
            strValue = fbi.Path + strValue
         endIf

         If fbi.Drive <> "" then
            strValue = fbi.Drive + strValue
         else
            strValue = getAliasPath( fbi.alias ) + "\\" + strValue
         endIf

         splitFullFileName( strValue, dynParts )

         ; See if a bad alias was selected.

         If dynParts[ "NAME" ] = "" then
            msgStop( "Can't Use Alias", "The " + fbi.Alias +
                     " alias is not valid, presumeably because " +
                     "the folder or network drive no longer " +
                     "exists.  Choose a different alias or " +
                     "folder." )
            fbi.Alias = ":PRIV:"
         else
            loRepeat = FALSE
         endIf

      else
         loRepeat = FALSE
      endIf
   endWhile

  ; Verify that the user entered a valid filename,  Remove
  ; as needed.
   if loRetval then

      loRetval = NOT ( upper( FullName( strFileName ) ) =
                       upper( strValue ) )
   endIf

   If loRetval then
      strFileName = strValue
   endIf

   dynParts.empty()
   return loRetval

endMethod

Much of the above code converts alias information into a fully-qualified path name. Given that you periodically will use this to select files to be passed to other applications (or Windows API calls), we've found this to be the most flexible approach.

You should also note that the above returns FALSE when the user cancels the FileBrowser or when the user selects (or enters) a filename that doesn't exist. (You can do this by typing an invalid filename in the File Name edit box.) If you want the user to be able to enter non existant filenames, remove the verification IF...ENDIF block. (This can also be controlled using a FileBrowserInfo variable, as shown in the next section.)

Step 2: Calling the Custom Method

Now that you have a general function (also called a "wrapper" function) that works with FileBrowser, you can call it using something like this:

method pushButton(var eventInfo Event)
var
   fbiXFile  FileBrowserInfo   ; data for systemSaveAs() function.
   loRetval  Logical           ; Value returned to calling process.
   strValue  String            ; Holds filenames
endVar

   ; initialize local vars
   loRetval = TRUE
   strValue = "IMPORT.TXT"

   fbiXFile.Title          = "Open File"

   ; Note the constant that's used here.  Though the documentation
   ; says the constant is called "browseOptPathMustExist," that
   ; generates a compiler error.  A quick look at the table
   ; generated by enumRTLConstants() shows this is the constant
   ; to use instead.

   fbiXFile.Options        = browseOptPathMustExit  ; No "s" in exist
   fbiXFile.AllowableTypes = fbText + fbFiles
   fbiXFile.Alias          = ":PRIV:"
   fbiXFile.DefaultExt     = "TXT"

   ; Call the getFileName wrapper function
   loRetval = getFileName( strValue, fbiXFile )

   if loRetval then

      msgInfo( "FYI", "The user chose to import " +
               strValue + "." )
   else

      msgStop( "File Browser Cancelled", "The user either cancelled " +
               "the FileBrowser or an invalid file was selected." )

   endIf

endMethod

This code uses a FileBrowserInfo variable to control the appearance and behavior of the FileBrowser dialog. In this case, it's used to change the dialog box title, the types of files that can be selected, and to indicate whether or not the file must exist. (Note the constant for this; it's declared incorrectly in certain versions of Paradox.

We prefer this type of approach for it places the specific configuration of the dialog box near the code that actually uses it. You can, of course, define the FileBrowserInfo variable in the getFileName() method shown above.

You should also note that this version only displays dialog boxes reporting the results of the operation. You'll want to use strValue as needed for the application you're developing. To use this to import a custom file, for example, pass strValue to your TextStream or DataTransfer variable.

Other Considerations

Here are some other things to consider while working with these methods:

• The fields of the FileBrowserInfo type are documented on the Help page for either FileBrowser (older versions) or FileBrowserEx (more recent versions). Unfortunately, this information is not entirely complete. You may need to experiment to get the specific results you're looking for.

• The fbIni constant is documented as allowing INI files (*.INI), however, certain versions of Paradox appear to translate this constant to allowing *.cfg files instead. (We suspect this is an intentional design choice that was not reflected in the online Help files.)

• If you're using a version of Paradox that interprets fbIni as *.cfg files and you want to prompt the user for actual .INI files, use the CustomFilter field of FileBrowserInfo, as illustrated in Specifying Custom Filters in FileBrowser.

• If your default filename is not one that's supported by a FileBrowserFileTypes constant, it does not appear in the FileBrowser. This has been previously documented as an intentional design choice on the part of the Paradox development team, though we suspect the behavior exists for compatibility reasons.

• The ObjectPAL Reference does not make it easy to locate the supported constants for FileBrowserInfo's Options field. (You have to search for the topic called "BrowserOptions.") As of Paradox 9, these are the supported values:

  Constant	Value	Purpose
  BrowseOptCreatePrompt	8192	Prompts user to create new files.
  BrowseOptFileMustExist	4096	Selected file must exist.
  BrowseOptNoNetButton	131072	Hides the network button in older versions of Windows; no apparent effect in others. (See following note)
  BrowseOptPathMustExit	2048	Forces the user to choose an existing directory. (Note that "Exist" is mispelled.)

Related Articles:

• Specifying Custom Filters in FileBrowser
• Trick: Creating Resizeable FileBrowser Dialogs