WIN31.DOC file accompanying version 3.1 of Borland

Written by Embarcadero USA on Posted in PROGRAMMING

 Technical Notes Database

TN2542C.txt   WIN31.DOC file accompanying version 3.1 of Borland
Category   :OTHER
Platform    :All
Product    :BCW  3.x


Changes to windows.h from 3.0 to           Message cracker examples  . . 26
3.1  . . . . . . . . . . . . . . . 1       Message handler function
Catching coding errors at                  signatures  . . . . . . . . . 28
compile-time: STRICT . . . . . . . 1       Improving reusability:
  Why STRICT?  . . . . . . . . . . 2       Template_DefProc  . . . . . . 28
  Compiling 3.0 applications . . . 3       Private and registered window
  New typedefs, constants, and             messages  . . . . . . . . . . 29
  helper macros  . . . . . . . . . 4       Message crackers and window
    COMSTAT structure change . . . 5       instance data . . . . . . . . 30
  Making your code STRICT                  Message crackers and dialog
  compliant  . . . . . . . . . . . 6       procedures  . . . . . . . . . 33
  STRICT conversion hints  . . .  10       Message crackers and window
  Common compiler warnings and             subclassing . . . . . . . . . 34
  errors . . . . . . . . . . . .  11       Dialog procedures: A better
Macro APIs and message crackers . 14       way . . . . . . . . . . . . . 36
  Macro APIs . . . . . . . . . .  15         Executing default dialog
      3.1-only macro APIs  . . .  18         procedure functionality . . 37
  Control message APIs . . . . .  18         Returning message results from
    Control API Examples . . . .  18         dialog procedures . . . . . 37
  Message cracker macros . . . .  22         How it works  . . . . . . . 37
    Using message crackers and               A simplified example using
    forwarders . . . . . . . . .  23         predefined macro APIs . . . 39
    Saving time and improving              Converting existing code to use
    readability with HANDLE_MSG . 24       message crackers  . . . . . . 41
    How message crackers work  .  25
1: New handle types  . . . . . . . 5
Changes to windows.h from 3.0 to 3.1
                    The windows.h header file included with Borland C++ 3.1
                    contains various features that make application
                    development faster and easier by helping you find
                    problems as you compile your code. These improvements
                    o STRICT option provides stricter type checking,
                      helping you find type mismatch errors quickly.
                    o windows.h has been completely reorganized so that
                      related functions, types, structures, and constants
                      are grouped together.
                    o New UINT type used for 32-bit Windows upward
                    o New unique typedefs for all handle types, such as
                      HINSTANCE and HMODULE.
                    o Various constants and typedefs missing in the 3.0
                      windows.h have been added.
                    o Windows 3.0 compatibility: windows.h can be used to
                      compile applications that run under Windows 3.0.
                    o Proper use of "const" for API pointer parameters and
                      structure fields where pointer is read-only.
                    If you have ObjectWindows, also see OWL31.DOC in your
                    OWL\DOC directory for details about how these changes
                    affect ObjectWindows and your ObjectWindows
Catching coding errors at compile-time: STRICT
                    The new windows.h supports an option called STRICT that
                    enables the strictest possible compiler error checking.
                    Strict compile-time checking helps you find programming
                    errors when you compile your application, rather than
                    at runtime.
                    The idea is that you define STRICT before including
                    windows.h, which causes the various types and function
                    prototypes in windows.h to be declared in a way that
                    enforces very strict type checking. For example,
                    without STRICT, it is possible to pass an HWND to a
                    function that requires an HDC without any kind of
                    compiler warning: with STRICT defined, this results in
                    a compiler error.
                    Specific features provided by the STRICT option
                    o Strict handle type checking (you can't pass an HWND
                      where an HDC is declared).
                    o Correct and more consistent declaration of certain
                      parameter and return value types (for example,
                      GlobalLock returns void FAR* instead of LPSTR).
                    o Fully prototyped typedefs for all callback function
                      types (for example, dialog procedures, hook
                      procedures, and window procedures)
                    o Windows 3.0 backward compatible: STRICT can be used
                      with the 3.1 windows.h for creating applications that
                      will run under Windows 3.0.
                    o The COMM DCB and COMSTAT structures are now declared
                      in an ANSI compatible way.
       Why STRICT?  =======================================================
                    The best way to think of STRICT is as a way for you to
                    get the most out of the error checking capabilities
                    built into Borland C++. STRICT is of great benefit
                    especially with code under development, because it
                    helps you catch bugs right away when you compile your
                    code, rather than having to track it down at runtime
                    with a debugger. By catching certain kinds of bugs
                    right away, it's less likely that you'll ship your
                    applications with bugs that weren't encountered in
                    STRICT also makes it easier to migrate your code to the
                    32-bit Windows platform later, because it will help you
                    locate and deal with type incompatibilities that will
                    arise when migrating to 32 bits.
                                   - 2 -
                    It's not very difficult to convert your application to
                    use STRICT, and it can be done in stages if needed.
                    In order to take advantage of the STRICT option, you
                    will probably have to make some simple changes to your
                    source code (described in detail later).
                    We think you'll find that STRICT makes modifying,
                    maintaining, and even reading your code much easier,
                    and well worth the effort to convert your application.
     Compiling 3.0  =======================================================
                    Unless you define STRICT, your 3.0 applications will
                    compile with windows.h without serious modifications.
                    The type declarations for many of the Windows APIs and
                    callback functions have changed; those changes are
                    backward compatible for C code, but not for C++ code.
                    If you use C++, you'll notice compile- and link-time
                    errors in many Windows API functions because of changes
                    to types like WORD to UINT. See the following sections
                    for more information.
                    All of the features of Borland C++ 3.1 can be used to
                    develop applications that will run under Windows 3.0.
                    There are two things you must do:
                    1. Define WINVER to 0x0300 before including windows.h
                       This ensures that only 3.0 compatible functions,
                       structures, and definitions are available for use.
                       You can do this in your makefile with
                       -DWINVER=0x0300 in the compiler command line, in the
                       IDE in the Options|Compiler|Code Generation|Defines
                       input box, or in your code by adding "#define WINVER
                       0x0300" before you include windows.h.
                    2. Use the -30 parameter to BRC or RC.
                       This marks your executable as a 3.0 application, so
                       that Windows 3.0 won't prevent it from running with
                       a "This application requires a later version of
                       Windows" message. You will typically run RC twice in
                       your makefile: Once to produce the .res file (with
                       the -r switch), and a second time to combine your
                       linked .exe and .res files into the final
                       application. The -30 parameter must be used with the
                                   - 3 -
                       second invocation of RC. See Chapter 4 in the
                       Borland C++ User's Guide for instructions on how to
                       add the -30 parameter to your IDE projects.
     New typedefs,  =======================================================
    constants, and
     helper macros  The following typedefs and constants have been added to
                    windows.h. All are 3.0 compatible:
            WINAPI  Used in place of FAR PASCAL in API declarations. If you
                    are writing a DLL with exported API entry points, you
                    can use this for your own APIs.
          CALLBACK  Used in place of FAR PASCAL in application callback
                    routines such as window procedures and dialog
            LPCSTR  Same as LPSTR, except used for read-only string
                    pointers. Typedefed as const char FAR*.
              UINT  Portable unsigned integer type whose size is determined
                    by host environment (16 bits for Win 3.1). Synonym for
                    "unsigned int". Used in place of WORD except in the
                    rare cases where a 16-bit unsigned quantity is desired
                    even on 32-bit platforms.
           LRESULT  Type used for declaration of all 32-bit polymorphic
                    return values.
            LPARAM  Type used for declaration of all 32-bit polymorphic
            WPARAM  Type used for declaration of all 16-bit polymorphic
   MAKELPARAM(low,  Macro used for combining two 16-bit quantities into an
             high)  LPARAM.
  MAKELRESULT(low,  Macro used for combining two 16-bit quantities into an
             high)  LRESULT.
  MAKELP(sel, off)  Macro used for combining a selector and an offset into
                    a FAR VOID* pointer.
    SELECTOROF(lp)  Macro used to extract the selector part of a far ptr.
                    Returns a UINT.
                                   - 4 -
      OFFSETOF(lp)  Macro used to extract the offset part of a far ptr.
                    Returns a UINT.
 FIELDOFFSET(type,  Macro used for calculating the offset of a field in a
            field)  data structure. The type parameter is the type of
                    structure, and field is the name of the field whose
                    offset is desired.
