Understanding Handles

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Another important concept you must understand before calling functions in DLLs is that of the handle. A handle is a 32-bit positive integer that Microsoft® Windows® uses to identify a window or another object, such as a font or bitmap.

In Windows, a window can be many different things. A window can be a bounded rectangular area of the screen, such as the application window to which you are accustomed. A control on a form, such as a list box or scroll bar, might be a window also, although not all types of controls are windows. The icons that appear on your desktop and the desktop itself are windows.

Because all of these types of objects are windows, Windows can treat them similarly. Windows gives every window a unique handle and uses the handle to work with that window. Many API functions return handles or take them as arguments.

Windows assigns a handle to a window when it is created and frees the handle when the window is destroyed. Although the handle remains the same for the lifetime of the window, there is no guarantee that a window will have the same handle if it is destroyed and recreated. Therefore, if you store a handle in a variable, keep in mind that the handle will no longer be valid if the window is destroyed.

The GetActiveWindow function is an example of a function that returns a handle to a window — in this case, the application window that is active currently. The GetWindowText function takes a handle to a window and returns that window's caption, if it has one. The following procedure uses GetActiveWindow to return a handle to the active window and GetWindowText to return its caption:

Declare Function GetActiveWindow Lib "user32" () As Long
Declare Function GetWindowText Lib "user32" Alias "GetWindowTextA" _
   (ByVal Hwnd As Long, ByVal lpString As String, ByVal cch As Long) As Long

Function ActiveWindowCaption() As String
   Dim strCaption As String
   Dim lngLen   As Long
   
   ' Create string filled with null characters.
   strCaption = String$(255, vbNullChar)
   ' Return length of string.
   lngLen = Len(strCaption)

   ' Call GetActiveWindow to return handle to active window,
   ' and pass handle to GetWindowText, along with string and its length.
   If (GetWindowText(GetActiveWindow, strCaption, lngLen) > 0) Then
      ' Return value that Windows has written to string.
      ActiveWindowCaption = strCaption
   End If
End Function

The GetWindowText function takes three arguments: the handle to a window, a null-terminated string into which the window's caption will be returned, and the length of that string.

See Also

API Basics | What Is an API? | Why Use VBA to Call the Windows API? | API Resources | Accessing Functions in a DLL | Anatomy of a Declare Statement | Constants and User-Defined Types | Returning Strings from DLL Functions