foxtools overview - documentation.help · foxtools is a visual foxpro api library that exposes...

FoxtoolsOverviewFoxtoolsisaVisualFoxProAPIlibrarythatexposesWindowsDLLsforuseinVisualFoxPro.

FunctionsintheFoxtoolslibraryallowyoutosetandretrievefileinformation,manipulatepathsandfilenames,usesystemalerts,andperformmanyotherfunctions.

NoteTheFoxtoolsfunctionsaren'tsupportedbyMicrosoftProductSupportServices(PSS),eitherelectronicallyorviatelephone.ManyofthesefunctionsareincludedforbackwardcompatibilitywithFoxProversion2.6.Somefunctionsbehavedifferentlydependingontheplatformforwhichtheyareused.

What'sNew

SeveralfilenamemanipulationfunctionsinFoxtools.fllhavebeenaddedtoVisualFoxPro.It'snolongernecessarytouseSETLIBRARYTOFOXTOOLS.FLLtocallthesefunctions.AsanativefunctioninVisualFoxPro,youcancallthemdirectlyinyourVisualFoxProprograms.Theyarethefollowing:

AddBS()FunctionAGetFileVersion()Function(GetFileVersion()inFoxTools)DefaultExt()FunctionDriveType()FunctionForceExt()FunctionForcePath()FunctionJustDrive()FunctionJustExt()FunctionJustFName()FunctionJustPath()FunctionJustStem()Function

WhereFoxtoolsGetsInstalled

WhenyouinstallVisualFoxPro,Foxtools.fllisinstalledinthemainVisualFoxProdirectory.TousetheFoxtoolsfunctions,issuethefollowingcommand:

SETLIBRARYTOFoxtools

NoteAPIroutinesaredocumentedintheProfessionalReferencesectionofHelpunderAPILibraryConstruction.TheseroutinesmaptoeditorandwindowfunctionsandallowyoutoextendVisualFoxProusingtheCprogramminglanguage.

RegFn(),RegFn32(),andCallFn()

TheFoxtoolsAPIlibraryallowsVisualFoxProprogramstocallanyWindowsDLLfunctionsthat

takethefollowingarguments:integer,long,float,double,string/buffer.Thesecanbepassedbyreferenceorbyvalue.

returnthefollowingtypes:integer,long,float,double,string/buffer.Thesearereturnedbyvalueonly.

RegFn()andRegFn32()registerafunctionandtheargumentsittakes,andCallFn()callsaregisteredfunction.TheWindowsDLLfunctionsaredocumentedinthebooksthatcomewiththeWindowsSoftwareDevelopmentKit(SDK).TheWindowsSDKisalsoincludedwithMicrosoftC/C++7.0andVisualC++.

Note

Fll32_16.dllisusedforcalling16-bitDLLsunderwin32s.Itusestheuniversalthunktocall16-bitDLLs.

Ddereg.exeisusedforcalling16-bitDLLsunderwin32.ItusesDDEtocall16-bitDLLs.

AddBS()Addsabackslash(ifneeded)toapathexpression.AlsoavailableasanativefunctioninVisualFoxPro.

Syntax

AddBS(cPath)

cPath

Specifiesthepathnametowhichtoaddthebackslash.

ReturnType

Character

CallFn()Callsaregisteredfunctionandreturnsthevaluethatthefunctionreturned,usingthetypedeclaredbyReturnTypeinRegFncall.

Syntax

CallFN(nFunctionHandle,Arg1[,Arg2[,...]])

nFunctionHandle

ThefunctionhandlefromapreviouscalltoRegFn()orRegFn32().

Arg1,Arg2,....

ArgumentsrequiredbythefunctionreferencedbyFnNum.Youmustpassasmanyargumentsasweredeclaredwhenthefunctionwasregisteredoranerroroccurs.

Allargumentsmustmatchtheirdeclaredtypeasfollows:

F,D–mustbeafloatingpointnumber.

I,L–mustbeaninteger.

C–mustbeastringpassedbyvalue,or0(zero).If0,anullpointerispassed.

