This is the first in a series of tutorials for using API calls. It covers the most fundamental information. Later tutorials will go into more depth.
What is an API Call?
An API call is a function contained in a library file, called a Dynamic Link Library or DLL. These files have an extension of "*.DLL".
Here is an example of an API call. We can use it to determine if a window or control is enabled or disabled.
CallDLL #user32, "IsWindowEnabled",_
hButton asuLong,_ 'handle of window or control
result AsBoolean'nonzero = enabled
Liberty BASIC allows us to enable or disable a window or control, but there is no Liberty BASIC function to discover if a window or control is currently enabled or disabled. We can get around that limitation with this handy API function. Here is a Liberty BASIC program that makes use of the "IsWindowEnabled" API function. Copy it and paste it into Liberty BASIC, then run it to see how it works.
nomainwin
'open a program window
button #1.enable, "Enable/Disable",[doEnable],UL,10,10
button #1.quit, "Quit", [quit], UL, 10, 60
open "API Demo"for window as #1
#1"trapclose [quit]"'get the handle of the quit button
hButton = HWND(#1.quit)
wait
[doEnable]'The IsWindowEnabled function determines whether the'specified window or control is enabled'for mouse and keyboard input
CallDLL #user32, "IsWindowEnabled",_
hButton asuLong,_ 'handle of window or control
result AsBoolean'nonzero = enabled'a result of 0 means that the window is NOT enabled'a nonzero result means that the window IS enabledif result =0then'if button was disabled, enable it
#1.quit"!enable"else'if bitton was enabled, disable it
#1.quit"!disable"endif
wait
[quit] close #1 : end
Functions
What is a function? It is a block of code that takes in an argument or a list of arguments and returns a value. That sounds a little complicated, doesn't it? It's kind of like my bread machine. I put a list of ingredients into my bread machine, including flour, yeast and water. My bread machine takes these ingredients and manipulates them, then returns a loaf of fresh-baked bread to me.
The list of ingredients can change. If I put in white flour, my bread machine returns white bread. If I use rye flour, it returns rye bread. If I use whole wheat flour, it returns wheat bread.
A function accepts a list of ingredients that we call arguments. (They can also be called parameters.) It manipulates these arguments and returns a value.
Liberty BASIC has many built-in functions. One of them is the MAX() function. It takes in two arguments and it returns a value. The arguments are numbers. The returned value is the larger of the two arguments. In the example below, the returned value is contained in the variable "z". The MAX() function accepts the two arguments, in this example they are the number 7 and the number 2, and it places the larger of those two numbers into the variable "z". Printing z produces "7".
z = MAX(7,2)
print z
The arguments can be variables. The code using variables in place of literal numbers looks like this:
x =7
y =2
z = MAX(x,y)
print z
API calls are functions. We give the API function a list of arguments and it returns a value, which we store in a variable. API functions are similar to Liberty BASIC's built-in functions, but the syntax is a little different. API functions are accessed with the CALLDLL statement.
CALLDLL
The CALLDLL statement needs to know which DLL is to be used. The DLLs in Windows are recognized by Liberty BASIC without a need to open them. We refer to them by their handles. A very common and useful DLL is called "user32.DLL". Liberty BASIC gives us a handle for this DLL. It is "#user32". The first part of an API call to user32 looks like this:
CALLDLL #user32,
That's not all, though! More information follows that statement, and we'll talk about each part in order.
Take note that CALLDLL statements must be on a single line. We often split them into multiple lines to make them easier to read. We do this by using the underscore line continuation character as we did in the demonstration program above. It allows us to write a statement of code on multiple lines so that we can add comments and avoid the need to read long lines of code, but Liberty BASIC still sees the statement as a single line of code.
Here is an API call on one line of code:
CallDLL #user32, "IsWindowEnabled", hButton asuLong, result AsBoolean
Here is the same API call broken into several lines with the underscore line continuation character. This allows us to add comments to each argument.
CallDLL #user32, "IsWindowEnabled",_
hButton asuLong,_ 'handle of window or control
result AsBoolean'nonzero = enabled
API Function Names
The next part of the CALLDLL statement is the name of the API function. It is a text string and it must be enclosed in quotation marks. The name is case sensitive, so "FunctionName" is not the same as "FUNCTIONNAME". Be sure to copy the capitalization properly. A generic CALLDLL statement looks like this:
calldll #dll, "FunctionName",...
An actual API function called "IsWindowEnabled" looks like this:
CallDLL #user32, "IsWindowEnabled",...
API Arguments
Each API call has a set list of arguments that must be passed into the function. Each of these arguments gives the API function some information. The function evaluates this information. It returns a value based on the information in these arguments. Arguments can be literal numbers or strings, or they can be numeric or string variables. They cannot be array elements or expressions.
Arguments are passed "as type". You can read more about types later in this tutorial.
Acceptable arguments:
calldll #dll, "FunctionName", argument1 as type1,...calldll #dll, "FunctionName", 23as type2,...calldll #dll, "FunctionName", "Some Text"as type3,...var$ ="A bit of text."
calldll #dll, "FunctionName", var$ as type4,...
Some API functions require many arguments. A function with three arguments looks like this:
calldll #dll, "FunctionName", argument1 as type1, argument2 as type2, argument3 as type3,...
Handles
Many API calls require the Windows handle of a program window or control as one of the arguments.This Windows handle is a number of type ULONG. It is not the same as the "#handle" Liberty BASIC handle. We retrieve the Windows handle with the HWND() function and store it in a variable. In this example, the variable is called "hButton".
button #1.quit, "Quit", [quit], UL, 10, 60
open "API Demo"for window as #1'get the handle of the quit button
hButton = HWND(#1.quit)
Types
API functions need to know what kind of argument is being passed in. Arguments can be numbers, strings or structs. We will talk about numeric arguments in this tutorial.
The most common numeric types are these. Types that hold numbers that are 4 bytes in size include ulong and long. Types that hold numbers that are 2 bytes in size include short, ushort, word and boolean. There are other types, but we won't discuss them in this tutorial.
A CALLDLL statement looks like this with actual types used in the arguments:
calldll #dll, "FunctionName", argument1 asulong, argument2 as word, argument3 aslong,...
Handle Types
In Liberty BASIC, handles must always be passed as either "ulong" type or "word" type. In the demonstration program at the start of this tutorial, the "hButton" handle is passed "as ulong".
Return Values
API functions return a value, and we must include the "as type" for that value, just as we did for the list of arguments. There is a return type of "void" for functions that perform an action, but do not return a value. The numeric return types include ulong, long, short, word, ushort and boolean.
Here is a generic call that includes the return value. The returned value is always the last part of the CALLDLL statement.
calldll #dll, "FunctionName", argument1 asulong, argument2 as word, result asboolean
Note that you cannot use a variable name for the return type that is called "return" because that is a Liberty BASIC statement. Variable names cannot be the same as statement or function names in the Liberty BASIC language. Liberty BASIC programmers often use a variable name of "result" to contain the value returned by the API function.
Our programs might need to know the value returned by the function so that they can perform the proper actions. Use "if/then" to manage program flow after an API call has been made.
Demo
Here again is the demonstration program. It opens a Liberty BASIC window that contains two buttons. It retrieves the handle of the Quit button with the HWND() function. It passes that handle into a user32.dll function called "IIsWindowEnabled". The IsWindowEnabled function returns a value telling the program whether the window or control whose handle is passed as an argument is enabled at the time the function is called. If the quit button is enabled, the program disables it. If it is disabled, the program enables it.
The handle is passed as type "ulong". The return type is "boolean". A boolean value is either nonzero (meaning it is true) or zero (meaning it is false.) If IsWindowEnabled returns a value of 0, the window is not enabled. If it returns any other value than 0, the window is enabled when the function is called.
nomainwin
'open a program window
button #1.enable, "Enable/Disable",[doEnable],UL,10,10
button #1.quit, "Quit", [quit], UL, 10, 60
open "API Demo"for window as #1
#1"trapclose [quit]"'get the handle of the quit button
hButton = HWND(#1.quit)
wait
[doEnable]'The IsWindowEnabled function determines whether the'specified window or control is enabled'for mouse and keyboard input
CallDLL #user32, "IsWindowEnabled",_
hButton asuLong,_ 'handle of window or control
result AsBoolean'nonzero = enabled'a result of 0 means that the window is NOT enabled'a nonzero result means that the window IS enabledif result =0then'if button was disabled, enable it
#1.quit"!enable"else'if bitton was enabled, disable it
#1.quit"!disable"endif
wait
[quit] close #1 : end
Alyce
Feb 23, 2007
The ABCs of APIs Lesson 1
Table of Contents
What is an API Call?
An API call is a function contained in a library file, called a Dynamic Link Library or DLL. These files have an extension of "*.DLL".
Here is an example of an API call. We can use it to determine if a window or control is enabled or disabled.
Liberty BASIC allows us to enable or disable a window or control, but there is no Liberty BASIC function to discover if a window or control is currently enabled or disabled. We can get around that limitation with this handy API function. Here is a Liberty BASIC program that makes use of the "IsWindowEnabled" API function. Copy it and paste it into Liberty BASIC, then run it to see how it works.
Functions
What is a function? It is a block of code that takes in an argument or a list of arguments and returns a value. That sounds a little complicated, doesn't it? It's kind of like my bread machine. I put a list of ingredients into my bread machine, including flour, yeast and water. My bread machine takes these ingredients and manipulates them, then returns a loaf of fresh-baked bread to me.The list of ingredients can change. If I put in white flour, my bread machine returns white bread. If I use rye flour, it returns rye bread. If I use whole wheat flour, it returns wheat bread.
A function accepts a list of ingredients that we call arguments. (They can also be called parameters.) It manipulates these arguments and returns a value.
Liberty BASIC has many built-in functions. One of them is the MAX() function. It takes in two arguments and it returns a value. The arguments are numbers. The returned value is the larger of the two arguments. In the example below, the returned value is contained in the variable "z". The MAX() function accepts the two arguments, in this example they are the number 7 and the number 2, and it places the larger of those two numbers into the variable "z". Printing z produces "7".
The arguments can be variables. The code using variables in place of literal numbers looks like this:
API calls are functions. We give the API function a list of arguments and it returns a value, which we store in a variable. API functions are similar to Liberty BASIC's built-in functions, but the syntax is a little different. API functions are accessed with the CALLDLL statement.
CALLDLL
The CALLDLL statement needs to know which DLL is to be used. The DLLs in Windows are recognized by Liberty BASIC without a need to open them. We refer to them by their handles. A very common and useful DLL is called "user32.DLL". Liberty BASIC gives us a handle for this DLL. It is "#user32". The first part of an API call to user32 looks like this:That's not all, though! More information follows that statement, and we'll talk about each part in order.
Take note that CALLDLL statements must be on a single line. We often split them into multiple lines to make them easier to read. We do this by using the underscore line continuation character as we did in the demonstration program above. It allows us to write a statement of code on multiple lines so that we can add comments and avoid the need to read long lines of code, but Liberty BASIC still sees the statement as a single line of code.
Here is an API call on one line of code:
Here is the same API call broken into several lines with the underscore line continuation character. This allows us to add comments to each argument.
API Function Names
The next part of the CALLDLL statement is the name of the API function. It is a text string and it must be enclosed in quotation marks. The name is case sensitive, so "FunctionName" is not the same as "FUNCTIONNAME". Be sure to copy the capitalization properly. A generic CALLDLL statement looks like this:An actual API function called "IsWindowEnabled" looks like this:
API Arguments
Each API call has a set list of arguments that must be passed into the function. Each of these arguments gives the API function some information. The function evaluates this information. It returns a value based on the information in these arguments. Arguments can be literal numbers or strings, or they can be numeric or string variables. They cannot be array elements or expressions.Arguments are passed "as type". You can read more about types later in this tutorial.
Acceptable arguments:
Some unacceptable arguments:
Some API functions require many arguments. A function with three arguments looks like this:
Handles
Many API calls require the Windows handle of a program window or control as one of the arguments.This Windows handle is a number of type ULONG. It is not the same as the "#handle" Liberty BASIC handle. We retrieve the Windows handle with the HWND() function and store it in a variable. In this example, the variable is called "hButton".Types
API functions need to know what kind of argument is being passed in. Arguments can be numbers, strings or structs. We will talk about numeric arguments in this tutorial.The most common numeric types are these. Types that hold numbers that are 4 bytes in size include ulong and long. Types that hold numbers that are 2 bytes in size include short, ushort, word and boolean. There are other types, but we won't discuss them in this tutorial.
A CALLDLL statement looks like this with actual types used in the arguments:
Handle Types
In Liberty BASIC, handles must always be passed as either "ulong" type or "word" type. In the demonstration program at the start of this tutorial, the "hButton" handle is passed "as ulong".Return Values
API functions return a value, and we must include the "as type" for that value, just as we did for the list of arguments. There is a return type of "void" for functions that perform an action, but do not return a value. The numeric return types include ulong, long, short, word, ushort and boolean.Here is a generic call that includes the return value. The returned value is always the last part of the CALLDLL statement.
Note that you cannot use a variable name for the return type that is called "return" because that is a Liberty BASIC statement. Variable names cannot be the same as statement or function names in the Liberty BASIC language. Liberty BASIC programmers often use a variable name of "result" to contain the value returned by the API function.
Our programs might need to know the value returned by the function so that they can perform the proper actions. Use "if/then" to manage program flow after an API call has been made.
Demo
Here again is the demonstration program. It opens a Liberty BASIC window that contains two buttons. It retrieves the handle of the Quit button with the HWND() function. It passes that handle into a user32.dll function called "IIsWindowEnabled". The IsWindowEnabled function returns a value telling the program whether the window or control whose handle is passed as an argument is enabled at the time the function is called. If the quit button is enabled, the program disables it. If it is disabled, the program enables it.The handle is passed as type "ulong". The return type is "boolean". A boolean value is either nonzero (meaning it is true) or zero (meaning it is false.) If IsWindowEnabled returns a value of 0, the window is not enabled. If it returns any other value than 0, the window is enabled when the function is called.
Table of Contents