There are about 1000 most often used API functions built-in. Some of these functions have reserved names, names that are already in use by the BASIC language. Those functions are renamed and are available under an alias.
A built-in function always uses the return value, either by using it in an expression or by voiding the value. For instance:
Dim p%
p% = CharLower("ABC") // expression
~CharLower("ABC") // ~ void
Void CharLower("ABC") // void
The Windows API supports both ANSI and UNICODE functions. The GFA-BASIC 32 built-in functions are the ANSI variant.
Many API functions take the C data type LPSTR (or LPTSTR, LPCSTR, etc) as a parameter. This is a pointer to a null-terminated string. When passing a string data type pass the address of the character data using the VarPtr function or the V: operator.
Dim api$ = "ABC"
~CharLower(V:api$) // address of the string
When a string is passed 'by value', as in the first example, the string is first copied to an internal buffer of 1030 bytes. Then the address of the buffer is passed to the API function. This has two disadvantages. First any strings larger than 1029 characters are cut off. Secondly, API functions that return text data to a LPSTR buffer are not received by the program, because they are copied to the temporal buffer.
The built-in functions are not checked for a correct syntax, only for the correct number of parameters. In fact, each parameter of the built-in functions is simply a 32-bit integer. What ever you pass to that integer is the responsibility of the programmer.
A user-defiined type can be passed by address using V: or 'by value', without the V:. GFA-BASIC 32 always passes the address of the type variable.
The following API functions are renamed due to there use as reserved keyword for a BASIC command or function. Note some got two new names.
GetObject in GetGdiObject or apiGetObject
LoadCursor in LoadResCursor or apiLoadCursor
lstrcmpi in _lstrcmpi
lstrcmp in _lstrcmp
The following 16-bit API functions are not included:
GetBitmapDimension, SetBrushOrg, GetBrushOrg, GetCurrentPosition, PostAppMessage, SetConvertHook, SetConvertParams, ConvertRequest, DefHookProc, GetAspectRatioFilter, GetCurrentTask, GetNumTasks, SetSysModalWindow, and UnlockResource
{Created by Sjouke Hamstra; Last updated: 12/05/14 by James Gaite}