ReturnTypes

User-definedinRegFn()orRegFn32().

CleanPath()Returnsacorrectedfilename(bestguess)foraninvalidfilenameandremovesspaces,invalidcharacters,duplicatebackslashes,andsoon.

Syntax

CleanPath(cFilename)

cFilename

Specifiesthefilenametobecleaned.

ReturnTypes

Character

CloseClip()ClosestheClipboardopenedpreviouslywithOpenClip().

Syntax

CloseClip()

ReturnType

Logical

Remarks

Thereturnvaluereportssuccess(.T.)orfailure(.F.)ofthecommand.AlmostallClipfunctionsrelyonopeningtheClipboardbeforeusingthefunction._CLIPTEXTcanbeusedtoaccessthecontentsoftheWindowsClipboard.

NoteThisfunctionmapstotheWindowsSDKfunctionthatissimilarlynamed.Formoreinformation,seetheWindowsSDKdocumentation.

CountClipF()RetrievesthenumberofdifferentdataformatscurrentlyontheWindowsClipboard.

Syntax

CountClipF()

ReturnType

Numeric

Remarks

AlmostallClipfunctionsrelyonopeningtheClipboardbeforeusingthefunction.Youcanuse_CLIPTEXTtoaccessthecontentsoftheWindowsClipboard.


DefaultExt()Returnsafilenamewithanewextensionifonedoesn'talreadyexist.AlsoavailableasanativefunctioninVisualFoxPro.

Syntax

DefaultExt(cFilename,cDefault)

cFilename

Specifiesthefilename(withorwithoutapathorextension)tobereturned.

Cdefault

Specifiesthedefaultextensionwithoutaperiod.

ReturnType

Character

DriveType()Returnsthetypeofthespecifieddrive.AlsoavailableasanativefunctioninVisualFoxPro.

Syntax

DriveType(cDrive)

cDrive

Thedrivedesignator.Thecolonindrivenames(forexample,"C:")isoptional.

ReturnTypes

Numeric

Remarks

ThefollowingtableexplainsthenumberDriveType()returnsandthecorrespondingdrivetypedescription.

Number Drivetype0 Notype2 Floppydisk3 Harddisk4 Removabledriveornetworkdrive5 CD-ROM6 RAMdisk(1)

(1)BecausetherearemanydifferenttypesofRAMdisks,youmightgetinconsistentreturnresults.

EmptyClip()EmptiestheClipboardandfreeshandlestodataintheClipboard,thenassignsownershipoftheClipboardtothewindowinwhichtheClipboardisopen.

Syntax

EmptyClip()

ReturnType

Logical

Remarks



EnumClipFm()EnumeratestheformatsfoundinalistofavailableformatsthatbelongtotheClipboard.

Syntax

EnumClipFm(nFormat)

nFormat

SpecifiesaClipboardformat.

Todeterminetheavailableclipboardformats,setnFormatto0;EnumClipFm()willreturnthefirstavailableClipboardformat.ForsubsequentcallstoEnumClipFm(),setnFormattothereturnvalueofthepreviousEnumClipFm()call.

ReturnType

Numeric

Remarks

EachcalltoEnumClipFm()specifiesaknownavailableformat;thefunctionreturnstheformatthatappearsnextinthelist.



ForceExt()Returnsastringwiththeoldfilenameextensionreplacedbyanewextension.AlsoavailableasanativefunctioninVisualFoxPro.

Syntax

ForceExt(cFilename,cExtension)

cFilename

Specifiesthefilename(withorwithoutapathorextension)whichwillgetanewextension.

cExtension

Specifiesthenewextension(withoutaperiod)forcFilename.

ReturnType

Character

ForcePath()Returnsafilenamewithanewpathnamesubstitutedfortheoldone.AlsoavailableasanativefunctioninVisualFoxPro.

Syntax

ForceExt(cFilename,cPath)

cFilename

Specifiesthefilename(withorwithoutapathorextension)whichwillgetanewpath.

cPath

SpecifiesthenewpathforcFilename.

