Calling Windows API Subs and Functions
While VB is a very powerful language, sometimes you may want to incorporate functionality in your application that is not available with "straight" VB. Enter the Windows API (Application Programming Interface). The Windows API is a set of code libraries (DLL files) containing numerous functions for working with all aspects of Windows (graphics, the file system, fonts, low-level memory access, etc.). These function libraries are available to programmers coding with any Windows development system (VB, C++, Delphi, etc.).
While using the API is often treated as an "advanced" programming topic (and to be sure, using the API allows you to delve as deep into the depths of Windows programming as you desire), the coding actually set up and use an API function is relatively straightforward. The basic steps are:
- Declare the API sub or function with the Declare statement. The Declare statement must be coded in the general declarations section of a form or module, and can be declared with either Public or Private scope (Private only in forms). If declared as Public, any form or module in your VB application can use the function; if Private, only the form or module in which it is declared can use the function.
- Declare any variables and constants necessary to be used as parameters with the sub or function.
- Call the sub or function as you would any other sub or function. (Be advised that there are some differences between calling API functions versus regular VB subs and functions. Most notably, when dealing with strings, the keyword "ByVal" must be used when you really want to pass it by reference to get a return value back.)
To find the declarations and documentation necessary to use any of the 1000+ Windows API functions available, you can consult any of the numerous VB Help websites, or get a book such as Dan Appleman's "VB Programmer's Guide to the Win32 API".
VB itself comes with an add-in utility called the API Viewer, with which you can locate an API function by name and copy the declaration for it – but this utility does not document how to use the function; you would have to find that out from some other resource.
Using the API Viewer Utility
To use the API Viewer, go to the Add-Ins menu on VB's main menu bar, and choose Add-In Manager:
On the resulting Add-In Manager screen, locate the VB 6 API Viewer entry, and double-click it. The word "Loaded" should appear in the Load Behavior column, and the checkbox for "Loaded/Unloaded" in the lower right-hand corner should be checked. Check the "Load on Startup" checkbox if you want this utility available every time you use VB. Click OK when you are done.
Note: If you do NOT see the item "VB 6 API Viewer" in this list, please skip to the "Troubleshooting the API Viewer Add-In" section below.
Now, if you go to the Add-Ins menu, an item for API Viewer should be present:
Upon selecting API Viewer, the utility will come up:
Go the File menu. The first time you use this, you should select Convert Text to Database (this will make the utility faster to use). Subsequently, choose Load Database File:
From the resulting dialog box, select WIN32API.MDB:
Now the declarations for the available API functions have been loaded. You can perform searches to find the one(s) you want and copy their declarations for use in your program.
Troubleshooting the API Viewer Add-In
If you have been able to follow the steps above with no problem, please proceed to the Sample Program section below.
If someone other than yourself has installed Visual Basic or Visual Studio on your machine (such as a network administrator at your workplace), you may not see the various VB add-ins when you log onto your workstation. This problem is described in Microsoft Knowledge Base Article 190212 ("BUG: Add-Ins Only Visible to the User Who Installs VB"). The article does not reference the API Viewer specifically, however, the problem described in the article does apply here. To remedy the situation, first verify that the API Viewer utility program, called APILOAD.EXE, exists on your system. With a standard installation of Visual Studio/Visual Basic, that file, along with others should be located in the folder C:\Program Files\Microsoft Visual Studio\Common\Tools\Winapi.
If you cannot locate this file on your system, then this means that the option to include the API Viewer utility was not selected when Visual Studio/Visual Basic was installed. This certainly does not prevent you from using the API, it just means that you do not have this reference utility readily available. To do the sample program below, simply type in the function declaration for "FlashWindow" as opposed to copying and pasting.
Assuming that you located APILOAD.EXE, you can make it an add-in to the VB IDE by running this command from the "Run" box of the Windows "Start" menu (if necessary, substitute the correct drive and/or path information for your system):
"C:\Program Files\Microsoft Visual Studio\Common\Tools\Winapi\apiload.exe" /regserver
If the registration was successful, you should see the "VB 6 API Viewer" as an add-in option the next time you open VB, and you can go back follow the steps described above. If, for whatever reason, the registration was not successful, but you still have APILOAD.EXE on your system, you can run that as a stand-alone program instead of as an add-in from the IDE.
We will now build a simple "Try It" program that demonstrates the use of API functions. We will call upon the "Flash Window" function to make the title bar of our form blink on and off.
- Set up a new "Try It" program
- Go to the Add-Ins menu, choose API Viewer, and load the API database file
- Locate the FlashWindow function in the Available Items list.
- Click the Add button. The declaration should appear in the Selected Items area.
- Under "Declare Scope", choose Private.
- Click the Copy button.
- Close the utility.
- Open your code window, and paste the declaration under the Option Explicit line:
- If desired, "fix up" the declaration to break it into several lines for readability. Also, declare a private variable called mlngOnOrOff (long). Your general declarations section should look like this:
Option Explicit
Private Declare Function FlashWindow _
Lib "user32" _
(ByVal hwnd As Long, _
ByVal bInvert As Long) _
As Long
Private mlngOnOrOff As Long
- Place the following code in the cmdTryIt_Click event:
Private Sub cmdTryIt_Click()
Dim intX As Integer
Dim lngRetVal As Long
For intX = 1 To 1000
mlngOnOrOff = IIf(mlngOnOrOff = 0, 1, 0)
lngRetVal = FlashWindow(Me.hwnd, mlngOnOrOff)
Next
End Sub
- Run the program. When you click the "Try It" button, the title bar of the form should blink on and off.
We can analyze the code as follows. First, an explanation of the Declare statement. The Declare statement as it is used in this example, has the following general syntax:
[Public | Private] Declare Function FunctionName Lib LibraryName ([parameter list]) As datatype
The FunctionName specifies which Windows function we want to call, and the LibraryName specifies which DLL the function can be found in. In this example, we are looking for the FlashWindow function located in the user32.dll Windows system file. The arguments to this particular function are hwnd, which will tell the function which window we want to flash ("hwnd" is a "handle" or unique identifier associated with a window), and bInvert which is a number that will act like a flag to indicate whether we want to flash the window "on" or "off" (a value of 0 indicates off, anything else indicates "on"). The As Long specification at the end of our declaration indicates that the function will be returning a Long value. In the case of many API functions, a Long value will be returned to indicate the success or failure of the call.
In the loop where we call the function, we first toggle the variable that we will pass as the second parameter: if it's on, turn it off; if it's off, turn it on:
mlngOnOrOff = IIf(mlngOnOrOff = 0, 1, 0)
In the statement where we make the call, we pass the hwnd property of our form ("Me" refers to the form in which the code is currently running, and the ".hwnd" is a built-in property of the form) as well as the numeric flag value that we set in our variable mlngOnOrOff. In that the function returns a Long value, we are assigning that return value to the variable lngRetVal:
lngRetVal = FlashWindow(Me.hwnd, mlngOnOrOff)
Download the VB project code for the example above here.