New handle types      Typedef           Meaning
                      HINSTANCE         Instance handle type
                      HMODULE           Module handle type
                      HLOCAL            Local handle type
                      HGLOBAL           Global handle type
                      HTASK             Task handle type
                      HFILE             File handle type
                      HRSRC             Resource handle type
                      HGDIOBJ           Generic GDI object handle type
                                        (except HMETAFILE)
                      HMETAFILE         Metafile handle type
                      HDWP              DeferWindowPos handle
                      HACCEL            Accelerator table handle
          3.1 only    HDRVR             Driver handle
------------------  The 3.0 declaration of the COMSTAT structure was not
 COMSTAT structure  ANSI compatible: ANSI does not allow the use of
            change  BYTE-sized bitfield declarations. To allow windows.h to
------------------  be used with full ANSI compliance, the COMSTAT
                    structure has changed. The 7 bit fields below are now
                    accessed as byte flags of the single status field:
                      Old field name    Bit of status field
                      fCtsHold          CSTF_CTSHOLD
                      fDsrHold          CSTF_DSRHOLD
                      fRlsdHold         CSTF_RLSDHOLD
                      fXoffHold         CSTF_XOFFHOLD
                      fXoffSent         CSTF_XOFFSENT
                                   - 5 -
                      fEof              CSTF_EOF
                      fTxim             CSTF_TXIM
                    No change is required if you are compiling with WINVER
                    set to 0x0300 and are not using STRICT.
                    If you have code that accesses any of these fields,
                    here's how you have to change your code:
Old code                      New code
if (comstat.fEof || ...)      if ((comstat.status & CSTF_EOF) || ...)
comstat.fCtsHold = TRUE;      comstat.status |= CSTF_CTSHOLD;
comstat.fTxim = FALSE;        comstat.status ~= CSTF_TXIM;
                    Be careful to properly parenthesize "&" expressions.
                    See windows.h for more details.
  Making your code  =======================================================
  STRICT compliant
                    Using STRICT with your existing Windows application
                    code is not very difficult. Here's what you need to do:
                    o Decide what you want be STRICT compliant.
                      The first step is to decide what you want to be
                      STRICT compliant.
                      STRICT is most valuable with newly developed code or
                      code that you're maintaining or changing regularly.
                      If you have a lot of stable code that has already
                      been written and tested, and is not changed or
                      maintained very often, you may decide that it's not
                      worth the trouble to convert to STRICT.
                      If you are writing a C++ application, you don't have
                      the option of applying STRICT to only some of your
                      source files. Because of the way C++ "type safe
                      linking" works, you may get linking errors if you mix
                      and match STRICT and non-STRICT source files in your
                    o Enable strict compiler error checking
                                   - 6 -
                      First, turn on all Borland C++'s warning and error
                      messages. In the IDEs, you can use Options|Compiler|
                      Messages|Display|All; for the command-line compiler,
                      use the -w switch. Do this without turning on STRICT
                      for now.
                      In you're writing applications in C, you might want
                      to compile them as C++ to take advantage of C++'s
                      stricter type checking and type-safe linking. You can
                      do this by renaming .C files to .CPP or by using the
                      IDEs' Options|Compiler|C++ Options|C++ Always option
                      or the command-line compiler's -p switch.
                    o Change your code to use new STRICT types
                      First you need to go through your own source and
                      header files and change type declarations to use the
                      new types defined in windows.h. Below are the common
                      types that should be changed:
                        Old type          New type(s)
                        HANDLE            HINSTANCE, HMODULE, HGLOBAL,
                                          HLOCAL, etc. as appropriate
                        WORD              UINT (EXCEPT where you really
                                          want a 16-bit value even on a
                                          32-bit platform) or WPARAM
                        LONG              LPARAM or LRESULT as appropriate
                        FARPROC           WNDPROC, DLGPROC, HOOKPROC, etc.
                                          as appropriate (MakeProcInstance
                                          and FreeProcInstance calls
                                          require casting)
                      See "Strict Conversion Notes" below for particular
                      things to watch out for when changing your code.
                      The UINT type is important for 32-bit Windows
                      migration. On 16-bit windows, WORD and UINT are
                      identical: 16 bit unsigned quantities. On a 32-bit
                      platform, a UINT will be 32 bits and WORD is 16 bits.
                                   - 7 -
                      This allows much more efficient code to be generated
                      on the 32-bit platform where UINTs are used. You
                      should use WORD in your code ONLY in those places
                      where you want a 16 bit value, even on a 32-bit
                      Because C++ mangles function names, any callback
   C++ users note!    function whose arguments have changed between Windows
                      3.0 and 3.1 (from WORD to UINT, for example) will
                      generate link-time errors. You must either change the
                      argument types or replace the 3.1 version of
                      windows.h with the 3.0 version (in win30.h). It's
                      highly recommended that you change the parameter
                      You may also want to use CALLBACK instead of FAR
                      PASCAL in the declaration of your various callback
                      functions, though this isn't necessary.
                      You may be able to save yourself some work by not
                      converting the body of your window and dialog
                      procedures to use WPARAM, LPARAM, and LRESULT right
                      away, since those types are compatible with WORD and
                      LONG, even in STRICT.
                    o Make sure your functions are declared before use
                      To compile as C++ or with all warnings enabled, all
                      of your application functions must be properly
                      declared before they are used. It's best to have all
                      your declarations in an include file, rather than
                      declaring them in your source files as needed: it's
                      much easier to maintain your code this way should you
                      need to change any of the declarations in the future.
                      Chances are you will need to be making changes to the
                      function declarations as you change over to the new
                      STRICT data types.
                      While it's not strictly necessary to do so, it's a
                      good idea to provide function parameter names in your
                      function prototypes. This makes header files much
                      easier to read, and provides a degree of
                    o Recompile without STRICT and fix resulting warnings
                      Without defining STRICT anywhere, recompile your
                      application and fix any warnings that result. You can
                                   - 8 -
                      use the Borland C++ IDE's Search|Next Error (Alt+F7)
                      command to speed up those fixes.
                      Some common compiler warnings--and how you should
                      deal with them--are described later in this section.
                      Use the rules found there to make the appropriate
                      changes to your source.
                    o Run the app to make sure all is well.
                      After you've gotten your application to compile
                      cleanly as C++ or with all warnings enabled, it's a
                      good idea to run your app and put it through it's
                      paces to make sure all is well.
                    o Define STRICT
                      After you've made a first pass and gotten things to
                      compile cleanly without STRICT, it's time to turn it
                      on and make the next round of changes.
                      If you've decided that you want to make your entire
                      app STRICT, then the best and easiest thing to do is
                      define STRICT in your makefile, by passing the
                      -DSTRICT flag to the compiler or to use the Options|
                      Compiler|Code Generation|Defines input box. If you
                      want to do it on a per-source file basis, then simply
                      define STRICT in the source file before you include
                    o Recompile and clean up resulting errors
                      Once you've made the changes to your window and
                      dialog procedures as outlined above, you're ready to
                      recompile everything.
                      After turning on STRICT you'll probably get new
                      errors and warnings that you'll need to go through
                      and clean up.
                      You might also get link-time errors because of
   C++ users note!    mismatched function parameter types. Check your
                      function prototypes and definitions carefully.
                      The list of warnings and errors below will explain
                      how to deal with most of the problems that arise.
                                   - 9 -
 STRICT conversion  =======================================================
                    1. Always declare function pointers with the proper
                       function type, rather than FARPROC. You'll need to
                       cast function pointers to and from the proper
                       function type when using MakeProcInstance,
                       FreeProcInstance, and other functions that take or
                       return a FARPROC:
                        BOOL CALLBACK DlgProc(HWND hwnd, UINT msg,
                                              WPARAM wParam,
                                              LPARAM lParam);
                        DLGPROC lpfnDlg;
                        lpfnDlg=(DLGPROC)MakeProcInstance(DlgProc, hinst);
                    2. Take special care with HMODULEs and HINSTANCEs. For
                       the most part, the Kernel module management
                       functions use HINSTANCEs, but there are a few APIs
                       that return or accept only HMODULEs.
       WinMain and  3. If you've copied any API function declarations from
   LibMain are two     windows.h, they may have changed, and your local
  common examples.     declaration may be out of date. Remove your local
                    4. Properly cast the results of LocalLock and
                       GlobalLock to the proper kind of data pointer.
                       Parameters to these and other memory management
                       functions should be cast to LHANDLE or GHANDLE, as
                    5. Properly cast the result of GetWindowWord and
                       GetWindowLong and the parameters to SetWindowWord
                       and SetWindowLong.
                    6. When casting SendMessage, DefWindowProc, and
                       SendDlgItemMsg or any other function that returns an
                       LRESULT or LONG to a handle of some kind, you must
                       first cast the result to a UINT:
                        HBRUSH hbr;
                        hbr = (HBRUSH)(UINT)SendMessage(hwnd, WM_CTLCOLOR,
                                  - 10 -
                                                        ..., ...);
                    7. The CreateWindow and CreateWindowEx hmenu parameter
                       is sometimes used to pass an integer control ID. In
                       this case you must cast this to an HMENU:
                        HWND hwnd;
                        int id;
                        hwnd = CreateWindow("Button", "Ok", BS_PUSHBUTTON,
                                            x, y, cx, cy, hwndParent,
                                            (HMENU)id, //Cast required here
                                            hinst, NULL);
                    8. Polymorphic data types (WPARAM, LPARAM, LRESULT,
                       void FAR *) should be assigned to variables of a
                       known type as soon as possible. You should avoid
                       using them in your own code when the type of the
                       value is known. This will minimize the number of
                       potentially unsafe and non-32-bit-portable casting
                       you will have to do in your code. The macro APIs and
                       message cracker mechanisms provided in windowsx.h
                       will take care of almost all packing and unpacking
                       of these data types, in a 32-bit portable way.
                    9. Become familiar with the common compiler warnings
                       and errors that you're likely to encounter as you
                       convert to STRICT.
   Common compiler  =======================================================
      warnings and
            errors  Here are some common compiler warnings and errors you
                    might get when trying to make your application compile
                    cleanly as C++ or with all messages enabled, with or
                    without STRICT.
                    These are also the kinds of warnings and errors you'll
                    receive as you maintain STRICT source code.
