Article ID: 190000 - View products that this article applies to.
This article was previously published under Q190000
This article demonstrates how to get started calling functions in the Windows Application Programming Interface (Windows API) in your Visual Basic projects. This article assumes you are familiar with using Visual Basic but have never used it to call the functions in the Windows API.
Although Visual Basic has an extensive list of statements, methods, events, and procedures to help you create a Windows program quickly and easily, there are limitations within the development environment that may prevent you from implementing your ideas. One way to go beyond these limitations is to call the Windows API from within your Visual Basic project. At the heart of the Windows operating system are the functions that make up the Windows API. The majority of these functions are accessible from Visual Basic programs.
The following topics are covered in this article:
What is the Windows API?If you look at the Windows System directory, typically \Windows\System under Window 95/98 and \Winnt\System32 under Windows NT, you will find a number of Dynamic Link Library (.DLL) files. These files contain functions that are used to run the operating system and to ensure a consistent user interface and operating environment. These files make up the Windows API.
The purpose of the Windows API is to allow you to develop programs consistent with the Windows operating system and user interface. Instead of individuals writing the code to create components of the Windows operating system, such as forms, command buttons, and menus, you can call the appropriate functions in the Windows API and let the operating system create those components.
The purpose of each function in the Windows API is documented in the Platform Software Development Kit (SDK). The Platform SDK is shipped with Microsoft Visual C++ and as part of a subscription to the Microsoft Developer Network (MSDN.)
You can also download the Platform SDK from the following Microsoft Web site:
http://www.microsoft.com/msdownload/platformsdk/setuplauncher.htmAs with any other Windows program, Visual Basic uses the functions in the Windows API. When you perform a task in Visual Basic, such as adding a command button to a form, Visual Basic calls the appropriate functions to perform the task. The features of Visual Basic are wrappers to these functions.
Why Use the Windows API?The reason why you would use the Windows API is to perform a task beyond what is available from Visual Basic. For example, you cannot determine or set the cursor blinking rate through any statement, property, procedure, or method in Visual Basic. You can get the blink rate by calling the GetCaretBlinkTime function, which returns the cursor blink rate in milliseconds. If you want to set the cursor to blink at another rate under specified conditions, you can call the SetCaretBlinkTime function, passing the specified time in milliseconds.
You can get the same functionality as almost any of the features of Visual Basic by calling the appropriate Windows API functions. However, calling these functions directly is typically more complicated and can cause unpredictable behavior if not done correctly, resulting in system errors. For the best performance and predictable behavior, you should use the intrinsic Visual Basic functionality.
How to Call a Windows API FunctionThere are two steps required to call a Windows API function:
For example, to declare the GetCaretBlinkTime function in a module, copy the following text to the code window of your module:
If you want to use the same function only in a specific form, add the keyword "Private" to the beginning of the function declaration. The GetCaretBlinkTime function declaration is written in the code window of a form as follows:
This function returns a Long value that is the cursor blink rate in milliseconds. The Lib keyword precedes the name of the file that contains the function; in this case, User32.DLL. The Alias keyword is used to define the specific function in the DLL file. This clause is optional when the function is being declared with the same name as in the DLL.
You will often see the Private notation used in Microsoft Knowledge Base articles because not using a module streamlines the implementation of the sample code. If you need to use a Windows API function in more than one source file in a project, it should be declared in a module.
For more information about the Declare statement, see "Declare Statement" in the Language Reference in Books Online.
Once you have declared the function, you can call it as you would any Visual Basic function and a pass any appropriate parameters. The following example shows how to call the GetCaretBlinkTime function:
For functions that require parameters, you can pass parameters by reference or by value.
A parameter passed by reference passes the 32-bit address of the location where the value is stored. By default, Visual Basic passes parameters by reference. You can also explicitly pass parameters by reference using the ByRef keyword.
The values of parameters passed by reference can be changed in the called procedure. For example, the InvertRect function inverts a specified rectangle by inverting the value of each pixel. The function requires the handle to the device context containing the rectangle and the address of a user defined type (UDT) variable with the logical coordinates of the rectangle. The address of the user defined variable is passed by reference.
When you call this function, the logical coordinates of the rectangle are placed in the user defined variable.
To use this function, add the following declarations to a module:
The first declaration specifies a user defined type required for a parameter of the InvertRect function while the second declaration is for the function.
Passing a parameter by value sends the actual value of the parameter to the function. You pass a parameter by value if the parameter is not changed by the called procedure. To pass a parameter by value, add the ByVal keyword to each parameter you want to pass to the function.
NOTE: When you pass a string variable to an API call, you actually pass the memory address of the string, so you should always pass string parameters as ByVal. If you pass a string parameter by reference, you pass the memory address containing the memory address of the string, which causes the API function receiving the parameter to behave incorrectly and may cause a memory violation error.
The SetCaretBlinkTime function requires the rate in milliseconds parameter to be passed by value to the function. Declare this function by adding the following statement to a module:
To use this function to set the cursor blink rate to 250 milliseconds, add the following to your project:
Sample ProjectThis section shows you how to create a sample project that controls the cursor blink rate by calling two functions in the Windows API. The GetCaretBlinkRate function returns the current blink rate in milliseconds while the SetCaretBlinkRate function sets the blink rate. Both of these functions will be declared in a module. You can also declare these functions in the form by prefacing each function declaration with the Private keyword.
NOTE: The SetCaretBlinkRate function sets the cursor blink rate for the operating system. If you exit the project before setting the blink rate back to the default, the cursor blink rate will change for all programs.
For more information about using the functions in the Windows API, refer to the following sources:
187674The following articles in the Microsoft Knowledge Base show you how to use functions in the Windows API to accomplish specific tasks:
(http://support.microsoft.com/kb/187674/EN-US/ )How To Find Undocumented Constants Used by Windows API Functions
(http://support.microsoft.com/kb/161161/EN-US/ )How To Search a ListBox Control Quickly
(http://support.microsoft.com/kb/175512/EN-US/ )How To Get a Short Filename from a Long Filename
(http://support.microsoft.com/kb/151799/EN-US/ )How To Use the Animated Copy Functions in Windows 95
Article ID: 190000 - Last Review: July 16, 2004 - Revision: 2.2