| Microsoft Office 2000/Visual Basic Programmer's Guide | |
Another important concept that you need to understand before calling functions in DLLs is that of the handle. A handle is simply a 32-bit positive integer that Windows uses to identify a window or another object, such as a font or bitmap.
In Windows, a window can be many different things. In fact, almost anything that you can see on the screen is in a window, and most things that you can't see are also in windows. A window can be a bounded rectangular area of the screen, like the application windows that you're accustomed to. A control on a form, such as a list box or scroll bar, may also be a window, 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's currently active. 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. For more information about passing strings to DLL functions, see "Returning Strings from DLL Functions" later in this chapter.
The ActiveWindowCaption procedure shown in the previous example is available in the modActiveWindowCaption module in MiscAPIFunctions.xls in the ODETools\V9\Samples\OPG\Samples\CH10 subfolder on the Office 2000 Developer CD-ROM.