Warning: Function should return a value
                    This warning means that a function declared to return a
                    value does not return a value. In older, non-ANSI C
                    code, it was common to declare functions that did not
                    return a value with no return type:
                     int i;
                                  - 11 -
                    Functions declared in this manner are treated by the
                    compiler as being declared to return an "int". If the
                    function does not return anything, it should be
                    declared "void":
                     void foo(int i)
Warning: Call to function  with no prototype
                    This means that a function was used before it was fully
                    prototyped, or declared. It can also arise when a
                    function that takes no arguments is not prototyped with
                     void bar(); /* Should be: bar(void) */
Error: Lvalue required
Error: Type mismatch in parameter
                    These errors indicate that you are trying to assign or
                    pass a non-pointer type when a pointer type is
                    required. With STRICT defined, all handle types as well
                    as LRESULT, WPARAM, and LPARAM are internally declared
                    as pointer types, so trying to pass an int, WORD, or
                    LONG as a handle will result in these errors.
                    These errors should be fixed by properly declaring the
                    non-pointer values you're assigning or passing. In the
                    case of special constants  such as (HWND)1 to indicate
                    "insert at bottom" to the window positioning
                    functions, you should use the new macro such as
                    Only in rare cases should you suppress a type mismatch
                    error with a cast: This can often generate incorrect
                                  - 12 -
Error: Type mismatch in parameter 
foo.c(335) : warning C4049: 'argument' : indirection to different types
                    These warnings indicate that you are passing or
                    assigning a pointer of the wrong type. This is the
                    warning you get if you pass the wrong type of handle to
                    a function. This is because under STRICT all handle
                    types are defined as pointers to unique structures.
                    To suppress these warnings, fix the type mismatch error
                    in your code. Once again, it's dangerous to suppress
                    these warnings with a cast, since there may be an
                    underlying type error in your app.
Error: Type mismatch in redeclaration of 
                    This error will result if you have inconsistent
                    declarations of a variable, parameter, or function in
                    your source code.
Warning: Conversion may lose significant digits
                    This warning results when a value is converted by the
                    compiler, such as from LONG to int. You're being warned
                    because you may lose information from this cast.
                    If you're sure there are no information-loss problems,
                    you can suppress this warning with the appropriate
                    explicit cast to the smaller type.
Warning: Non-portable pointer conversion
                    This error results when you cast a near pointer or a
                    handle to a 32-bit value such as LRESULT, LPARAM, LONG
                    or DWORD. This warning almost always represents a bug,
                    because the hi-order 16 bits of the value will contain
                    a non-zero value. The compiler first converts the
                    16-bit near pointer to a 32-bit far pointer by placing
                    the current data segment value in the high 16 bits,
                    then converts this far pointer to the 32-bit value.
                    To avoid this warning and ensure that a 0 is placed in
                    the hi 16 bits, you must first cast the handle to a
                     HWND hwnd;
                     LRESULT result = (LRESULT)(UINT)hwnd;
                    In cases where you DO want the 32-bit value to contain
                    a far pointer, you can avoid the warning with an
                    explicit cast to a far pointer:
                                  - 13 -
                     char near* pch;
                     LPARAM lParam = (LPARAM)(LPSTR)pch;
Error: Size of the type is unknown or zero
                    This error results from trying to change the value of a
                    void pointer with + or +=. These typically result from
                    the fact that certain Windows functions that return
                    pointers to arbitrary types (such as GlobalLock and
                    LocalLock) are defined to return void FAR* rather than
                    To solve these problems, you should assign the void*
                    value to a properly- declared variable (with the
                    appropriate cast):
                     BYTE FAR* lpb = (BYTE FAR*)GlobalLock(h);
                     lpb += sizeof(DWORD);
Error: Not an allowed type
                    This error typically results from trying to dereference
                    a void pointer. This usually results from directly
                    using the return value of GlobalLock or LocalLock as a
                    pointer. To solve this problem, assign the return value
                    to a variable of the appropriate type (with the
                    appropriate cast) before using the pointer:
                     BYTE FAR* lpb = (BYTE FAR*)GlobalLock(h);
                     *lpb = 0;
Warning: Parameter  is never used
                    This message can result in callback functions when your
                    code does not use certain parameters. You can either
                    turn off this warning, or use the argsused pragma to
                    suppress it.
Macro APIs and message crackers
                    The macro APIs, message crackers and control APIs are
                    defined in  the file windowsx.h.  The new handle types,
                    structures, and  helper macros as well as the STRICT
                    option are a part of the standard windows.h.
                                  - 14 -
        Macro APIs  =======================================================
                    windowsx.h contains a number of new APIs implemented as
                    macros that call other APIs.  Generally they make your
                    code both easier to read and write, and they can save
                    you lots of typing.  These macros are all portable to
                    32-bit Windows.
void FAR* WINAPI GlobalAllocPtr(WORD flags, DWORD cb)
                    Same as GlobalAlloc, except that it returns a far
                    pointer directly.
void FAR* WINAPI GlobalReAllocPtr(void FAR* lp, DWORD cbNew, WORD flags)
                    Same as GlobalReAlloc, except that it takes and returns
                    a far pointer.
BOOL WINAPI GlobalFreePtr(void FAR* lp)
                    Same as GlobalFree, except used with far pointer
                    alloced (or realloced) with functions above.
BOOL WINAPI GlobalLockPtr(void FAR* lp)
                    Same as GlobalLock, except used with far pointer.
BOOL WINAPI GlobalUnlockPtr(void FAR* lp)
                    Same as GlobalUnlock, except used with far pointer.
HMODULE WINAPI GetInstanceModule(HINSTANCE hInstance);
                    Maps an instance handle to a module handle.
void    WINAPI UnlockResource(HGLOBAL hResource);
                    Unlocks a global resource handle locked with
BOOL    WINAPI DeletePen(HPEN hpen)
                    Deletes a pen (with proper typecasting)
HPEN    WINAPI GetStockPen(int i);
                    Returns one of the stock pens indicated by i (properly
                    cast to HPEN).
HPEN    WINAPI SelectPen(HDC hdc, HPEN hpenSelect)
                    Selects a pen and returns previously selected pen (with
                    proper type casting).
BOOL    WINAPI DeleteBrush(HBRUSH hbr)
                                  - 15 -
                    Deletes a brush (with proper typecasting)
