Killer Win32 API
Originally Presented at the
9th Annual Borland Conference
Denver, Colorado
August 9, 1998
Keith G. Chuvala, First Intermark Corp.
mailto:kgc@pdq.net - http://www.sckans.edu/~kgc
Introduction to the Win32 API for Visual dBASE Developers
The Win32 API (Application Programming Interface) is the developer’s connection to the inner and outer workings of Windows 95, 98, and NT. The API is your gateway to a huge collection of functions that make up the core of Windows itself and the bulk of many of its applications. Learning and understanding key components of the API and getting comfortable with the techniques involved in exploiting it allows us to not only produce applications with greater functionality, but also to better understand how Windows itself “sees the world” and why it works the way it does.
Visual dBASE 7 provides a powerful development environment and a terrific object-oriented language, but like any other development product, it cannot be all things to all developers. I’ve yet to encounter a language product that natively supports every capability we want or need to supply in our own applications. But “under the hood” Microsoft has written myriad useful functions into Windows itself, and in many cases these functions supply part or all of the added functionality we desire. Of course, Windows is not written in the dBASE language, so accessing those functions often requires some extra effort on our part.
Our goal is to make a Windows API function “look like” a regular Visual dBASE function that can be called by our VdB applications as needed. As you’ll see there are also myriad constant values used by API functions, and these constants will need to be added to our applications as well. In many cases, then, two or more steps are required to successfully access the functions available through the Windows API. Typically we’ll create or use constants with #define, then describe (or “prototype”) the function using dBASE’s EXTERN command.
In this tutorial we will cover the fundamentals of accessing the API using these dBASE tools, then we’ll work forward, moving into specific important functions available to use through the API. Along the way there is a lot of jargon and techno-speak, so be sure to take notes and ask questions as we go! Finally we’ll look at a number of useful API-laden tools developed by dBASE developers around the world.
Deciphering Win32API.H and Friends
The Visual dBASE installation program creates a number of files that will be referenced throughout this tutorial. These files are filled with #define and EXTERN statements that are required to access the various functions in the Windows API. In most cases we will not have to write those statements ourselves, but rather will need to include these dBASE-supplied files in our programs and projects.
Win32API.H is actually little more than a “front end” to other API-related files. The files we’ll be examining are found in the INCLUDE and SAMPLES directories under your Visual dBASE “home” directory. If you don’t find these files in your installation, you might need to reinstall VdB.
Here are the files we’ll be working with from the Visual dBASE INCLUDE directory:
Win32API.h Loads other .H files
WinBASE.h Oodles of API constants
WinDEF.h Type definitions that help us “fake” C data types
WinREG.h Constants used with registry-related API
WinERROR.h Windows error codes
WinGDI.h Constants and such for drawing (Graphics Device Interface)
WinMISC.h Constants for Networking, Shell, and other functions
WinUSER.h User interface constants
StructAPI.h Constants used with STRUCMEM.DLL
Win32API.prg Monster-sized prototype/EXTERN program
In the Visual dBASE SAMPLES directory we’ll use:
StructAPI.prg Prototypes/EXTERNs for STRUCMEM.DLL
Structure.prg Custom class front end to STRUCMEM.DLL functions
Registry.prg Custom class front end to Windows registry API
Win32API.wfm VdB sample form illustrating various API functions
This is not a complete list of the files in the INCLUDE and SAMPLES directories; we simply won’t have time to cover all of them in any detail. Instead we’ll concentrate on fundamental concepts and techniques that you can easily extend to other functions.
A quick word about the filenames above. The ‘.h’ file extension denotes a “header file,” and originally came into wide use with the C language. It’s such a common convention that Visual dBASE adheres to it. Header files can include valid code of any kind, but the traditional (and highly recommended) standard convention is that only data type definitions, constant values, and such be stored in them. So-called “executable” code (actual program logic) should be written in .PRG, .WFM, and other such files. Hiding UDFs or other code in header files is permissible, but it goes against convention and makes that code harder to locate when you go looking for it 6 months down the road!
Using EXTERN
The EXTERN command is used to construct a prototype of a non-VdB function. Such functions are typically API functions, or contained in vendor-supplied .DLL files. In order for VdB to call a foreign function, it must be told via the EXTERN statement what argument(s) the function requires, the types of the argument(s), and what data type the function returns to dBASE, if any.
For our fist simple example, here’s the prototype for the WinAPI Beep() function, which simply beeps the speaker at a given frequency for a given duration, or in dBASE, will play the default sound if it has been setup via the Control Panel Sounds applet.
Extern CINT Beep(CLONG, CLONG) kernel32
We’ll talk about CINT and CLONG in a bit. For now, just type the command into the Command Window, or add it to a program file. NOTE: The case of “Beep” must be matched exactly! While dBASE ordinarily doesn’t care if commands are capitalized, all lowercase, or otherwise, other languages do, and the API functions are case-sensitive. So you can’t use BEEP, beep, bEEp, or BeeP; it’s gotta be Beep.
The parameters (or arguments) in the prototype specify what data types dBASE will have to pass to the API function. These must match up with the data types of the actual function as closely as possible. dBASE does a decent job of translating things for us, but clearly there’s some non-dBASE lingo to learn here. We’ll cover this in more detail in the “Data Types in EXTERN Statements” section that follows.
The final item in the statement is the name of the dynamic link library (“DLL”) or module in which the function is actually located. If this is a built-in Windows module (Kernel32, User32, GDI32, ADVAPI32, SHELL32, etc.) or one which dBASE itself always loads (IDAPI32, for example), no filename extension need be specified. For other functions, you’ll need to specify the full name (e.g. MPR.DLL, COMDLG32.DLL, etc.)
Now, if you goofed typing in our Beep line above, you’ll be greeted with an error, most likely something like this:
So try it again and get it right this time J.
To execute the function, simply type the function call in the Command Window as if it were any other dBASE function:
beep()
Your speaker will sing if you have a sound setup for the default beep. Note that I didn’t match the case here, yet it still works! The above restriction on case sensitivity applies to prototyping the function only; in standard dBASE practice you can mix case at will in your dBASE code. I recommend, however, that you stick as closely to convention as possible; it’s best to match the case of all API functions and constants exactly. This makes for consistent and clear code, and besides, if the next guy or gal to come along and work on your code happens to have a background in C, they’ll try to strangle you if you mixed case arbitrarily!
Data Types in EXTERN Statements
In the previous example we used non-dBASE data types to prototype the Beep() function. This is necessary because dBASE’s data types don’t always match up well with those of other languages. Since Windows and most all of its components are written in C or C++, we have to match up data types with those expected by functions written in those languages. Here’s a list of built-in data types supported in Visual dBASE specifically for use with EXTERN, as reported in the Visual dBASE documentation:
dBASEKeyword |
As Pointer |
dBASEData Type |
Size |
API (WindEF.H)Data Type(s)* |
|
CINT |
CPTR CINT |
Numeric |
32 bits |
INT |
|
CLONG |
CPTR CLONG |
Numeric |
32 bits |
LONG |
|
CSHORT |
CPTR CSHORT |
Numeric |
16 bits |
SHORT WCHAR |
|
CCHAR |
|
Numeric |
8 bits |
CHAR |
|
|
CSTRING |
String |
Null-terminated |
LPSTR LPCSTR Most STRINGs |
|
CHANDLE |
|
Numeric |
32 bits |
HANDLE CHWND Most Hxxx types |
|
CUINT |
CPTR CUINT |
Numeric |
32 bits |
UINT WPARAM |
|
CLONG |
CPTR CULONG |
Numeric |
32 bits |
LONG DWORD LPARAM LRESULT |
|
CUSHORT |
CPTR CUSHORT |
Numeric |
16 bits |
WORD ATOM |
|
CUCHAR |
|
Numeric |
8 bits |
BYTE |
|
CFLOAT |
CPTR CFLOAT |
Numeric |
32 bits |
FLOAT |
|
CDOUBLE |
CPTR CDOUBLE |
Numeric |
64 bits |
LONGLONG DWORDLONG |
|
CLDOUBLE |
CPTR CLDOUBLE |
Numeric |
80 bits |
|
|
CLOGICAL |
CPTR CLOGICAL |
Logical |
8 bits |
BOOL |
|
CVOID |
|
none |
N/A |
VOID |
* In most cases, a single dBASE C-type will correspond to multiple API types. When in doubt, check the WinDEF.h header file (see below). This table lists only a few of the API types!
Some of these might seem hard to understand, but rather than go into the significance and nuances of each, suffice it to say at this point that your task is simply to match up the dBASE data type you’re using with the closest C-style data type. When constructing EXTERN statements, you’ll just need to use the type specified in the API function’s documentation. Which poses another challenge!
To illustrate the problem, load up Win32API.PRG in the source editor and find the EXTERN statement for the Beep() API function. It reads like this:
extern BOOL Beep(DWORD, DWORD) kernel32
Uh oh. BOOL and DWORD are not in our list of built-in types as listed above. And in fact, most API documentation you use, be it from Inprise, Microsoft, or another vendor, will likely use a set of data type descriptors that aren’t native to any language in particular, but rather were derived specifically for work within the Windows framework. Rather than defining a specific language’s data type, they instead describe a fundamental data type that any language should have a match for.
The “fix” to this problem is supplied in the VdB-supplied WinDEF.H header file, which is a collection of #define statements mapping dBASE’s build-in C data types to these new windows data types. Hence the following advice is important:
When working with Windows API functions, ALWAYS #include <WinDEF.h> in your program! Otherwise you’ll have to convert documented data types by hand.
The WinAPI.PRG program #includes this file already, and as you’ll see, you’ll probably also want or need to include other .H files, depending on the API functions you are calling. During this tutorial and in this paper my goal is to make as many examples as possible run-able from the command window. So most of the examples here will use the built-in types.
What about Structures?
Another complication arises with some API functions. In C, there is a mechanism called a struct, which allows the programmer to package two or more variables into one variable. The variable itself is said to be “of type struct <struct_name>” where struct_name is whatever the programmer decided to call his new data type. Even if you’re not a C programmer, you can see the effect in the following:
// simple.c: a simple structure
struct pixel
{
int xcoord;
int yccord;
int color;
};
void main(void)
{
struct pixel one_point;
}
In this short example we’ve created a new data type called “struct pixel,” which contains 3 variables (called “members”). In the main() function we’ve declared one variable, called one_point. This variable contains 3 members, per the definition of the data type, which are called one_point.xccord, one_point.ycoord, and one_point.color. Look familiar? Sure, it’s just like a dBASE object. When we create a new form object with code like f = new form(), we know that f has members like Text, ColorNormal, Open, OnClose, etc. Such is a struct, though structs as used by the Windows API most often contain only memory variables (properties, if you will), and not events or methods (though those elements can be contained in C++ structs, so beware!)
Here’s a fairly simple API function that returns the coordinates of a window’s client area. Again, to facilitate typing this into the command window, I’ll use the built-in data types rather than the ones you’d find in the Windows API reference:
extern CLOGICAL GetClientRect( CHANDLE, CPTR ) USER32
The two arguments GetClientRect() expects are a CHANDLE, the window’s handle (the HWND property of a dBASE form, usually), and a CPTR, the address of a 16-byte structure in memory that will be used to store the coordinates. So we need to create a 16-byte “buffer” that the function can use to store the individual coordinate values (one coordinate each 4 bytes – top, left, bottom, right). And it’s this buffer that poses the problem
Visual dBASE has two problems with this kind of data type. First, although dBASE sports the generic Object type into which we can package variables seemingly just like a C struct, in memory it’s built very differently, and the API functions that expect structs will also expect them to have C-style structure. So what do we dBASE folks have at our disposal for packing data together in a very precise way? Strings, that’s what. We can pack a string with the data required and pass it to the API function like it were a C style struct.
Well, except for the second problem. J
Visual dBASE 7.x is architected to be easily ported to different languages (the human kind, that is!) To facilitate multiple character sets, some of which require more than one byte per character, VdB strings are Unicode, which means that (among other things) they are 2 bytes per character. So building a C style struct with simple string concatenation (which is what we did in previous releases of Visual dBASE) no longer works; the resulting struct is 2 times too large, and data offsets are all incorrect.
So while we might be tempted to try this to get the bottom coordinate from bytes 8 and 9, it would not produce the correct results:
f = new form()
f.open()
cBuffer = space(16) // This will produce 32 bytes!
GetClientRect(f.hwnd,cBuffer)
? val(cBuffer[8])+(val(cBuffer[9])*256) // nothing there!
Fortunately the Visual dBASE gurus at Borland added some new capabilities aimed specifically at overcoming this obstacle. The new String class includes methods SetByte() and GetByte() that allow us to set or get the value of a specific byte within a string. So the corrected code for the above example might look like this:
f = new form()
f.open()
cBuffer = space(8) // This will produce 16 bytes!
GetClientRect(f.hwnd,cBuffer)
? cBuffer.getbyte(8) + cBuffer.getbyte(9)*256 // Correct!
Included in the VdB SAMPLES directory you’ll find Structure.PRG and the attendant files StructAPI.H, StructAPI.PRG, and STRUCMEM.DLL. These files offer a higher-level interface for exchanging structures with API functions. The files contain internal documentation (particularly useful are the comments in STRUCTURE.PRG, and with Win32API.WFM form in the SAMPLES directory demonstrates its use as well.
Without getting too deep into the code, this code is intended to be used to create a custom class that takes on the form of the structure needed for an API call. You create an instance of that class, and pass its Value property to the API function. For now we’ll show an example using the GetClientRect() function to get some useful information, namely the size of the dBASE shell’s client area.
// STRUCTDEMO.PRG: Demonstrate essentials of STRUCTURE.PRG
// Uses GetClientRect() to retrieve _App.FrameWin client size
#include <structapi.h> // type definitions
set procedure to _dbwinhome+"samples\structure" additive
if type("GetClientRect") # "FP"
extern CLOGICAL GetClientRect( CHANDLE, CPTR ) USER32
endif
clear
sBuff = new ClientRect_Struct() // Create and instance of the stucture
GetClientRect(_app.framewin.hwnd,sBuff.value) // call the API function
? "Size of Visual dBASE Client Rectangle"
? "-------------------------------------"
? "Height:", sBuff.getmember("Bottom")
? "Width: ", sBuff.getmember("Right")
CLASS ClientRect_Struct of structure // structure definition per
// Win32API.h
super::addMember( TYPE_DWORD, "Top")
super::addMember( TYPE_DWORD, "Left")
super::addMember( TYPE_DWORD, "Bottom")
super::addMember( TYPE_DWORD, "Right")
endclass
Of course you don’t have to create a custom class; you could build the structure on the fly. Encapsulating the structure in a class makes it far easier to reuse, of course.
Character Buffer Considerations
Related to the above concern about Unicode strings, some API functions return strings all neatly filled in for us. But they’re regular non-Unicode strings, and dBASE’s can’t work with them. Again, we can use GetByte to do the conversion for us. Among the code listings at the end of this paper you’ll find Jim Sare’s fix for GetModuleFileName(), which returns the executable program name associated with a running application. The function fills in a string you supply when it is called, but it fills the string with 1-byte characters, so we have the reverse problem we had with structures. Jim’s code is a fine example of how you can convert these character buffers into useful strings.
Name Changes between Win3x and Win32
Windows 95 (and Windows 98) are as backward compatible as possible, which is good. And which is bad. Numerous compromises had to be made to facilitate both the old 16-bit Windows API and the new 32-bit Windows API. There are numerous API functions that are available to both, so of course one or the other name had to change, and it is in almost all cases the 32-bit version. Often the name change is simply the addition of “A” to the end of the function name (e.g. “FindWindow” for 16 bit and “FindWindowA” for 32-bit. There are also numerous “extended” API functions that have been added, and frequently an “Ex” suffix is added to the original function name (e.g. “FindWindowEx”).
The most noticeable change for developers who did some WinAPI work in Visual dBASE 5.x is that the fundamental Windows modules have changed. In the 16-bit world (including compatibility mode in Win9x and WinNT), the modules that contain most of our WinAPI functions were called USER and KERNEL. In Win32 they are USER32 and KERNEL32, respectively.
The Windows Registry
Those who use Visual dBASE to create applications for distribution should pay attention to a few issues that might fall under the guise of “well-behaved” Windows applications. In the days of Windows 3.1, it was common practice (and in fact encouraged by Microsoft) to use Windows API functions to create and use localized .INI files to hold persistent configuration and other state information. In the Win32 world this practice is changing, as we are supposed to save all such information now in the Windows registry. I’ll not go into the debate over the propriety or wisdom of relying on the registry, but it’s worthwhile to understand something about the registry and how to access it with Win32 API functions.
Ideally, all configuration information for the system should reside in the registry. In fact, if you want your program to qualify for the “Compatible with Windows 9x” logo, it must be registry-oriented.
Microsoft itself has moved almost everything to the Registry. Even the venerable configuration files CONFIG.SYS and AUTOEXEC.BAT are utterly unnecessary in Win9x, though their use is supported for backward compatibility and for those applications and devices that still rely on 16-bit drivers and such.
So what kind of information would a VdB developer want to store in the Registry, anyway? Any settings that must remain persistent across instances of the application, maintained even when the machine is powered down. User preferences, serial number information, process statuses, etc. are all possibilities. I like my MDI applications to “remember” the sizes and locations of MDI child windows between invocations, so I sometimes store this information. You can think of the Registry as similar to a database table in that respect; a long-term storage area for whatever kind of information you wish to track. But it’s not a database table, so it’s important to keep the volume of information in mind. Large registries cause large problems when they get corrupted. So if you need hundreds of settings or other large amounts of information stored, it might be best to save those things in a .DBF or .MEM file and then store in the registry the path and filename of that file.
A well-behaved Win9X application is supposed to save a bit of information about itself in the Registry. The InstallShield Express installer that comes with Visual dBASE handles this for us, and even allows the option of building the registry keys necessary for uninstalling the application. So much of this burden is off our shoulders from the start. Even so, it’s good for any developer to have at least a passing familiarity with the registry’s structure and use.
The tool most often used to access the registry is RegEdit, normally located in your Windows home directory. If you’ve never used RegEdit, and you’re sitting at a Win9X PC as you read this, start the program now and navigate around a bit with the mouse to get a feel for the layout of the data contained in the registry.
The above illustration is a screenshot of RegEdit on the machine I’m on now, which is running Win98. RegEdit looks the same in Win95 and Win98, and everything I say here applies to both as far as I can tell!
Each key (displayed on the left side of the display) is a container for other registry information, be it in the form of other keys or actual data. The value entries for a given key are displayed in the right window pane when the key is selected on the left. If you’ve poked around much you probably have noticed that the hierarchy of keys can get quite deep. There’s no way we could go into exhaustive detail on any one of them, let alone all of them, so let’s discuss the 6 major keys and their use.
HKEY_CLASSES_ROOT is full of Object Linking and Embedding (OLE)-related information. You’ll find scores of file extensions, shell extension information used by Explorer, etc. Leave it alone if you don’t know what you’re doing!
HKEY_CURRENT_USER contains the user profile of the currently active user. As you probably know, Win9x supports multiple user profiles on a single machine, so remember that information under this key does not necessarily affect everyone who uses the machine. Program groups, printers, network connections, desktop settings, and other such things are stored here. Well-behaved applications will often store their user preferences here, so that different users can have different preferences, even on the same machine.
HKEY_LOCAL_MACHINE contains information about the PC you’re running on. Device driver, startup, and other system-wide data are stored here. Don’t mess with this!
HKEY_USERS contains all the currently loaded user profiles (including the one detailed in HKEY_CURRENT_USER). In fact, HKEY_CURRENT_USER is technically a subkey of this key. HKEY_USERS is the key under which the machine’s default user preferences are stored. Note that if you’re looking at the registry on a server (Win9x or WinNT), this key does not normally affect logged-in users; their profiles are in the registries on their local PCs.
HKEY_CURRENT_CONFIG is key designed specifically for Win9x, though you might find it on a WinNT machine as well. It is predefined under Win9x, though, so they’ll always have it. HKEY_CURRENT_CONFIG is actually mapped to a branch under HKEY_LOCAL_MACHINE, but is also available at the higher level for ease of access. This is they key where you want to store your application’s non-user-specific configuration settings and information, e.g. server or backend database name(s).
There are a few specific subkeys you and/or your applications should know about and possible even create or modify. The “application information key” is
[HKEY_LOCAL_MACHINE]\Software\Company\Product\Version
InstallShield Express builds this key for us if we use it for the application’s installer, but it doesn’t fill in too much data by default. Here’s a screen shot of our company’s TimeClock application’s entries in my registry:
As you can see, I didn’t add of change anything under InstallShield’s “Make Registry Changes” section for this project. Fortunately ISE is smart enough to insert the keys for the company name, program name, and version number for me. These are taken from the primary setup screen when you start the process to deploy the application, as you can see:
The values returned for the “Company” and “Name” items are supplied by the machine and/or user when the application is installed.
Now, how can my applications get at this data? There are a number of API functions involved in accessing the registry, and they can be a bit intimidating. Once again there is sample code we can use in our own apps to get the functionality quickly without having to learn all the ins and outs of the registry functions.
In your SAMPLES directory is a file called REGISTRY.PRG. This program contains a custom class we can use to get at registry data easily. Here’s a simple program that uses the class to read the information in the keys we just looked at from my Time Clock application:
// REGDEMO.PRG: Demonstrate REGISTRY.PRG usage
#include <windef.h>
#include <winreg.h>
set procedure to _dbwinhome+"\samples\registry" additive
Reg = new Registry(HKEY_LOCAL_MACHINE,;
"SOFTWARE\First Intermark Corp.\FU$$ Time Clock\1.0")
? Reg.QueryValue("Company") // Prints "First Intermark Corp."
? Reg.QueryValue("Name") // Prints "Keith Chuvala"
Reg.close()
Basically, you create a Registry object initialized with the upper level key (in this case HKEY_LOCAL_MACHINE, which is #define’d in WinREG.h) as the first argument, and the subkey as the second arguments. Then you use the various methods of the class to add, set, delete, or query values under the specified key.
Other methods in this class include DeleteKey, DeleteValue, EnumValue (this one returns an array with the names of each value in the current key!), QueryKeyName, and SetValue. Take some time to play with this useful class!
Some Useful API Functions
Every window has a so-called “handle” which is a unique integer number identifying that particular window. We can’t set this value; Windows does this for us when we create a new form. In Visual dBASE we see this value as the form’s HWND property. Many API functions require that this handle be passed as an argument to the function. If the window in question was created with Visual dBASE, simply passing the HWND property is all that is required. If your program needs to interact with other active windows active at the time, you can use API functions to help you get their handle. Here we’ll look at a few useful functions that demonstrate how to ascertain a “foreign” HWND, and how to use it.
/* FindWin.PRG: Find a top-level window by its title text
Useful for detecting when an app is already running.
Does NOT search child windows
*/
Procedure FindWin
parameter cTitleText
if type("cTitleText") # "C"
return 0
endif
if type("FindWindow") # "FP"
extern cHandle FindWindow(CSTRING, CSTRING) User32 ;
from "FindWindowA"
endif
return FindWindow(0, cTitleText)
// ShowWin.PRG: Set the display state of a running Window
Procedure ShowWin
parameter nHWND, nHow
/* Values for nHow:
0 - Hide completely from view
1 – Normal window
2 - Minimize
3 - Maximize
*/
if type("nHWND") # "N"
return
else
if nHWND == 0
return
endif
endif
if type("nHow") # "N"
nHow = 1 // default to normal
endif
if type("ShowWindow") # "FP"
extern cHandle ShowWindow(cHandle, cInt) User32
endif
ShowWindow(nHWND, nHow)
return
You can use FindWin() and ShowWin() together to prevent multiple instances of your application from running simultaneously. Just search for the title text of your app’s primary window, and if found, bow out gracefully. Try something like this in your startup code:
/* RunOnce.PRG: Demonstrate use of FindWin and ShowWin to ensure that
only one instance of an app runs at any given time
*/
set procedure to findwin additive
set procedure to showwin additive
nHWND = findwin("My App")
if nHWND # 0
showwin(nHWND,1) // it's already out there, so show it!
return // For a compiled app this would be QUIT
endif
define form f property text "My App", mdi .f., left 0, top 0
f.open()
The next function, LockWin, was originally posted to the Borland newsgroups by either Romain Streiff or Jim Sare; I need to find out which and credit the right gentleman! It’s a great little function that tells Windows to NOT update a particular window’s display; it blocks repainting of the form. This can be used to prevent form “flicker” that so often happens when constructing a busy form, or when form elements are updated in an annoying fashion during looping operations and such. In my own incarnation of the function, I pass it two arguments, the first a logical value to indicate whether we’re locking or “unlocking”, and the HWND of the form to lock. If no HWND is passed, it is assumed the whole desktop window should be locked.
/* LockWin.PRG: Prevents the updating of a window.
Useful for avoiding “flicker” during some operations.
*/
Procedure LockWin
parameter lLock, nHandle
local nHWND
if type("nHandle") # "N" // default to desktop if omitted
nHWND = 0
if type("GetDesktopWindow") # "FP"
extern CHANDLE GetDesktopWindow (CVOID) USER32
endif
nHWND = GetDeskTopWindow()
endif
if type("lLock") # "L" // default to locking it if omitted
lLock = .t.
endif
nHWND = iif(lLock, nHandle, 0) // set to 0 to unlock
if type("LockWindowUpdate") # "FP"
extern CLOGICAL LockWindowUpdate(CHANDLE) User32
endif
LockWindowUpdate(nHWND)
return
One of the features of Win9x that I’ve come to appreciate is the ubiquitous filename extension recognition the registry provides, allowing us to operate in a more document-centric, rather than application-centric, fashion. As you undoubtedly know, if you double click on, say, a .BMP file in the Windows Explorer, the application associated with that file type is automatically launched, and the image you selected is opened up for display, editing, etc.
At the DOS level you can get the same behavior using the START command. START WINLOGO.BMP will accomplish the same effect as double-clicking on WINLOGO.BMP. This document-centric view of the world means that I don’t worry so much about what applications are out there, so much as what document(s) I want to work with.
Calling external editors or other programs from within Visual dBASE 5.x apps under Windows 3.x required ascertaining either the actual path to the application desired, or figuring out OLE hooks to accomplish the same. In Win9x a simple START will do the trick. But running the DOS START command results in an ugly (if temporary) DOS window on the screen. A better option is to do what Windows Explorer does; run the ShellExecute API function.
ShellExecute can open executable files or document files, can print document files, and can even be used to invoke explorer windows on a specified folder. As you might imagine, ShellExecute takes several arguments to handle those varied functions. At this point it’s useful to rely on the docs, which in this case is the Microsoft Win32 help file. Here’s the prototype for ShellExecute and a few of the notes that go along with it:
HINSTANCE ShellExecute(
HWND hwnd, // handle to parent window
LPCTSTR lpOperation, // pointer to string that specifies operation to perform
LPCTSTR lpFile, // pointer to filename or folder name string
LPCTSTR lpParameters, // pointer to string that specifies executable-file parameters
LPCTSTR lpDirectory, // pointer to string that specifies default directory
INT nShowCmd // whether file is shown when opened
);
Parameters
Hwnd Specifies a parent window. This window receives any message boxes that an application produces. For example, an application may report an error by producing a message box.
LpOperation Pointer to a null-terminated string that specifies the operation to perform. The following operation strings are valid:
String Meaning
"open" The function opens the file specified by lpFile. The file can be an executable file or a document file. The file can be a folder to open.
"print" The function prints the file specified by lpFile. The file should be a document file. If the file is an executable file, the function opens the file, as if "open" had been specified.
"explore" The function explores the folder specified by lpFile.
The lpOperation parameter can be NULL. In that case, the function opens the file specified by lpFile.
LpFile Pointer to a null-terminated string that specifies the file to open or print or the folder to open or explore. The function can open an executable file or a document file. The function can print a document file.
LpParameters If lpFile specifies an executable file, lpParameters is a pointer to a null-terminated string that specifies parameters to be passed to the application.
If lpFile specifies a document file, lpParameters should be NULL.
LpDirectory Pointer to a null-terminated string that specifies the default directory.
NShowCmd If lpFile specifies an executable file, nShowCmd specifies how the application is to be shown when it is opened.
You can see why having a good API reference is essential for success in working with API functions. The Win32.HLP file has loads of information, but no examples. There are numerous books available that detail the workings of many of the API functions and offer examples to follow.
/* WinSTART.PRG: uses the ShellExecute API call
to execute a Windows "start" without dropping to DOS
*/
function WinStart
parameter cCommand
if type("cCommand") # "C"
return
endif
if type("ShellExecute") # "FP"
extern cHandle ShellExecute(cHandle,cstring,cstring,cstring,cstring,CINT) ;
shell32 from "ShellExecuteA"
endif
return ShellExecute(0,"open",cCommand,null,null,1)
WinSTART assumes you’re going to “open” the document, as you can see. This afford you tremendous flexibility. Here are some examples of code I use this function for:
WinSTART(_dbwinhome + ”readme.txt”) // Read the VdB README (launches Notepad)
WinSTART(“http://www.fusslocal.com”)// Launch default browser, go to specified URL
WinSTART(mailto:kgc@hit.net) // Launch default mail program, start message to me!
WinSTART(“c:\program files”) // Launch Explorer, opened to “C:\Program Files”
Working with Messages
Many Windows objects can be manipulated or otherwise communicated with by sending (or “posting”) messages to them. We’ll not dive into all the details here, but essentially Windows is a huge message processing engine. Most everything we do in Windows involves the passing of messages from one element to another. If you have a utility like Borland’s WinSight, you can see these messages. We’ll do this in the tutorial.
As you will see, this message passing happens all the time, and largely without our knowledge or awareness of it. There are situations where we need to manipulate and/or send messages manually to get the behavior we want from our applications.
Visual dBASE’s support for the “Windows” menu in the menu designer is a good example. The Windows menu automatically maintains a list of currently open MDI child windows. Most MDI applications also add the ability to cascade or tile all open windows to clean up the display. Bu the native dBASE Window menu lacks these commands. We can add them on our own by adding code to the menu to send the appropriate message to the MDI parent shell.
The API function we need is SendMessage. Here is its prototype from the SDK Help file:
LRESULT SendMessage(
HWND hWnd, // handle of destination window
UINT Msg, // message to send
WPARAM wParam, // first message parameter
LPARAM lParam // second message parameter
);
Parameters
HWnd Identifies the window whose window procedure will receive the message. If this parameter is HWND_BROADCAST, the message is sent to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent to child windows.
Msg Specifies the message to be sent.
WParam Specifies additional message-specific information.
LParam Specifies additional message-specific information.
For the most part we concern ourselves with the first two arguments, the HWND of the window we’re passing a message to, and the Msg parameter itself. There are hundreds of different messages; this parameter is just an integer value that represents a given message. You’ll find many of these messages with somewhat mnemonic #defines in Visual dBASE’s header files, particularly WinUSER.h.
The two messages we’re interested in for this example are WM_MDICASCADE and WM_MDITILE, which tell an MDI parent Window to arrange its children accordingly. Here, then, is a simple form with a menu that contains this functionality:
// WinMenu.WFM: demonstrate Cascade and Tile via SendMessage() API call
shell(.f.)
** END HEADER -- do not remove this line
//
// Generated on 05/04/98
//
parameter bModal
local f
f = new testForm()
if (bModal)
f.mdi = false // ensure not MDI
f.readModal()
else
f.open()
endif
class testForm of FORM
with (this)
height = 10
left = 20
top = 5
width = 40
text = "First Form"
menuFile = "winmenu.mnu"
endwith
endclass
Okay, nothing exciting there, of course. The message passing is done my the menu itself. Examine the code that follows. It’s not required that the menu contain the code; you certainly could hook the same logic into the form, and in fact, it might make good sense to pack things like this inside a custom form class for ease of later reuse.
Notice how we use the OnInitMenu event handler to EXTERN the
API functions we need. Then the menu selections for Cascade and Tile execute
the SendMessage API function, in each case sending the message to the MDI
parent, but with different message identifiers according to the behavior each
requires.
