Article ID: 83456 - View products that this article applies to.
This article was previously published under Q83456
The WINDOWS.H and WINDOWSX.H header files in version 3.1 of the Microsoft Windows Software Development Kit (SDK) provide new features to make developing applications for the Windows environment faster and easier. These features enable the C compiler to find many common programming errors at compile time.
This article provides an overview and examples of the new features, as well as a road map to other resources in the SDK that explain them.
The WINDOWS.H and WINDOWSX.H header files provide the following features:
The SDK also provides the following resources:
Using the macros, control macros, and message crackers assists in the process of finding errors and increases code portability; however, using these features is a matter of taste. Some developers like them and find them useful, others do not.
The simplest way to become familiar with the new features is to review the WINDOWS.H and WINDOWSX.H header files, the associated WINDOWS.TXT and WINDOWSX.TXT text files, and the MAKEAPP sample application. Each of the new features is implemented in one of the header files (usually as a fairly simple macro) and is explained in one of the text files.
Each of the new features is designed to address three goals:
Each of the new features is compatible with Windows 3.0. You can use the new features in an application that will run under version 3.0 and you can modify existing code to use the new features.
The remainder of this article provides an introduction to each of the new features.
New Data Types, Type Definitions, and Helper MacrosThe new data types are implemented in WINDOWS.H and described in WINDOWS.TXT. Examples of new data types are WPARAM, LPARAM, and UINT. Examples of new handle types are HINSTANCE, HMODULE, and HTASK. Using the new data types can make source code easier to read and simplify porting to 32-bit Windows.
STRICT Preprocessor VariableThe STRICT preprocessor variable is implemented in WINDOWS.H and described in WINDOWSX.TXT. When an application defines STRICT, the C compiler enforces the highest possible level of type checking, which enables the compiler to find as many errors as possible. It is much more productive to find errors at compile time than to find them later using a debugger.
While an application can use the new data types described above without defining STRICT, it must use the new types if STRICT is defined.
To enable STRICT type checking, an application must define the STRICT environment variable before including WINDOWS.H, as follows:
The STRICT environment variable and the new data types are compatible with Windows 3.0, C++, the Microsoft C Compiler's highest warning level (specified by the -W4 option switch), and ANSI C.
An Example of Using STRICTThe ReleaseDC function is prototyped as follows:
In an application, a programmer might mistakenly switch the two parameters to the ReleaseDC function, as follows:
Traditionally, the compiler will not catch this error because both the HDC and HWND data types are defined to be UINT variables. However, if STRICT is enabled, the HDC and HWND data types are defined as completely different types, which enables the compiler to catch the error at compile time. (For more information about how the HWND and HDC data types are defined, see the DECLARE_HANDLE macro in WINDOWS.H.)
The WINDOWS.TXT file contains step-by-step instructions for writing STRICT-compliant Windows code. WINDOWS.TXT also lists the most common compiler errors generated while compiling an application with STRICT defined, and methods to address these errors.
Converting Existing Code to STRICTWINDOWS.TXT describes how to convert existing Windows code to be compatible with STRICT. However, this conversion requires a fair amount of effort. If the existing code is stable and not modified very often, the effort to convert the code may not be worthwhile.
MacrosThe macros are implemented in WINDOWSX.H. Each one is listed and described in WINDOWSX.TXT.
The macros can be used to simplify many common Windows programming operations. Macros are designed to make code easier to read and write. They can eliminate much typing and prevent type casting errors. The macros are compatible with 32-bit Windows.
As an example, the traditional method to subclass a window involves code such as the following:
The following code, which uses a new macro, accomplishes the same task:
Other macros include: GlobalAllocPtr, DeletePen, SelectBitmap, and GetWindowID.
Control Message MacrosThe control message macros are implemented in WINDOWSX.H. Each one is listed and described in WINDOWSX.TXT.
The control message macros simplify dealing with Windows controls (edit controls, list boxes, and so forth). Using the control message macros makes code smaller, potentially more readable, and handles all type casting required. When used in conjunction with the STRICT preprocessor variable, the control message functions prevent type errors and incorrect parameter passing.
Examples of control message macros are: Static_Enable, Button_GetCheck, Edit_GetLineCount, and ScrollBar_SetRange.
Each control message macro corresponds to an existing control message or window manager function. For example, Button_GetCheck can be used in place of the BM_GETCHECK message and Button_SetText can be used in place of SetWindowText.
A Control Message Macro ExampleThe following example illustrates the power of the control message macros.
The following code uses traditional SendMessage calls to retrieve all the lines of text from an edit control:
The following code uses control message macros to perform the same task, retrieving all the lines of text from an edit control:
Message CrackersThe message crackers are implemented in WINDOWSX.H. The message crackers are described in WINDOWSX.TXT, which also explains in some detail how to use them. WINDOWSX.TXT does not list all message crackers; the list is available in WINDOWSX.H.
The two biggest advantages to using message crackers are:
Using message crackers radically alters the appearance of a window procedure (see the example below). Whether or not this change of appearance is a desirable side effect depends on the coding tastes of the application developer.
Typically, a window procedure will handle many messages, with code in the procedure to process each message. This often leads to the source code for a window procedure continuing on for many pages. When an application uses message crackers, almost any window procedure can be listed very concisely. The bulk of the code is transferred to message- handling functions that the message crackers call.
A Simple Message Cracker ExampleThe following code sample demonstrates using the HANDLE_WM_* message crackers in a window procedure:
The application must also contain the following message-handling functions that are called by the message crackers:
While the window procedure code given above is compact, the HANDLE_MSG macro simplifies the code even further. For example:
Message Cracker BasicsIf a window procedure uses a message cracker to process a particular message, it must also implement a function to process that message. This function must have a specific "signature" (the order and types of parameters and the function's return type). The correct signature for each function is listed in WINDOWSX.H next to the corresponding message cracker.
For example, if the window procedure in the example above uses the HANDLE_WM_MOUSEMOVE message cracker, it must also implement the Template_OnMouseMove function, which the message cracker calls.
Once the application implements Template_OnMouseMove, the message cracker processes the message as follows:
Message Crackers Have Many UsesThe WINDOWSX.TXT text file explains and illustrates how to use message crackers in many different application programming situations, including the following:
Article ID: 83456 - Last Review: November 6, 1999 - Revision: 1.0