GetDir(), GetFile(), LocFile(), PutFile()

Using these functions definitely comes under the category of not reinventing the wheel. They bring up various standard dialogs. GETDIR() displays the Select Directory dialog. GETFILE() shows the Open File dialog. LOCFILE() tries to find the specified file first, but reverts to the Open File dialog if it can't. PUTFILE() brings up the Save As dialog.All these functions let you navigate through directories. There's some internal setting that remembers where you last navigated. Calling one of these functions without specifying an initial directory starts you where you left off—even if you call a different one of the functions. That's right—they all share this hidden setting. Fortunately, you can override FoxPro's memory by SETting DEFAULT or CDing to the directory you'd like to start in.Lately, we use all the functions in this group (except GETDIR()) a lot less than we used to. Instead, in our applications, we usually use the Common Dialogs ActiveX control these days. The Common Dialogs offer more control over various settings than these functions do, and make our apps work more like other Windows apps. (The Common Dialogs control has its own aggravations, too, but for the most part, the advantages of using it outweigh the disadvantages.)

Usage

cDirName = GETDIR( [ cStartDir [ , cCaption [ , cTitle 
           [ , nFlags [ , lRootOnly ] ] ] ] ])

Parameter	Value	Meaning
cStartDir	Character	The directory that should be initially highlighted in the dialog.
cStartDir	Omitted	Start from the last chosen directory or the default directory.
cCaption	Character	A message to display over the list of directories.
cCaption	Omitted	No message appears over the list.
cTitle	Character	A message to display as the title bar's caption.
cTitle	Omitted	The dialog caption is "Select Directory."
nFlags	Numeric	One or more of the options available to modify the functionality of the dialog. See below.
nFlags	Omitted	Default functionality.
lRootOnly	.T.	Restricts the user to selecting only directories under the starting directory.
lRootOnly	.F. or omitted	Allows access to any directory available to the user.

VFP 7 uses two separate dialogs depending on how many parameters you pass. If you pass just the first two parameters, it uses its own internal dialog, just like in previous versions. But if you pass more parameters, VFP uses the SHBrowseForFolder function from the Windows API. What's the difference? First, the SHBrowseForFolder function gives you control over the text in the title bar, so your apps can have more informative dialogs than "Select Directory" (yeah, why am I selecting a directory?). Another difference allows a myriad of flags to control numerous options in the dialog, such as whether to disable the OK button if the user has selected something that is not in the file system (such as "My Network Places") and whether to display files as well as folders. The constants are shown in the table below, and are additive. Add the multiple values together to combine the options. A complete description and more constants are available by searching MSDN for SHBrowseForFolder.

Constant Name	Value	Meaning
BIF_RETURNONLYFSDIRS	1	Returns only File System directories. In other words, if the user selects "My Network Places," the OK button is disabled until the user drills down and selects a location that can contain files.
BIF_DONTGOBELOWDOMAIN	2	Don't display network folders, such as "My Computer" and "My Network Places."
BIF_EDITBOX	16	Adds an edit box above the tree for the user to type in a directory name. Available only on Windows 98 or later, or with IE 4.0 or later, and requires version 4.71 or later of Shell32.dll.
BIF_USENEWUI	64	This one requires Windows 2000 or later, and displays a new interface. This larger dialog box is resizable and carries with it a whole host of features, such as drag-drop capability, the ability to add and delete folders, and much more.
BIF_BROWSEINCLUDEFILES	16384	Displays files as well as folders. Available only on Windows 98 or later, or with IE 4.0 or later, and requires version 4.71 or later of Shell32.dll.

Actually, any integer, positive or negative, works without error. Here are some undocumented values. Only one, 255, offers a capability not accounted for in the table above; the others might be easier to read by defining your own constants and using the following values. Note that these values are not additive, with the possible exception of 255.

Value	Meaning
8	Includes system shortcuts, such as the Recycle Bin, Internet Explorer, and the Control Panel. Also disables the OK button if the location doesn't have files (like 1).
255	Adds an edit box below the tree for the user to type in a directory name. Available only on Windows 98 or later, or with IE 4.0 or later, and requires version 4.71 or later of Shell32.dll.
-1	This one needs Windows 2000, and displays the new interface (like 64), adds an edit box (like 16), but below the tree, and shows all files (like 16384) and the user's desktop shortcuts.
-16	Like –1, but includes system shortcuts, described in 8, above.
-24	Like –1, but without the edit box.
-32	Like –16, but without the edit box.

Before VFP 5, we used GETDIR() a lot in development. CD GETDIR() was an easy way to change the default directory without having to remember where we are or where we're going. Since VFP 5, though, we can CD ? for the same effect.

In versions prior to VFP 7, and also in VFP 7 when using the internal GETDIR() version (that is, passing two or fewer parameters), GETDIR() (and CD) can't see directories that are flagged as "system." They simply don't appear. Fortunately, ADIR() can find them if you give it the right values ("DS") for the third parameter. The VFP 7 SHBrowseForFolder interface (pass three or more parameters) shows those directories flagged as "system."

Example

