TXNLEVEL() | Hackers Guide to Visual FoxPro 7.0

FoxTools

FoxTools.FLL is a dynamic link library (DLL) that has been specially compiled to access the Visual FoxPro API. (For information on creating FLL files, see "Creating a Basic FLL Library" in the VFP Help). It includes some useful utility functions. Check out HOME() + "\TOOLS\FOXTOOLS.CHM" for additional details.

Starting in Visual FoxPro 6.0, many of these functions have been incorporated directly into the language and no longer require the FLL to be loaded. These include: AddBS(), DefaultExt(), DriveType(), ForceExt(), ForcePath(), and the entire set of Just* functions. VFP 7 includes replacements for the Words() and WordNum() functions. However, FoxTools still contains several functions that make it useful, and we include this reference as an aid to those functions as well as to developers unfamiliar with FoxTools who need to maintain code from an older version.

Registering and Using DLL Functions: RegFn(), RegFn32(), CallFn()

Two functions within FoxTools allow Visual FoxPro applications to access and call functions built into dynamic link libraries (DLLs). The functions called this way may be part of the Windows native API, or they may be supplied by a third party. Any function that can operate when supplied with character and numeric parameters (structures cannot be created and passed from Visual FoxPro) can be run this way.

Usage

nFuncHandle = RegFn( cFuncName, cParamTypes,                       cRetType, cLocation ) nFuncHandle = RegFn32( cFuncName, cParamTypes,                         cRetType, cLocation )

Parameter	Value	Meaning
cFuncName	Character	The name of the function. Note that many function names are case-sensitive.
cParamTypes	Character	A list of the type of parameters accepted by the function, in the order they must be supplied. Parameters which are to be passed by reference need to be preceded with an "@" symbol. Acceptable types are: C = Character string D = Double-precision floating number F = Floating point I = Integer L = Long S = Short integer
cRetType	Character	A single character, describing the type of the return value of the function.
cLocation	Character	The name of the DLL containing the function. If the function is built into the core Windows API, WIN32API can be specified instead, which allows the same code to run on different Windows installations.

The ability to access DLL functionality using FoxTools was important when introduced in FoxPro 2.5, but it has been superseded somewhat by the addition of the DECLARE-DLL command. However, DECLARE accesses only those DLLs that have been recompiled to work within the 32-bit environment in which Visual FoxPro lives. Older, 16-bit applications are accessible only through the RegFn()–CallFn() sequence.

Registering DLLs works the same way whether they are 16-bit or 32-bit. First the function must be "registered" with FoxPro: FoxPro must be told the name of the function, its location, what parameters it accepts and what it returns.

In VFP 3 on Win 3.1 installations, RegFn() calls 16-bit DLLs; on 32-bit installations (WinNT and Win 95), RegFn() can also access 32-bit DLLs. RegFN32() always uses 32-bit DLLs. We recommend the use of DECLARE-DLL if you can be sure you're accessing a 32-bit DLL, and RegFn() otherwise.

One last note: If you'll be calling 16-bit functions using RegFn() from the 32-bit platforms, make sure DDEReg.EXE is included in your distribution disks, because this provides the mechanism to communicate with 16-bit DLLs. For VFP 3 running under Win32s, you'll need to include the file Fll32_16.DLL instead.

Usage

RetVal = CallFn( nFuncHandle, Param1, Param2, ... )

Now that you've gone to all the trouble of declaring the function, invoking it is pretty straightforward. Use the function handle returned to you from the RegFn() function as the first parameter to tell CallFn() which function it should be accessing, then pass the number and type of parameters specified in the RegFn() function. The return value you receive should be of the type specified.

Example

* Resource. PRG - Displays free system resources SET LIBRARY TO home()+"FOXTOOLS" ADDITIVE nGFSR = RegFn('GetFreeSystemResources', "I", "I", "USER") ? "System Resources ", CallFn(nGFSR,0) ? "GDI Resources", CallFn(nGFSR,1) ? "User Resources", CallFn(nGFSR,2)

File Functions

These functions modify a supplied drive, path, file name and extension to return only a portion of the supplied information or force a specific format. Almost all of these functions were added to the language in VFP 6. In the following and the other tables in this topic, those functions included directly within VFP are marked with an asterisk.

Function	Parameters	Purpose
AddBS*	cPathAndFile	Returns the string with an ending backslash, if one isn't already present.
CleanPath	cPathAndFile	Makes a best guess at the correct path and file name, removing invalid characters.
DefaultExt*	cPathAndFile, cExt	Appends file extension cExt to cPathAndFile, if no extension is present.
ForceExt*	cPathAndFile, cExt	Forces (appends or replaces) the specified extension onto the file name.
ForcePath*	cPathAndFile, cPath	Forces (prepends or replaces) the specified path onto the file name.
JustDrive*	cPathAndFile	Returns just the drive letter.
JustExt*	cPathAndFile	Returns just the extension.
JustFName*	cPathAndFile	Returns the file name with extension.
JustPath*	cPathAndFile	Returns the path, with drive if supplied.
JustStem*	cPathAndFile	Returns the file name without a path or extension.
ValidPath	cPathAndFile	Determines whether a drive, path, file name and extension could be valid, following the rules of DOS file and path naming restrictions. Does not test for the existence of the path or file. Does not work with operating systems that support spaces in path names.

Clipboard Functions

These functions provide access to the Windows clipboard, to determine the format of the information saved there and manipulate it. Use these functions to examine the contents of the clipboard and request the data in a specific format, or to register the format your application uses to post data onto the clipboard. These can be handy especially if you are using Fpole.DLL to transfer data to and from your application.

Function	Parameters	Purpose
CloseClip	none	Closes the handle opened with OpenClip().
CountClipF	none	Returns the number of different formats in which the information on the clipboard may be requested.
EmptyClip	none	Empties the clipboard.
EnumClipFm	nIndex	Returns a number corresponding to the format in which the clipboard contents may be requested. See the Windows SDK documentation (WinUser.H) for details.
GetClipDat	nFormat	Retrieves a handle to the current clipboard data in the format specified by nFormat.
GetClipFmt	nFormat	This is supposed to retrieve a custom clipboard format name, but it is way too deep into the weird Windows way for us to follow. If you really need to use this function, we recommend you plow through the Win32 SDK for help.
IsClipFmt	nFormat	Returns a logical response to the query of whether the clipboard contents can be rendered in the specified format.
OpenClip	nWndHandle	Opens the clipboard for manipulation by the other functions listed here. We recommend passing MainHwnd() as the argument.
RegClipFmt	cFormatName	Allows you to register a custom clipboard format, use it to render data into the clipboard and later extract it.
SetClipDat	nFormat, cData	Allows storage of data to the clipboard in the format specified.

String Functions

Functions for doing some useful things with string manipulation. Two of these functions were added to the core product in VFP 7, though their names were changed (to protect the innocent?) in the process.

Function	Parameters	Purpose
NextWord	cText, nPosition [, cDelimiters ]	Returns the first word or word fragment starting at position nPosition in the supplied character string or memo field, optionally ending at the specified word delimiters (in addition to space and tab).
Reduce	cString [, cCharacter ]	This function is documented as a means to replace repeated occurrences of cCharacter in cString with a single occurrence. It will, as long as cCharacter is a space (or omitted and allowed to default to a space—also undocumented). If it is any other character, all occurrences of that character are obliterated and replaced with spaces. Blech. You can write better.
StrFilter	cString1, cString2	Removes all the characters from cString1 not in cString2. We can do the same thing with STRTRAN() or SYS(15), so we see no particular advantage to this function.
WordNum*	cText, nIndex	Returns word number nIndex from the supplied character string or memo field. Starting in VFP 7, you can use the native GetWordNum() function instead.
Words*	cText	Returns the number of words in the supplied text. Starting in VFP 7, you can use the native GetWordCount() function instead.

FoxPro API Functions

These functions allow access to the internal editing and Windows functions of the Visual FoxPro editor. They start with _ED and _W and are documented, not in FoxTools' Help file, but rather in the main Help file supplied with FoxPro.

Miscellaneous Functions

A plethora of other functions got tossed into FoxTools, because someone needed them or asked for them.

Function	Parameters	Purpose
DriveType*	cDriveLetter	There's one difference between the native VFP command and the FoxTools function for earlier VFP versions: If the drive does not exist, VFP 5 and earlier return 0. VFP 6 and later versions return 1. In all other cases, both functions return the type of drive specified: 2=diskette, 3=hard drive, 4=network or removable, 5=CD-ROM, 6=RAM disk.
FoxToolVer	none	Returns the version of FoxTools, "3.12" for Visual FoxPro 3.0b, and "6.00" for VFP 6.0 and later.
GetFileVersion	cFileName, @ArrayName	Introduced in VFP 5, superseded by the more useful and native AGetFileVersion() in VFP 6, this function returns version information for a file.
GetProStrg	cSection, cEntry, cDefault, @cReturn, nRetLen	Equivalent of Windows API GetProfileString. See the entry DECLARE-DLL for a detailed study of this function.
MainHwnd	none	Returns the window handle of the main FoxPro window required by many Windows API functions. Starting in VFP 7, you can use the hWnd property of _VFP.
MkDir	cDirectory	Creates a directory. "Included for backward compatibility"—use the Visual FoxPro MD command instead.
MsgBox	numerous	See the FoxTools documentation for all the parameter variations. Also, see the MessageBox() entry in the Reference section for an explanation of when to use this function rather than MessageBox(), and a description of the undocumented SYSTEMMODAL option.
PutProStrg	cSection, cEntry, cValue	Writes an entry to Win.INI in the format cEntry=cValue. See the discussion in DECLARE-DLL for good reasons not to use this function.
RGBComp	nRGBNumber, @nRedColor, @nGreenColor, @nBlueColor	Returns the values of the three Red, Green and Blue colors from a single color number you get back from a function like GetColor().
RmDir	cDirectory	Removes a directory. "Included for backward compatibility"—use the Visual FoxPro RD command instead.

Many of the functions have been included within FoxTools because they are used in the programs that come with Visual FoxPro—programs such as AddLabel.App, Browser.App, Builder.App and Convert.App. These functions can be included within your own programs, provided that you bundle FoxTools with your application. Note that FoxTools.FLL must actually be included on the disk, and not bound into your APP or EXE, in order to be used.

Example

? FoxToolVer()    && Returns "6.0"   * Throw some text into the clipboard and see in what formats  * it can be pasted into another application. _CLIPTEXT = "Hey!"   NOTE: The results you see will vary by platform, but these ;       should give you an idea of what to expect. ? OpenClip(0)     && returns .T. ? CountClipF()    && returns 3 (formats) ? EnumClipFm(0)   && returns 1 (CF_TEXT) ? EnumClipFm(1)   && returns 16 (CF_LOCALE) ? EnumClipFm(16)  && returns 7 (CF_OEMTEXT) ? CloseClip()     && returns T.   ? Reduce("1  2  3")  && returns "1 2 3" (single spaces)