ReturnType

Character

FoxToolVer()ReturnstheversionnumberoftheFoxtoolslibrary.

Syntax

FoxToolVer()

ReturnType

Character

GetClipDat()RetrievesahandlefortheClipboarddataofaspecifiedformatandpassesitdirectlytothecallingapplication.

Syntax

GetClipDat(nFormat)

nFormat

ContainsanidentifierforpossibleClipboardformats.

nFormat Description(definetype)1 cf_Text2 cf_Bitmap3 cf_MetaFilePict4 cf_SYLK5 cf_DIF6 cf_TIFF7 cf_OEMText8 cf_DIB9 cf_Palette

ReturnType

Logical

Remarks

Theclipboardcontrolsthehandle,nottheapplication.Theapplicationshouldcopythedataimmediately.AlmostallClipfunctionsrelyonopeningtheClipboardbeforeusingthefunction.Youcanuse_CLIPTEXTtoaccessthecontentsoftheWindowsClipboard.

NoteThisfunctionmapstotheWindowsSDKfunctionthatissimilarlynamed.

Formoreinformation,seetheWindowsSDKdocumentation.

GetClipFmt()RetrievesthenameofaregisteredClipboardformat.

Syntax

GetClipFmt(nFormat)

nFormat

Specifiestheregisteredformattoretrieve.Thisargumentmustnotspecifyanyofthepredefinedclipboardformats.

ReturnType

Numeric

Remarks


NoteThisfunctionmapstotheWindowsSDKfunctionsthatissimilarlynamed.Formoreinformation,seetheWindowsSDKdocumentation.

GetFileVersion()Returnsinformationaboutafile.AlsoavailableasthenativefunctionAGETFILEVERSION()inVisualFoxPro.

Syntax

GetFileVersion(cFileName,@ArrayName)

cFileName

Specifiesthenameofthefileforwhichinformationisreturned.

ArrayName

Specifiesthenameofthearrayinwhichthefileinformationisplaced.ThearraymustbecreatedbeforeissuingGetFileVersion(),andmusthaveatleast1columnand12rows.

ReturnType

Numeric

Remarks

GetFileVersion()istypicallyusedtogetinformationabout.exeand.dllfiles.

Zeroisreturnedifthefunctionissuccessful;otherwise–1isreturned.

Thefollowingtableliststhefileinformationcontainedinthetwelvearrayelements:

ElementNumber FileInformation1 Comments2 CompanyName3 FileDescription4 FileVersion

5 InternalName6 LegalCopyright7 LegalTrademarks8 OriginalFileName9 PrivateBuild10 ProductName11 ProductVersion12 SpecialBuild

GetProStrg()RetrievesthestringassociatedwithanentrywithinthespecifiedsectionintheWin.iniinitializationfile.

Syntax

GetProStrg(lpszSection,lpszEntry,lpszDefault,@lpszReturnBuffer,cbReturnBuffer)

lpszSection

Pointstoanull-terminatedstringthatspecifiesthesectioncontainingtheentry.

LpszEntry

Pointertothenull-terminatedstringcontainingtheentrywhoseassociatedstringistoberetrieved.IfthisvalueisNULL,allentriesinthesectionspecifiedbythelpszSectionargumentarecopiedtothebufferspecifiedbythelpszReturnBufferargument.

LpszDefault

Pointertothedefaultvalueforthegivenentryiftheentrycan'tbefoundintheinitializationfile.ThisargumentmustneverbeNULL;itmustpointtoavalidstring,evenifthestringisempty(itsfirstcharacteriszero).

lpszReturnBuffer

Pointertothebufferthatwillreceivethecharacterstring.

cbReturnBuffer

Specifiesthesize,inbytes,ofthebufferpointedtobythelpszReturnBufferargument.

ReturnValue

Numeric

Remarks

AnapplicationcanusetheGetProStrg()functiontoretrieveastringfromaspecifiedfile.

IfthelpszEntryargumentisNULL,theGetProStrg()functioncopiesallentriesinthespecifiedsectiontothesuppliedbuffer.Eachstringwillbenull-terminated,withthefinalstringterminatingwithtwonullcharacters.Ifthedestinationbufferistoosmalltoholdallthestrings,thelaststringwillbetruncatedandfollowedbytwoterminatingnullcharacters.

IfthestringassociatedwithlpszEntryisenclosedinsingleordoublequotationmarks,themarksarediscardedwhenGetProStrgreturnsthestring.

GetProStrg()isn'tcasedependent,sothestringsinthelpszSectionandlpszEntryargumentsmaycontainacombinationofuppercaseandlowercaseletters.

Thereturnvalueisthenumberofbytescopiedtothebuffer,notincludingtheterminatingzero,ifthefunctionissuccessful.

IsClipFmt()IndicateswhetherdataofthespecifiedformatiscurrentlyontheClipboard.

Syntax

IsClipFmt(nFormat)

nFormat

Containsanumericvalueindicatingtheformatoftheavailabledata.

ThefollowingtablerepresentsthepredefinedWindowsformats:


ReturnType

Logical

Remarks

IsClipFmt()returnstrue(.T.)ifdataofthespecifiedformatisontheClipboard,orfalse(.F.)otherwise.

NoteThisfunctionmapstotheWindowsSDKfunctionsthatissimilarlynamed.Formoreinformation,seetheWindowsSDKdocumentation.

JustDrive()Returnsthedriveletterfromacompletepath.AlsoavailableasanativefunctioninVisualFoxPro.

Syntax

JustDrive(cPath)

cPath

Specifiesthecompletepathnameforwhichyouwantonlythedrive.

ReturnType

Character

JustExt()Returnsthethree-letterextensionfromacompletepath.AlsoavailableasanativefunctioninVisualFoxPro.

Syntax

JustExt(cPath)

cPath

Specifiesthename,whichmayincludethefullpath,ofthefileforwhichyouwantonlytheextension.

ReturnType

Character

JustFName()Returnsthefilenameportionofacompletepathandfilename.AlsoavailableasanativefunctioninVisualFoxPro.

Syntax

JustFName(cFilename)

cFilename

Specifiesthename,whichmayincludethefullpath,ofthefileforwhichyouwantonlythefilename.

ReturnType

Character

JustPath()Returnsthepathportionofacompletepathandfilename.AlsoavailableasanativefunctioninVisualFoxPro.

Syntax

JustPath(cFilename)

cFilename

Specifiesthefullname(includingpath)ofthefileforwhichyouwantonlythepath.

ReturnType

Character

JustStem()Returnsthestemname(firsteightcharactersoffilename)fromacompletepathandfilename.AlsoavailableasanativefunctioninVisualFoxPro.

Syntax

JustStem(cFilename)

cFilename

Specifiesthename(includingpath)ofthefileforwhichyouwantonlythestem.

ReturnType

Character

MainHwnd()Returnsthewindowhandle(HWND)ofthemainVisualFoxProwindow.

Syntax

MainHwnd()

ReturnType

Numeric

MkDir()Createsadirectory.

Syntax

MkDir(cPath)

cPath

Specifiesthepathtocreate.

ReturnType

Numeric

Remarks

Thisfunctionwon'tcheckforthevalidlengthandformatofadirectorystring.Thereturnvaluesareasfollows:

0 success1 nosuccess6 directoryalreadyexists

ThisfunctionisonlyavailableinFoxtoolsversion1.01orlater.

MessageBox()Displaysamodaldialogboxcenteredinthescreen.

Syntax

MessageBox(cText,cTitle,nType)

cText

Specifiesthecontentsindialogbox.

ctitle

Specifiesthetitleofdialogboxwindow.

ntype

Specifiesthetypeofdialogboxasfollows:

nType Type0 MB_OK1 MB_OKCANCEL2 MB_ABORTRETRYIGNORE3 MB_YESNOCANCEL4 MB_YESNO5 MB_RETRYCANCEL16 MB_ICONSTOP32 MB_ICONQUESTION48 MB_ICONEXCLAMATION64 MB_ICONINFORMATION