HBRUSH  WINAPI GetStockBrush(int i);
                    Returns one of the stock brushes indicated by i
                    (properly cast to HBRUSH).
HBRUSH  WINAPI SelectBrush(HDC hdc, HBRUSH hbrSelect)
                    Selects a brush and returns previously selected brush
                    (with proper type casting).
BOOL    WINAPI DeleteFont(HFONT hfont)
                    Deletes a font (with proper typecasting)
HFONT   WINAPI GetStockFont(int i);
                    Returns one of the stock fonts indicated by i (properly
                    cast to HFONT)
HFONT   WINAPI SelectFont(HDC hdc, HFONT hfontSelect)
                    Selects a font and returns previously selected font
                    (with proper type casting).
BOOL    WINAPI DeleteBitmap(HBITMAP hbm)
                    Deletes a bitmap (with proper typecasting)
HBITMAP WINAPI SelectBitmap(HDC hdc, HBITMAP hbmSelect)
                    Selects a bitmap and returns previously selected bitmap
                    (with proper type casting)
BOOL    WINAPI DeleteRgn(HRGN hrgn)
                    Deletes a region (with proper typecasting)
int     WINAPI CopyRgn(HRGN hrgnDst, HRGN hrgnSrc);
                    Copies hrgnSrc to hrgnDst.
int     WINAPI IntersectRgn(HRGN hrgnResult, HRGN hrgnA, HRGN hrgnB);
                    Intersects hrgnA with hrgnB, setting hrgnResult to the
int     WINAPI SubtractRgn(HRGN hrgnResult, HRGN hrgnA, HRGN hrgnB);
                    Subtracts hrgnB from hrgnA, setting hrgnResult to the
int     WINAPI UnionRgn(HRGN hrgnResult, HRGN hrgnA, HRGN hrgnB);
                    Computes the union of hrgnA and hrgnB, setting
                    hrgnResult to the result.
int     WINAPI XorRgn(HRGN hrgnResult, HRGN hrgnA, HRGN hrgnB);
                                  - 16 -
                    XORs hrgnA with hrgnB, setting hrgnResult to the
void    WINAPI InsetRect(RECT FAR* lprc, int dx, int dy)
                    Insets the edges of a rectangle by dx and dy.
HINSTANCE WINAPI GetWindowInstance(HWND hwnd)
                    Returns the instance handle associated with a window.
DWORD   WINAPI GetWindowStyle(HWND hwnd)
                    Returns the window style of a window.
DWORD   WINAPI GetWindowExStyle(HWND hwnd)
                    Returns the extended window style of a window
int     WINAPI GetWindowID(HWND hwnd)
                    Returns the window ID of a window.
void    WINAPI SetWindowRedraw(HWND hwnd, BOOL fRedraw)
                    Disables or enables drawing in a window, without hiding
                    the window.
WNDPROC WINAPI SubclassWindow(HWND hwnd, WNDPROC lpfnWndProc)
                    Subclasses a window by storing a new window procedure
                    address.  Returns previous window procedure address.
BOOL    WINAPI IsMinimized(HWND hwnd)
                    Returns TRUE if hwnd is minimized
BOOL    WINAPI IsMaximized(HWND hwnd)
                    Returns TRUE if hwnd is maximized
BOOL    WINAPI IsRestored(HWND hwnd)
                    Returns TRUE if hwnd is restored.
BOOL    WINAPI IsLButtonDown(void)
                    Returns TRUE if the left mouse button is down.
BOOL    WINAPI IsRButtonDown(void)
                    Returns TRUE if the right mouse button is down.
BOOL    WINAPI IsMButtonDown(void)
                    Returns TRUE if the middle mouse button is down.
                                  - 17 -
                    3.1-only macro APIs
void    WINAPI MapWindowPoints(HWND hwndFrom, HWND hwndTo, POINT FAR* lppt,
WORD cpt);
                    Maps cpt points at *lppt from the coordinate system of
                    hwndFrom to that of hwndTo.
void    WINAPI MapWindowRect(HWND hwndFrom, HWND hwndTo, RECT FAR* lprc)
                    Maps a rectangle from the coordinate system of hwndFrom
                    to that of hwndTo.
   Control message  =======================================================
                    New APIs have been added for use in dealing with the
                    various controls. These APIs are implemented as macros
                    that call SendMessage, and they take care of packing
                    the various parameters into wParam and lParam and
                    casting the return value as needed.
                    These macros are fully portable to 32-bit Windows: The
                    32-bit versions will transparently take into account
                    any differences in parameter packing on the 32-bit
                    These macros make your source code smaller and more
                    readable.  They're especially valuable with STRICT in
                    order to prevent type errors and incorrect message
                    parameter passing.
                    There is a 1-to-1 correspondence between a control API
                    and a window message or window manager API.  In the
                    interests of brevity, the control APIs are simply
                    listed below: For more information, you can check out
                    the macro definitions in windowsx.h and the
                    documentation for the corresponding window message.
                    Some of the new control APIs are usable with Windows
                    3.1 only, and are not available if you #define WINVER
------------------  Here is an example showing how these new APIs are used.
       Control API  First, here is some code that uses old-style
          Examples  SendMessage calls to print all the lines in an edit
------------------  control:
                                  - 18 -
void PrintLines(HWND hwndEdit)
  int line;
  int lineLast = (int)SendMessage(hwndEdit, EM_GETLINECOUNT,
                                    0, 0L);
  for (line = 0; line < lineLast; line++)
    int cch;
    char ach[80];
    *((LPINT)ach) = sizeof(ach);
    cch = (int)SendMessage(hwndEdit, EM_GETLINE,
                           line, (LONG)(LPSTR)ach);
    // ... or whatever ...
                    Using control APIs, this code would be simplified as