#DEFINE BIF_USENEWUI 64
cDataDir = GETDIR("AppDir\", "Where's the data?")
cDataDir = GETDIR("AppDir\", "Where's the data?", ;
           "Store Your Data", BIF_USENEWUI)

Usage

cFilePath = GETFILE( [ cExtensions [ , cTextCaption 
                     [ , cButtonCaption  [ , nButtonChoice 
                     [ , cDialogTitle ] ] ] ] ] )
cFilePath = LOCFILE( cFileName [ , cExtensions 
                     [ , cTextCaption ] ] )

Parameter	Value	Meaning
cExtensions	Character	A comma-separated (,), semicolon-separated (;) or vertical bar-separated (\|) list of file extensions to display in the Open File dialog. Can include DOS wildcards.
cExtensions	Omitted	Show all files.
TextCaption	Character	The caption to place next to the text box that shows the name of the selected file.
TextCaption	Omitted	Caption is "File Name:"
cButtonCaption	Character	The caption to appear on the OK button.
cButtonCaption	Omitted	Caption is "OK".
nButtonChoice	0 or omitted	Use OK and Cancel buttons.
	1	Use OK, New and Cancel buttons.
	2	Use OK, None and Cancel buttons.
cDialogTitle	Character	The caption to appear in the dialog's title bar. In VFP 3, this parameter was the Mac creator type.
cDialogTitle	Omitted	The dialog caption is "Open".
cFileName	Character	The file to locate.
cFilePath	Character	The full path to the file chosen.
cFilePath	Empty	The user pressed Esc or chose Cancel in GETFILE().

Use LOCFILE() when you're looking for a specific file and want to ask the user for help if you can't find it. (LOCFILE() checks the current directory first, then the FoxPro path.) Use GETFILE() to let the user choose any input file. We use GETFILE() a lot in developer tools where the user specifies a file to process.These two functions handle Esc/Cancel differently. GETFILE() returns the empty string—good choice. LOCFILE(), since it was looking for a specific file, gives an error (#1—"File Does Not Exist"). The current incarnation of the Open File dialog has a text box for the file name with a drop-down list underneath labeled "Files of Type". When you specify multiple extensions, the first extension in the list determines what appears as the current choice in the Files of Type drop-down. However, when you drop it open, you see all the extensions you specified, as well as an All Files choice. Extensions separated by vertical bars or semicolons are listed each on a separate line in the drop-down, while comma-separated lists are listed all on the same line (as in "*.DOC, *.XLS, *.PPT").No matter what you specify for nButtonChoice, there's a Help button on the dialog. In addition, when you set nButtonChoice to 0 (or omit this parameter), there is a disabled Code Page button. With the other choices, that position is occupied by either the New or None button. We haven't found a way to make the Code Page button come alive.The cTextCaption parameter specifies a string that appears next to the text box for entering the file name. The space for this caption is pretty limited, so you need to keep this one short.

This one's really a Windows thing. Both these functions let you specify a nonexistent file. They don't create the file. They just hand you back the full path to some file that ain't there. Always use FILE() to check the result of GETFILE() and LOCFILE() for existence.

Example

cInpFile = GETFILE("PJX","Choose a Project","Choose")
IF FILE(cInpFile)
   * Process the project in some way.
ELSE
   * Cancel because the user did.
   DO CleanUp
   RETURN
ENDIF
 
* Find a particular file.
cCustomer = LOCFILE("Customer.DBF","DBF","Customer")
IF FILE(cCustomer)
  ... process file here
ENDIF

Usage

cFilePath = PUTFILE( [ cTextCaption [ , cFileName 
                     [ , cExtensions ] ] ] )

Parameter	Value	Meaning
cTextCaption	Character	The caption to appear next to the file text box.
cTextCaption	Omitted	Caption is "File Name:"
cFileName	Character	The default file name for the new file.
cFileName	Omitted	No default name is used. The Files of Type drop-down list shows "File".
cExtensions	Character	List of extensions (separated with ";" or "\|") for files displayed in file list. Can include DOS wildcards.
cExtensions	Omitted	Files with no extension and those with TXT extension are displayed.
cFilePath	Character	The full path to the file chosen.
cFilePath	Empty	The user pressed Esc or chose Cancel.

Use PUTFILE() to choose a file for output. It lets you pick an existing file or specify a new one. Regardless of the setting of SAFETY, if the user picks an existing file, he's prompted with an overwrite message. We haven't found any way to get rid of this message and substitute our own. The Files of Type drop-down behaves as described above for GETFILE().PUTFILE() expects parameters in a very different order than the other functions. It's a real pain and means we always ended up looking up the parameters for this whole group of functions before VFP 7 saved us with IntelliSense. But we do see the point. In every case, the parameters are pretty much in the order of likelihood of their being used.

Example

cOutFile = PUTFILE("Result file:","Results.txt","TXT")
IF NOT EMPTY(cOutFile)
   REPORT FORM MyReport TO FILE (cOutFile) ASCII
ELSE
   WAIT WINDOW "Report Canceled" NOWAIT
ENDIF