ReturnType

Numeric

Remarks

MessageBox()returnsavalueindicatingthebuttonthattheuserclicked.

Returnvalue IDofbuttonclicked1 idok2 idcancel3 idabort4 idretry5 idignore6 idyes7 idno

NextWord()Returnsthecharactersbetweenaspecifiedcharacterindexandthefollowingworddelimiter(ortheendofthestring).

Syntax

NextWord(cString,nPosition[,cDelimiter])

cString

Specifiesthestringtosearch.

nposition

SpecifiesthenumericpositionofthecharacterinthestringthatwillbetheinitialcharacterreturnedbyNextWord().

cdelimiter

Specifiestheoptionalworddelimiters;NextWord()returnsthestringofcharactersbetweennPostitionandthischaracter.IfcDelimiter2isn'tused,thedefaultdelimitersarespaces,tabs,andcarriagereturncharacters(ASCII13).Thedelimitercharacterisn'tincludedinthereturnedstring.

ReturnType

Character

OpenClip()OpenstheClipboardforaccessbysubsequentClipboard-relatedfunctions.

Syntax

OpenClip(nHandle)

nHandle

SpecifiesthehandleofthewindowtobeassociatedwiththeClipboard.Zeroisacceptable.TogetthehandleoftheVisualFoxPromainwindow,callMainHwnd().

ReturnType

Logical

Remarks

Thereturnvaluereportssuccess(.T.)orfailure(.F.)ofthecommand.AlmostallClipfunctionsrelyonopeningtheClipboardbeforeusingthefunction.Youcanuse_CLIPTEXTtoaccessthecontentsoftheWindowsClipboard.


PutProStrg()CopiesastringintothespecifiedsectionoftheWindowsinitializationfile(Win.ini).

Syntax

PutProsStrg(lpszSection,lpszEntry,lpszString)

lpszSection

Pointertoanull-terminatedstringthatspecifiesthesectiontowhichthestringistobecopied.Ifthesectiondoesn'texist,itiscreated.Thenameofthesectioniscase-independent;thestringmaybeanycombinationofuppercaseandlowercaseletters.

LpszEntry

Pointertothenull-terminatedstringcontainingtheentrytobeassociatedwiththestring.Iftheentrydoesn'texistinthespecifiedsection,itiscreated.IfthisargumentisNULL,theentiresection,includingallentrieswithinthesection,isdeleted.

LpszString

Pointertothenull-terminatedstringtobewrittentothefile.IfthisargumentisNULL,theentryspecifiedbythelpszEntryargumentisdeleted.

ReturnType

Numeric

Remarks

Thereturnvalueisnonzeroifthefunctionissuccessful;otherwise,itiszero.

Reduce()Replacesspecifiedcharactersinastringwithaspace.

Syntax

Reduce(cSearch,cReplace)

cSearch

Specifiesthecharacterstringtochange.

cReplace

Specifiesthecharacterstosearchforandreplacewithaspace.Ifyouspecifymorethanonecharacter,thecharactersaretreatedseparatelyduringthereduction;theyaren'ttreatedasasinglemulticharacterstring.

ReturnType

Character

Remarks

ReplacescharactersspecifiedincReplacewithaspace,thenremovesleadingspacesandrepeatedspaceswithinthestring.Thefunctioniscommonlyusedtoreplaceagroupofspacesinastringwithasinglespace,ortoreplacedelimiterssuchastabsorcarriagereturnswithaspace.

RegClipFmt()RegistersanewClipboardformat.

Syntax

RegClipFmt(cFormat)

cFormat

Specifiesastringthatnamesthenewformat.

ReturnType

Numeric

Remarks

Theregisteredformatcanbeusedinsubsequentclipboardfunctionsasavalidformatinwhichtorenderdata,anditwillappearintheClipboard'slistofformats.

Thereturnvalueindicatesthenewlyregisteredformat.Iftheidenticalformatnamehasbeenregisteredbefore,evenbyadifferentapplication,theformat'sreferencecountisincremented(increasedbyone)andthesamevalueisreturnedaswhentheformatwasoriginallyregistered.Thereturnvalueiszeroiftheformatcan'tberegistered.



RGBComp()Returnsthered,green,andbluecomponentsofacompositeRGBcolorvalue.

Syntax

RGBComp(nRGBColor,@nRedVal,@nGreenVal,@nBlueVal)

nRGBColor

SpecifiesacompositeRGBcolorvaluerangingfrom0to16777215.

@nRedVal

SpecifiesareferencetoavariableinwhichthefunctionreturnstheintensityoftheredcolorcomponentofnRGBColor.

@nGreenVal

SpecifiesareferencetoavariableinwhichthefunctionreturnstheintensityofthegreencolorcomponentofnRGBColor.

@nBlueVal

SpecifiesareferencetoavariableinwhichthefunctionreturnstheintensityofthebluecolorcomponentofnRGBColor.

ReturnType

Logical

RmDir()Deletesadirectory.

Syntax

RmDir(cPath)

cPath

Specifiesthepathofthedirectoryorfoldertoberemoved.

ReturnType

Numeric

Remarks

ThisfunctionisonlyavailableinFoxtoolsversion1.01orlater.

Returns0ifsuccessfuland1ifnotsuccessful.

SetClipDat()SetsthedataontheopenedClipboard.

Syntax

SetClipDat(nFormat,cData)

nFormat

SpecifiesanidentifierforpossibleClipboardformats.


cData

SpecifiesthedatatoplaceontheClipboard.

ReturnType

Logical

Remarks

TheClipboardmusthavebeenopenedwithOpenClip()beforeyoucallthisfunction.IftheWindowsClipboardisrunning,itwon'tupdateitswindowtoshowthedataplacedintheClipboardbytheSetClipDat()functionuntilafter

theCloseClip()functioniscalled.


StrFilter()Removesallcharactersfromastringexceptthosespecified.

Syntax

StrFilter(cString,cSearch)

cString

Specifiesthecharacterstringtosearch.

cSearch

SpecifiesthecharacterstosearchforandretainincString.

ReturnType

Character

Remarks

StrFilter()removesallthecharactersfromcStringthataren'tincSearch,thenreturnsthecharactersthatremain.StrFilter()iscase-sensitive.

ValidPath()ChecksforavalidMS-DOSfilenameorpathexpression.

Syntax

ValidPath(cName)

cName

Specifiesthepathorfilenametobechecked.

ReturnType

Logical

Remarks

ValidPath()verifiesthatafilenameorpathnameissyntacticallylegal;itdoesn'tcheckfortheexistenceofthespecifiedfileorpath.Thefunctionisn'tfoolproofandcansometimesinterpretafileashavingavalidnamewhenthefilenameisactuallyinvalid.However,ValidPath()won'trejectavalidname.

Notsupportedinfilesystemsthatsupportspacesinpathnames.

WordNum()Returnsthespecifiedwordinastring.

Syntax

WordNum(cString,nIndex[,cDelimiter])

cString

Specifiesthestringcontainingthewordtobereturned.

nIndex

Specifiestheindexpositionofthewordtobereturned.Forexample,ifnIndexis3,WordNum()returnsthethirdword(ifcStringcontainsthreeormorewords).

cDelimiter

SpecifiesthecharacterusedtodelimitwordsincString.Thedefaultdelimitersarespace,tab,andcarriagereturn.

ReturnType

Character

Remarks

IfcStringcontainsfewerwordsthanthenumberspecifiedwithcIndex,WordNum()returnsanemptystring.

Words()Countsthenumberofwordsinastring.

Syntax

Words(cString[,cDelimiter])

cString

Specifiesthestringofwordstobecounted.

cdelimiter

SpecifiesthecharacterusedtodelimitwordsincString.Thedefaultdelimitersarespaceandtab.

ReturnType

Numeric

foxtools overview - documentation.help · foxtools is a visual foxpro api library that exposes...

Documents