Print Article

Seite 1 von 2

Issue Date: FoxTalk September 1997

Calling All Windows

Gary DeWitt

Have you ever seen an application that does something really cool but that Visual FoxPro won't let you do? Whatever it is, it can be done with the Windows Applications Programming Interface (API), most of which you can call from your VFP applications. This article is the start of a new column, Extending VFP through the API, dedicated to showing you how to increase the robustness of your VFP applications by unlocking the power of the Windows API.
Microsoft wrote the Windows API to expose the operating system's functionality to applications developers. Anything that you do in a Windows application ultimately calls the Windows API. Fortunately, Visual FoxPro handles most of these API calls for us. I wrote my first Windows program in C, hand-coding every API call myself. While it was a memorable experience, it's one I don't wish to repeat! FoxPro does a terrific job of hiding the complexity of the Windows API so that you can quickly write goodlooking Windows applications. But FoxPro doesn't do everything. The designers of Visual FoxPro knew that and gave us a tool we can use to call the Windows API ourselves, giving us the means to extend the functionality of our applications by taking direct control of the operating system. This tool is the DECLARE DLL statement. By using DECLARE, you can tell VFP how to find and call API functions. Here's an example of the most basic Windows API call: DECLARE INTEGER GetActiveWindow IN Win32API Here's how to translate this statement. The function is called GetActiveWindow, and the statement is called a declaration. This declaration of GetActiveWindow tells VFP that it's a function that takes no arguments, returns an integer, and can be found in Win32API. The Windows operating system is primarily made up of a bunch of DLLs. Five of these -- USER32.DLL, KERNEL32.DLL, GDI32.DLL, MPR.DLL, and ADVAPI32.DLL -- are collectively known as Win32API. Functions found in other DLLs, such as printer functions in WINSPOOL.DLL, require that you specify the name of the DLL in your declaration. Once a function has been declared, you can call it just as you would any built-in or user-defined function in FoxPro. * <some FoxPro code here> nHandle = GetActiveWindow() * <more FoxPro code that does something with nHandle> Windows API step by step There are a couple of things to keep in mind about using the Windows API. First, Windows assigns numbers, called handles, to all resources. If you want to refer to a resource in an API function, you must usually first call another function to get a handle for that resource. Second, the Windows API was written by and for C programmers. Most C programs don't pass values as arguments; they pass pointers. Pointers are nothing more than addresses of values. In FoxPro, passing by reference actually passes a hidden pointer to the API function, so you will usually pass by reference. There are normally five steps to take when using the Windows API:

n n n n n

Declare the API functions. Get a Windows handle to the resource you wish to control. Initialize memory variables for passing to the API. Call the function, passing arguments by reference. Use the values returned by the API function.

Here's a short program that uses the Windows API to find the text of the title bar of the main VFP window. The same thing could be done simply by checking the value of the _SCREEN.Caption property in VFP, but this code demonstrates each of the steps you must usually take when using the Windows API.

*-- Declare two API functions DECLARE INTEGER GetActiveWindow IN Win32API DECLARE INTEGER GetWindowText IN Win32API ; INTEGER, STRING @, INTEGER *-- Get the handle to the main VFP window

http://foxtalknewsletter.com/ME2/Audiences/Segments/Publications/Print.asp?Module=... 10.02.06

Print Article

Seite 2 von 2

nHandle = GetActiveWindow() *-- Initialize variables lcText = SPACE(100) lnSize = LEN(lcText) *-- Call the API function lnSize = GetWindowText(nHandle, @lcText, lnSize) *-- Use the resulting value IF lnSize > 0 ?LEFT(lcText, lnSize) ENDIF GetWindowText accepts three arguments -- the handle of the window, a pointer to the string containing the name, and the length of the string. To pass the second argument as a pointer, use an ampersand after the data type in the DECLARE statement, and before the variable name in the function call. In a future column I'll show you how to use functions like these to manipulate other applications, something that VFP doesn't let you do simply by checking a property. Rules, rules, rules Or perhaps I should say "rules, rules," because there are two hard-and-fast rules for using the Windows API: Never mix data types, and don't call functions that return pointers. Because the Windows API is written in C and because C is a strongly typed language, you must use the same data type specified in the documentation. VFP lets you pass pointers to the Windows API, but it won't return them. Just calling such a function can result in a GPF! Fortunately, such functions are the exception rather than the norm. How do you find this stuff? Visual FoxPro 3.0 ships with the best documentation I've ever seen for the Windows API: a help file called WIN32API.HLP. Unfortunately, Microsoft decided not to include this with VFP 5.0. This file describes functions and structures, but because it's written for C programmers, you'll have to know something about function prototypes and structure typedefs to use it. I'll be covering those topics in future columns. WIN32API.HLP requires that you know the values of the many constants that it references. I've put most of the constants in WINDOWS.H in the accompanying Download file . Another excellent source of documentation on Windows API calls is included with Visual Basic. Now that VB and VFP are both part of Microsoft's Visual Studio bundle, many of you have VB 5.0. The API Text Viewer contains all the function calls, constants, and structures used by the Windows API. The Viewer is for VB programmers, of course, so everything is in VB syntax and will have to be translated to VFP. This is pretty easy, though, because VB is closer to VFP than C is. The biggest drawback to the API Text Viewer is that it only lists code without describing how to use it. More to come There's a lot to learn about the Windows API: structures, pointers, structures of pointers and devices. I'll cover all of them in the next several months. Each month I'll show you how to do something cool, while incorporating all of that C esoterica a little at a time. If there's something you're just dying to figure out how to do, let me know what it is.

http://foxtalknewsletter.com/ME2/Audiences/Segments/Publications/Print.asp?Module=... 10.02.06