void PrintLines(HWND hwndEdit)
  int line;
  int lineLast = Edit_GetLineCount(hwndEdit);
  for (line = 0; line < lineLast; line++)
    int cch;
    char ach[80];
    cch = Edit_GetLine(hwndEdit, line, ach, sizeof(ach));
    // ... or whatever ...
                    The new style code is much easier to read (and write),
                    doesn't generate compiler warnings, and doesn't have
                    any non-portable casts.
                    Here is a complete list of the control APIs.  See
                    windowsx.h for more info.
                        Static_Enable(hwnd, fEnable)
                        Static_GetText(hwnd, lpch, cchMax)
                                  - 19 -
                        Static_SetText(hwnd, lpsz)
                        Static_SetIcon(hwnd, hIcon)
                        Static_GetIcon(hwnd, hIcon)
                        Button_Enable(hwnd, fEnable)
                        Button_GetText(hwnd, lpch, cchMa
                        Button_SetText(hwnd, lpsz)
                        Button_SetCheck(hwnd, check)
                        Button_SetState(hwnd, state)
                        Button_SetStyle(hwnd, style, fRedraw)
                        Edit_Enable(hwnd, fEnable)
                        Edit_GetText(hwnd, lpch, cchMax)
                        Edit_SetText(hwnd, lpsz)
                        Edit_LimitText(hwnd, cchMax)
                        Edit_GetLine(hwnd, line, lpch, cchMax)
                        Edit_GetRect(hwnd, lprc)
                        Edit_SetRect(hwnd, lprc)
                        Edit_SetRectNoPaint(hwnd, lprc)
                        Edit_SetSel(hwnd, ichStart, ichEnd)
                        Edit_ReplaceSel(hwnd, lpszReplace)
                        Edit_SetModify(hwnd, fModified)
                        Edit_LineFromChar(hwnd, ich)
                        Edit_LineIndex(hwnd, line)
                        Edit_LineLength(hwnd, line)
                        Edit_Scroll(hwnd, dv, dh)
                        Edit_SetPasswordChar(hwnd, ch)
                        Edit_SetTabStops(hwnd, cTabs, lpTabs)
                        Edit_SetWordBreak(hwnd, lpfnWordBreak)
                        Edit_FmtLines(hwnd, fAddEOL)
                        Edit_SetHandle(hwnd, h)
                        ScrollBar_Enable(hwnd, flags)
                        ScrollBar_Show(hwnd, fShow)
                        ScrollBar_SetPos(hwnd, pos, fRedraw)
                                  - 20 -
                        ScrollBar_SetRange(hwnd, posMin, posMax, fRedraw)
                        ScrollBar_GetRange(hwnd, lpposMin, lpposMax)
                        ListBox_Enable(hwnd, fEnable)
                        ListBox_AddString(hwnd, lpsz)
                        ListBox_InsertString(hwnd, lpsz, index)
                        ListBox_AddItemData(hwnd, data)
                        ListBox_InsertItemData(hwnd, lpsz, index)
                        ListBox_DeleteString(hwnd, index)
                        ListBox_GetTextLen(hwnd, index)
                        ListBox_GetText(hwnd, index, lpszBuffer)
                        ListBox_GetItemData(hwnd, index)
                        ListBox_SetItemData(hwnd, index, data)
                        ListBox_FindString(hwnd, indexStart, lpszFind)
                        ListBox_FindItemData(hwnd, indexStart, data)
                        ListBox_SetSel(hwnd, fSelect, index)
                        ListBox_SelItemRange(hwnd, fSelect, first, last)
                        ListBox_SetCurSel(hwnd, index)
                        ListBox_SelectString(hwnd, indexStart, lpszFind)
                        ListBox_SelectItemData(hwnd, indexStart, data)
                        ListBox_GetSel(hwnd, index)
                        ListBox_GetSelItems(hwnd, cItems, lpIndices)
                        ListBox_SetTopIndex(hwnd, indexTop)
                        ListBox_SetColumnWidth(hwnd, cxColumn)
                        ListBox_SetHorizontalExtent(hwnd, cxExtent)
                        ListBox_SetTabStops(hwnd, cTabs, lpTabs)
                        ListBox_GetItemRect(hwnd, index, lprc)
                        ListBox_SetCaretIndex(hwnd, index)
                        ListBox_SetAnchorIndex(hwnd, index)
                        ListBox_Dir(hwnd, attrs, lpszFileSpec)
                        ListBox_AddFile(hwnd, lpszFilename)
          3.1 only      ListBox_SetItemHeight(hwnd, index, cy)
          3.1 only      ListBox_GetItemHeight(hwnd, index)
                        ComboBox_Enable(hwnd, fEnable)
                        ComboBox_GetText(hwnd, lpch, cchMax)
                        ComboBox_SetText(hwnd, lpsz)
                        ComboBox_LimitText(hwnd, cchLimit)
                                  - 21 -
                        ComboBox_SetEditSel(hwnd, ichStart, ichEnd)
                        ComboBox_AddString(hwnd, lpsz)
                        ComboBox_InsertString(hwnd, index, lpsz)
                        ComboBox_AddItemData(hwnd, data)
                        ComboBox_InsertItemData(hwnd, index, data)
                        ComboBox_DeleteString(hwnd, index)
                        ComboBox_GetLBTextLen(hwnd, index)
                        ComboBox_GetLBText(hwnd, index, lpszBuffer)
                        ComboBox_GetItemData(hwnd, index)
                        ComboBox_SetItemData(hwnd, index, data)
                        ComboBox_FindString(hwnd, indexStart, lpszFind)
                        ComboBox_FindItemData(hwnd, indexStart, data)
                        ComboBox_SetCurSel(hwnd, index)
                        ComboBox_SelectString(hwnd, indexStart, lpszSelect)
                        ComboBox_SelectItemData(hwnd, indexStart, data)
                        ComboBox_Dir(hwnd, attrs, lpszFileSpec)
                        ComboBox_ShowDropdown(hwnd, fShow)
          3.1 only      ComboBox_GetDroppedState(hwnd)
          3.1 only      ComboBox_GetDroppedControlRect(hwnd, lprc)
          3.1 only      ComboBox_GetItemHeight(hwnd)
          3.1 only      ComboBox_SetItemHeight(hwnd, cyItem)
          3.1 only      ComboBox_GetExtendedUI(hwnd)
          3.1 only      ComboBox_SetExtendedUI(hwnd, flags)
   Message cracker  =======================================================
                    The message cracker macros provide a convenient,
                    portable, and type-safe mechanism for dealing with
                    window messages, their parameters, and their return
                    The basic idea is that instead of having to pick apart
                    message parameters with casts and HIWORD/LOWORD and
                    such, you simply declare and implement a function that
                    has the properly typed parameters and return value.
                    The message crackers efficiently pick apart the message
                    parameters, call your function, and return the
                    appropriate value from the window message.
                    Message forwarder macros allow you to forward a message
                    via DefWindowProc, SendMessage, or CallWindowProc. The
                    macros do the work of packing explicitly typed
                                  - 22 -
                    arguments into wParam and lParam and calling the
                    appropriate function.
                    With these macros, you don't have to worry about what
                    parameters go where and what kind of casting you need
                    to do.  They are also portable to 32-bit Windows (where
                    some of the message parameters have changed).
------------------  For each window message, there are two macros: A
     Using message  cracker and a forwarder. To see how these macros work,
      crackers and  let's use the WM_CREATE message as an example. Here is
        forwarders  a code fragment showing how a window procedure could
------------------  use message crackers to handle the WM_CREATE message.
                    For now, our WM_CREATE message processing will simply
                    call DefWindowProc.
                    NOTE: The following examples use STRICT-style
                    declarations, but you can use message crackers without
// Message handler function prototype (declared in a .h file)
BOOL MyCls_OnCreate(HWND hwnd, CREATESTRUCT FAR* lpCreateStruct);
// Window procedure for class "MyCls" (defined in a .c file)
LRESULT _export CALLBACK MyCls_WndProc(HWND hwnd, UINT msg,
                                       WPARAM wParam,
                                       LPARAM lParam)
  switch (msg)
    case WM_CREATE:
      return HANDLE_WM_CREATE(hwnd, wParam, lParam,
      return DefWindowProc(hwnd, msg, wParam, lParam);
// WM_CREATE message handler function.
// For now, just calls DefWindowProc.
BOOL MyCls_OnCreate(HWND hwnd,
                    CREATESTRUCT FAR* lpCreateStruct)
  return FORWARD_WM_CREATE(hwnd, lpCreateStruct, DefWindowProc);
                                  - 23 -
                    Some important points:
                    o You must declare and implement a function to handle
                      the message, which must have a particular "signature"
                      (the order and type of the parameters, and the type
                      of the return value, if any).
                    o You pass this message handler function as the last
                      parameter to the HANDLE_WM_XXX function. This
                      function must be declared and fully prototyped before
                      being used with a message cracker.
                    o You must always return the value returned by the
                      HANDLE_WM_XXX function, even if the message handler
                      function is declared void.
                    o The FORWARD_WM_XXX function always has the same
                      signature (parameters and return type) as its
                      corresponding message handler function, with the
                      addition of the last parameter, which is the API or
                      function to be used to forward the message.
                    o You don't need to use message crackers to handle all
                      your messages. Old-style message handling code can be
                      mixed with message crackers in the same window
                    o By convention, message handler functions are named
                      "Class_OnXXX", where Class is the window class name
                      and XXX is the name of the corresponding message,
                      minus the "WM_" and using mixed case instead of all
                      caps. This is just a convention: you can use any name
                      you like for the function (although you can't alter
                      its signature).
------------------  The HANDLE_MSG macro can be used to reduce the amount
   Saving time and  of "noise" in your window procedures and save yourself
         improving  some typing.  The HANDLE_MSG macro replaces the "case
  readability with  WM_XXX:", the HANDLE_WM_XXX call, and the return.  So,
        HANDLE_MSG  instead of
  return HANDLE_WM_CREATE(hwnd, wParam, lParam, MyCls_OnCreate);
                                  - 24 -
                    you can just type:
HANDLE_MSG(hwnd, WM_CREATE, MyCls_OnCreate);
                    HANDLE_MSG is optional.  Some people prefer to "spell
                    out" the goings-on in their window procedures, and
                    others prefer the convenience and brevity of the
                    HANDLE_MSG form.
                    HANDLE_MSG requires that you name your window procedure
                    message parameters wParam and lParam. The examples in
                    this document use HANDLE_MSG.
------------------  To see how message crackers work, we'll take a look at
       How message  the definition of the message cracker macros as found
     crackers work  in windowsx.h (these definitions are somewhat
------------------  simplified for the sake of clarity):
// BOOL Cls_OnCreate(HWND hwnd, CREATESTRUCT FAR* lpCreateStruct)
#define HANDLE_WM_CREATE(hwnd, wParam, lParam, fn) \
((fn)(hwnd, (CREATESTRUCT FAR*)lParam) ? 0L : (LRESULT)-1L)
#define FORWARD_WM_CREATE(hwnd, lpCreateStruct, fn) \
(BOOL)(DWORD)(fn)(hwnd, WM_CREATE, 0, (LPARAM)lpCreateStruct)
                    The comment shows the signature of the message handler
                    function that you must declare and implement.
                    Essentially all these macros do is convert the wParam
                    and lParam message parameters to and from specific,
                    explicitly typed parameters and invoke a function.
                    The HANDLE_WM_CREATE macro calls the handler function
                    with the appropriate parameters, obtained by casting
                    wParam and lParam appropriately.  The return value of
                    the handler value is mapped to the proper LRESULT
                    return value, in this case 0L or -1L.  If the handler
                    function returns no value, then 0L is returned.
                    The FORWARD_WM_CREATE macro calls the supplied message
                    function (which must have the same signature as
                    DefWindowProc) with the proper hwnd, wParam, and lParam
                    parameters calculated from the parameters supplied to
                    the macro.
                    The HANDLE_MSG macro is quite simple too:
                                  - 25 -
#define HANDLE_MSG(hwnd, message, fn)    \
case message: return HANDLE_##message(fn, hwnd, wParam, lParam)
                    It simply does the "case" for you, and returns the
                    result of the proper HANDLE_WM_XXX function.  The
                    message parameter names wParam and lParam are
                    hard-wired into this macro.
------------------  Here is a more detailed example of a window procedure
   Message cracker  for the "Template" class that uses message crackers and
          examples  message forwarders:
// Excerpt from header file for class Template
// Window procedure prototype
LRESULT _export CALLBACK Template_WndProc(HWND hwnd, WORD msg,
                                          WPARAM wParam,
                                          LPARAM lParam)
// Default message handler
#define Template_DefProc    DefWindowProc
// Template class message handler functions,
// declared in a header file:
void Template_OnMouseMove(HWND hwnd, int x,
                          int y, UINT keyFlags);
void Template_OnLButtonDown(HWND hwnd, BOOL fDoubleClick,
                            int x, int y, UINT keyFlags);
void Template_OnLButtonUp(HWND hwnd, int x,
                          int y, UINT keyFlags);
HBRUSH Template_OnCtlColor(HWND hwnd, HDC hdc,
                           HWND hwndChild, int type);
// Exerpt from c source file for class Template
// Template window procedure implementation.
LRESULT _export CALLBACK Template_WndProc(HWND hwnd, WORD msg,
                                          WPARAM wParam,
                                          LPARAM lParam)
  switch (msg)
                                  - 26 -
    HANDLE_MSG(hwnd, WM_MOUSEMOVE, Template_OnMouseMove);
    HANDLE_MSG(hwnd, WM_LBUTTONDOWN, Template_OnLButtonDown);
    HANDLE_MSG(hwnd, WM_LBUTTONDBLCLK, Template_OnLButtonDown);
    HANDLE_MSG(hwnd, WM_LBUTTONUP, Template_OnLButtonUp);
      return Template_DefProc(hwnd, msg, wParam, lParam);
// Message handler function implementations:
void Template_OnMouseMove(HWND hwnd, int x, int y, UINT keyFlags)
void Template_OnLButtonDown(HWND hwnd, BOOL fDoubleClick,
                            int x, int y, UINT keyFlags)
void Template_OnLButtonUp(HWND hwnd, int x, int y, UINT keyFlags)
HBRUSH Template_OnCtlColor(HWND hwnd, HDC hdc,
                           HWND hwndChild, int type)
  switch (type)
    case CTLCOLOR_BTN:
      // Pass the WM_CTLCOLOR message on to the parent,
      // and use the edit control colors.
      return FORWARD_WM_CTLCOLOR(GetParent(hwnd), hdc, hwndChild,
                                 CTLCOLOR_EDIT, SendMessage);
      // Perform default processing of the message.
      return FORWARD_WM_CTLCOLOR(hwnd, hdc, hwndChild,
                                 type, Template_DefProc);
                                  - 27 -
------------------  For the most part, the OnXXX message handler function
   Message handler  parameters have the same name and type as those shown
          function  in the documentation of the corresponding window
        signatures  message. To find out exactly what those messages are,
------------------  look at the commented function prototype in windowsx.h
                    before the message cracker for the message you're
                    interested in.
                    There are a few cases where the OnXXX functions work a
                    bit differently than the corresponding window message:
                    o OnCreate (and OnNCCreate) must return TRUE if all is
                      well, or the window will not be created and
                      CreateWindow will return NULL.
                    o The signatures for OnKey and On?ButtonDown functions
                      are a little different from their corresponding
                      messages.  OnKey handles both key up and key down
                      messages with the fDown parameter. The On?ButtonDown
                      functions handle double click messages too, with the
                      fDoubleClick parameter (though you must be sure to
                      register your window class with CS_DBLCLKS if you
                      want to handle double clicks).
                    o The OnChar function is not passed the virtual key or
                      key flags information, as this information is not
                      usable in a WM_CHAR handling. This is because
                      different virtual keys can generate the same WM_CHAR
                      messages, and certain key macro processors will
                      generate WM_CHAR messages with no virtual key or
------------------  For every window class, there is a function that must
         Improving  be called to perform the default processing for that
      reusability:  window.  Normally, this call is DefWindowProc, but if
  Template_DefProc  you're subclassing a window, it's CallWindowProc, or if
------------------  you're implementing an MDI child window, it's
                    DefMDIChildProc, etc.
                    A very common programming mistake is to copy code from
                    another window procedure without making the appropriate
                    change to the default message handler function. This
                    can lead to subtle, hard to track down bugs.
                                  - 28 -
                    This is the purpose of the Template_DefProc macro
                    defined and used in the example above.  Every class
                    should have an appropriate XXX_DefProc macro (or
                    function) defined which will perform default message
                    In the example above, the default message handler is
                    DefWindowProc, so Template_DefProc is defined as
                     #define Template_DefProc   DefWindowProc.
                    For an MDI child window, it might be:
                     #define MdiWnd_DefProc     DefMDIChildProc
                    The advantage of this scheme is that to steal code from
                    another window procedure, you need only change the
                    class name prefix, and the proper default handling will
                    be taken care of automatically.
------------------  Message crackers and forwarders work well with new
       Private and  window messages that you define.  You must write a
 registered window  message cracker and forwarder macro for the new message
          messages  -- the easiest way to do this is to copy and modify
------------------  existing macros from windowsx.h.
                    If your new message value is a constant (e.g.,
                    WM_USER+100), then you can use HANDLE_MSG to handle the
                    message in your window procedure.  However, if your new
                    message is registered with RegisterWindowMessage,
                    HANDLE_MSG can't be used, because variables cannot be
                    used as switch statement case values: only constants
                    can.  In this case, you can handle it as follows:
// In Template class initialization code:
WM_NEWMESSAGE = RegisterWindowMessage("WM_NEWMESSAGE");
// In Template_WndProc: window procedure:
LRESULT _export CALLBACK Template_WndProc(HWND hwnd, WORD msg,
                                          WPARAM wParam,
                                  - 29 -
                                          LPARAM lParam)
  if (msg == WM_NEWMESSAGE)
    HANDLE_WM_NEWMESSAGE(hwnd, wParam, lParam,
  switch (msg)
    HANDLE_MSG(hwnd, WM_MOUSEMOVE, Template_OnMouseMove);
------------------  It's very common for a window to have some additional
  Message crackers  "instance data" associated with it that is kept in a
        and window  separate data structure allocated by the application.
     instance data  This separate data structure is associated with its
------------------  corresponding window by storing a pointer to the
                    structure in a  specially-named window property or in a
                    window word (allocated by setting  the cbWndExtra field
                    of the WNDCLASS structure when the class is
                    The message crackers fully support this style of
                    programming by allowing you to pass a pointer to the
                    instance data as the first parameter to the message
                    handlers instead of a window handle.  The following
                    example should make this clear:
// Window instance data structure.
// Must include window handle field.
typedef struct _FOO
    HWND hwnd;
    int otherStuff;
} FOO;
// "Foo" window class was registered with
// cbWndExtra = sizeof(FOO*), so we can use
// a window word to store back pointer.
// Window properties can also be used.
// These macros get and set the hwnd -> FOO* backpointer.
// Use GetWindowWord or GetWindowLong as appropriate based
// on the default size of data pointers.
                                  - 30 -
#if (defined(__SMALL__) | defined(__MEDIUM__))
#define Foo_GetPtr(hwnd) \
        (FOO*)GetWindowWord((hwnd), 0)
#define Foo_SetPtr(hwnd, pfoo) \
        (FOO*)SetWindowWord((hwnd), 0, (WORD)(pfoo))
#define Foo_GetPtr(hwnd) \
        (FOO*)GetWindowLong((hwnd), 0)
#define Foo_SetPtr(hwnd, pfoo) \
        (FOO*)SetWindowLong((hwnd), 0, (LONG)(pfoo))
// Default message handler
#define Foo_DefProc DefWindowProc
// Message handler functions, declared with a FOO* as their
// first argument, rather than an HWND.  Other than that,
// their signature is identical to that shown in windowsx.h.
BOOL Foo_OnCreate(FOO* pfoo, CREATESTRUCT FAR* lpcs);
void Foo_OnPaint(FOO* pfoo);
// Code to register the Foo window class:
BOOL Foo_Init(HINSTANCE hinst)
    WNDCLASS cls;
    cls.hCursor         = ...;
    cls.hIcon           = ...;
    cls.lpszMenuName    = ...;
    cls.hInstance       = hinst;
    cls.lpszClassName   = "Foo";
    cls.hbrBackground   = ...;
    cls.lpfnWndProc     = Foo_WndProc;           = CS_DBLCLKS;
    cls.cbWndExtra      = sizeof(FOO*);  // room for instance
                                         // data ptr
    cls.cbClsExtra      = 0;
    return RegisterClass(&cls);
// The window procedure for class "Foo".  This demonstrates how
// instance data is attached to a window and passed to the
// message handler functions.  It's fully STRICT enabled,
// and Win 3.0 compatible.
                                  - 31 -
LRESULT CALLBACK _export Foo_WndProc(HWND hwnd, UINT msg,
                                     WPARAM wParam,
                                     LPARAM lParam)
  FOO* pfoo = Foo_GetPtr(hwnd);
  if (pfoo == NULL)
    // If we're creating the window, then try to allocate it.
    if (msg == WM_NCCREATE)
      // Create the instance data structure, set up the hwnd
      // backpointer field, and associate it with the window.
      pfoo = (FOO*)LocalAlloc(LMEM_FIXED | LMEM_ZEROINIT,
      // If an error occured, return 0L to fail the CreateWindow
      // call. This will cause CreateWindow to return NULL.
      if (pfoo == NULL)
        return 0L;
      pfoo->hwnd = hwnd;
      Foo_SetPtr(hwnd, pfoo);
      // NOTE: the rest of the FOO structure should be
      // initialized inside of Template_OnCreate
      // (or Template_OnNCCreate).
      // Further creation data may be accessed through the
      // CREATESTRUCT FAR* parameter.
      // It turns out WM_NCCREATE is NOT necessarily the first
      // message recieved by a top-level window
      // (WM_GETMINMAXINFO is).
      // Pass messages that precede WM_NCCREATE on through to
      // Foo_DefProc
      return Foo_DefProc(hwnd, msg, wParam, lParam);
  if (msg == WM_NCDESTROY)
    // The window is being destroyed: free up the FOO structure.
                                  - 32 -
    // NOTE: If you want to handle WM_NCDESTROY with a message
    // cracker (NOT RECOMMENDED), you can uncomment the lines
    // below.
    // LRESULT result = HANDLE_MSG(hwnd, WM_NCDESTROY,
    // Deallocation of any fields of the FOO structure should
    // be done inside the OnNCDestroy function.
    pfoo = NULL;
    Foo_SetPtr(hwnd, NULL);
    //return result;
  switch (msg)
    HANDLE_MSG(pfoo, WM_CREATE, Foo_OnCreate);
    HANDLE_MSG(pfoo, WM_PAINT, Foo_OnPaint);
      return Foo_DefProc(hwnd, msg, wParam, lParam);
------------------  Dialog procedures are different from window procedures
  Message crackers  in that they return a BOOL indicating whether the
        and dialog  message was processed rather than an LRESULT. For this
        procedures  reason, you can't use HANDLE_MSG: You must invoke the
------------------  message cracker macro explicitly.
                    Here's an example that shows how you'd use message
                    crackers in a dialog procedure:
                     BOOL MyDlg_OnInitDialog(HWND hwndDlg, HWND hwndFocus,
                                             LPARAM lParam);
                     void MyDlg_OnCommand(HWND hwnd, int id, HWND hwndCtl,
                                          UINT codeNotify);
                     BOOL _export CALLBACK MyDlg_DlgProc(HWND hwndDlg, UINT
                                                         WPARAM wParam,
                     LPARAM lParam)
                                  - 33 -
                       switch (msg)
                         // Since HANDLE_WM_INITDIALOG returns an LRESULT,
                         // we must cast it to a BOOL before returning.
                         case WM_INITDIALOG:
                           return (BOOL)HANDLE_WM_INITDIALOG(hwndDlg,
                                   wParam, lParam,
                         case WM_COMMAND:
                           HANDLE_WM_COMMAND(hwndDlg, wParam, lParam,
                           return TRUE;
                           return FALSE;
                    If you'd like to process messages that return values
                    such as WM_ERASEBKGND in your dialog procedure, or
                    would like to make it easier to share code between your
                    window procedures and your dialog procedures, you may
                    want to make use of the techniques shown later in
                    "Dialog Procedures: A Better Way."
------------------  Message crackers can also be used to simplify window
  Message crackers  subclassing code. With message crackers, unprocessed
        and window  messages must be forwarded using the appropriate
       subclassing  FORWARD_WM_* macro.  When you are subclassing a window,
------------------  the proper way to forward unprocessed messages is by
                    calling CallWindowProc, passing it the previous window
                    procedure address, along with the four standard window
                    message parameters.
                    The FORWARD_WM_* macros can't be used directly with
                    CallWindowProc, because they can only invoke functions
                    having the standard window procedure signature:
                    CallWindowProc has an extra WNDPROC parameter.
                    This problem is handled easily by simply declaring
                    XXX_DefProc as a function instead of a macro.  Your
                    function must call CallWindowProc instead of calling
                                  - 34 -
                    Here's an example showing how this works:
// Global variable that holds the previous window
// procedure address of the subclassed window:
WNDPROC Foo_lpfnwpDefProc = NULL;
// Code fragment to subclass a window
// and store previous wndproc value:
void SubclassFoo(HWND hwndFoo)
  // Global application instance handle:
  extern HINSTANCE g_hinstFoo;
  // SubclassWindow is a macro API that calls SetWindowLong
  // as appropriate to change the window procedure of hwndFoo.
  Foo_lpfnwpDefProc = SubclassWindow(hwndFoo,
                      ((FARPROC)Foo_WndProc, g_hinstFoo));
// Default message handler function
// This function invokes the superclasses' window procedure.
// It must be declared with the same signature as any window
// procedure, so it can be used with the FORWARD_WM_* macros.
LRESULT Foo_DefProc(HWND hwnd, UINT msg,
                    WPARAM wParam, LPARAM lParam)
  return CallWindowProc(Foo_lpfnwpDefProc,
                        hwnd, msg, wParam, lParam);
// Foo window procedure.  Everything here is the same as in the
// normal non-subclassed case: the differences are encapsulated // in
                             WPARAM wParam, LPARAM lParam)
  switch (msg)
    HANDLE_MSG(hwnd, WM_CHAR, Foo_OnChar);
                                  - 35 -
      // Be sure to call Foo_DefProc, NOT DefWindowProc!
      return Foo_DefProc(hwnd, msg, wParam, lParam);
// Message handlers
void Foo_OnChar(HWND hwnd, UINT ch, int cRepeat)
  if (ch == ... || whatever)
    // handle it here
    // Forward the message on to Foo_DefProc
    FORWARD_WM_CHAR(hwnd, ch, cRepeat, Foo_DefProc);
------------------  There are two longstanding sources of confusion and
Dialog procedures:  bugs in Windows dialog procedures: 1. There is no way
      A better way  to return a value from a message handled by a dialog
------------------  procedure, and 2. it's not possible to execute the
                    default dialog behavior for a message before executing
                    your own code in your dialog procedure.
                    Here is a simple solution to both of these problems
                    that is compatible with both Windows 3.0 and 3.1.  It
                    unifies the way window procedures and dialog procedures
                    are coded, and it works very nicely with message
              Note  These techniques, like message crackers, are completely
                    optional.  You can use these techniques with or without
                    message crackers.
                    You can code a dialog procedure just as if it were a
                    window procedure: you have the same freedom to return
                    values and execute the default dialog processing
                    messages as you do with window procedures.  It's also
                    easier to copy or share code between dialog and window
                                  - 36 -
                    Executing default dialog procedure functionality
                    Although Windows provides the DefDlgProc API, it can't
                    be used as is for our purposes because its
                    implementation calls the dialog procedure again.  If we
                    called it from our dialog procedure, the dialog
                    procedure would be called again, recursively, until we
                    run out of stack space and crash.  To prevent this
                    infinite recursion, we need only detect that we're
                    being called recursively and return FALSE, which will
                    cause the default processing to be performed.
                    Returning message results from dialog procedures
                    Windows 3.0 and 3.1 both support a general mechanism
                    for returning values from messages handled in dialog
                    procedures.  Essentially, you store the return value
                    with SetWindowLong, which will get returned from the
                    message when your dialog procedure returns TRUE.
                    There are some special cases you have to worry about:
                    in some cases, the return value must be returned in
                    place of the BOOL return value.
                    How it works
                    Here is some code that shows how all this comes
// function prototypes in header file..
BOOL CALLBACK _export MyDlg_OldProc(HWND hwndDlg, UINT msg,
                                    WPARAM wParam,
                                    LPARAM lParam);
LRESULT MyDlg_DlgProc(HWND hwndDlg, UINT msg,
                      WPARAM wParam, LPARAM lParam);
// implementation in .c file..
// static (or global) variable for preventing infinite recursion
                                  - 37 -
static BOOL fMyDlgRecurse = FALSE;
BOOL CALLBACK _export MyDlg_OldProc(HWND hwndDlg, UINT msg,
                                    WPARAM wParam,
                                    LPARAM lParam);
  LRESULT result;
  // Check for possible recursion.  If so, just return FALSE
  // after clearing the recursion flag, to ensure that the
  // default processing is executed.
  if (fMyDlgRecurse)
    fMyDlgRecurse = FALSE;
    return FALSE;
  result = MyDlg_DlgProc(hwndDlg, msg, wParam, lParam);
  // Here if we handled the message, and want to return result.
  switch (msg)
    // The following messages are special-cased by the dialog
    // manager, and assumed to be returned as a BOOL from the
    // dialog procedure:
    case WM_CTLCOLOR:
      return (BOOL)LOWORD(result);
      // All other messages use the DWL_MSGRESULT window words:
      SetWindowLong(hwndDlg, DWL_MSGRESULT, (LPARAM)result);
      return TRUE;
LRESULT MyDlg_DlgProc(HWND hwndDlg, UINT msg,
                      WPARAM wParam, LPARAM lParam);
  switch (msg)
                                  - 38 -
    HANDLE_MSG(hwndDlg, WM_INITDIALOG, MyDlg_OnInitDialog);
    HANDLE_MSG(hwndDlg, WM_COMMAND, MyDlg_OnCommand);
      // Call DefDlgProc to invoke default dialog processing
      // for messages we don't handle ourself.  Set recursion
      // flag before we go, so MyDlg_OldDlgProc knows to
      // return FALSE.
      fMyDlgRecurse = TRUE;
      return DefDlgProc(hwndDlg, msg, wParam, lParam);
                    You must declare a static (or global) BOOL variable
                    that is initialized to FALSE.  It's safe to use the
                    same global variable for all your dialogs, even if one
                    dialog procedure brings up another dialog box.
                    What's important is that the same boolean variable be
                    used in the "OldDlgProc" and before the call to
                    DefDlgProx: a local BOOL variable must NOT be used, or
                    infinite recursion will result.
                    A simplified example using predefined macro APIs
                    Three macro APIs are defined in windowsx.h that
                    drastically simplify the code shown above.  They are
                    SetDlgMsgResult, DefDlgProcEx, and
                    Here's the same dialog code, this time using these
                    macro APIs:
// prototypes..
BOOL CALLBACK _export MyDlg_OldProc(HWND hwndDlg, UINT msg,
                                    WPARAM wParam,
                                    LPARAM lParam);
LRESULT MyDlg_DlgProc(HWND hwndDlg, UINT msg,
                      WPARAM wParam, LPARAM lParam);
// implementation..
                                  - 39 -
static BOOL fDefDlgEx = FALSE;
BOOL CALLBACK _export MyDlg_OldProc(HWND hwndDlg, UINT msg,
                                    WPARAM wParam,
                                    LPARAM lParam);
  return SetDlgMsgResult(hwndDlg, msg,
         MyDlg_DlgProc(hwndDlg, msg, wParam, lParam));
LRESULT MyDlg_DefProc(HWND hwndDlg, UINT msg,
                      WPARAM wParam, LPARAM lParam);
  return DefDlgProcEx(hwnd, msg, wParam, lParam, &fDefDlgEx);
LRESULT MyDlg_DlgProc(HWND hwndDlg, UINT msg,
                      WPARAM wParam, LPARAM lParam);
  switch (msg)
    HANDLE_MSG(hwndDlg, WM_INITDIALOG, MyDlg_OnInitDialog);
    HANDLE_MSG(hwndDlg, WM_COMMAND, MyDlg_OnCommand);
      return MyDlg_DefProc(hwnd, msg, wParam, lParam);
                    As mentioned earlier, it's safe to use the same boolean
                    fDefDlgEx variable for all your dialog procedures, or
                    you can define one for each of your dialogs. What's
                    important is that the same boolean variable be used for
                    the CheckDefDlgRecursion call AND the DefDlgProcEx call
                    in a given dialog procedure: a local BOOL variable must
                    NOT be used, or infinite recursion will result.
                    You can also use the same _DefProc function declaration
                    for all of your dialog procedures that use the same
                    fDefDlgEx variable: for example, you could implement
                    the following function:
LRESULT CommonDlg_DefProc(HWND hwndDlg, UINT msg,
                          WPARAM wParam, LPARAM lParam)
  return DefDlgProcEx(hwnd, msg, wParam, lParam, &fDefDlgEx);
                                  - 40 -
                    then, for each dialog class, #define something like:
                     #define MyDlg_DefProc  CommonDlg_DefProc
------------------  Converting existing code over to use message crackers
        Converting  is not particularly difficult.  Here are some
  existing code to  suggestions that should help:
       use message
          crackers  o Have a look at the sample app MAKEAPP for some more
------------------    detailed examples of the use of message crackers and
                      message forwarders.
                    o It's a good idea (though not necessary) to first
                      convert your code to use STRICT.  With STRICT
                      enabled, the compiler can help you find parameter
                      type mismatch and other errors much easier.
                    o It's best to declare all your message handler
                      functions in an include file, rather than declaring
                      them directly in the .c file that uses them.  You
                      don't have to use the ClassName_OnXXX naming
                      convention for your function, but we've found that
                      it's quite a helpful way to organize the code for a
                      window class.
                    o When declaring or implementing a message forwarder
                      function, just use your editor to search for and copy
                      the message handler function prototype comment from
                      windowsx.h and paste it into your source code. This
                      way you don't have to type it from scratch.
                    o Use the FORWARD_WM_* macros to send or forward
                      non-control messages to other windows by passing
                      SendMessage as the first parameter.
                    o If you have defined your own private window messages,
                      you should define a message cracker and forwarder for
                      each.  This is pretty simple to do: Just copy an
                      existing cracker and forwarder from windowsx.h and
                      edit it. Be sure to fully parenthesize your use of
                      macro parameters, and be careful with the casts you
                    Converting existing window and dialog procedures to
                    message crackers can be a fair amount of work,
                                  - 41 -
                    especially if the window and dialog procedures are
                    large.  You can mix and match old-style message
                    handlers with message crackers, so you may want to use
                    message crackers for new message handlers, or for
                    existing code you plan on modifying extensively.
                    Converting dialog procedures over to the new-style
                    LRESULT-returning dialog procedures is also something
                    that isn't required for all your dialog procedures.
                    You can convert those that you plan to modify, or that
                    contain code that you may want to reuse in other dialog
                             - 42 -


7/2/98 10:42:51 AM

Article originally contributed by

Tags: C++Builder

Check out more tips and tricks in this development video: