Premiere Issue

Incorporate custom message-handling in your applications

by Kent Reisdorph

At the operating system level, Windows is all about messages. Much of what happens in Windows is due to Windows dispatching one message or another. VCL provides events for the most often used Windows messages; you can easily handle a wide variety of Windows messages through these events. The OnKeyDown event provides the mechanism for responding to Windows WM_KEYDOWN messages, the OnMouseDown event lets you respond to WM_LBUTTONDOWN and WM_RBUTTONDOWN messages, and so on. Your C++Builder programs will handle most Windows messages through events.

However, VCL doesn't provide events for every possible Windows message--there are just too many of them. If you want to handle Windows messages that aren't encapsulated in VCL, if you want to implement user-defined messages, or if you need custom handling of Windows messages, then you'll have to roll up your sleeves and do a little more work. In this article, we'll explain how to handle messages in your applications when you need to work outside of the VCL event mechanism.

Messages and message cracking

Let's briefly review how the Windows message system works. First of all, as you probably know, Windows is driven by messages. Windows sends messages to programs (to specific windows, actually) for many different reasons, perhaps to tell a window to perform certain tasks. For example, Windows might tell a window to repaint itself by sending a WM_PAINT message. You could think of this as a command message, since Windows expects the application to respond by carrying out a task.

Windows also sends messages to notify an application that particular events have occurred. Perhaps an event has occurred within a window that the application might like to know about (messages such as WM_SIZE and WM_MOVE), or maybe something has happened within Windows itself (WM_SYSCOLORCHANGE or WM_WININICHANGE, for example).

Since controls are windows, Windows sends notification messages when an event happens within a control. Examples include a text change in an edit control (EN_UPDATE) or a user's selection of a list box item (LBN_SELCHANGE). In all, there are hundreds of Windows messages. It's up to the application to respond to messages it deems pertinent to its operation.

Message parameters

A Windows message has two parameters--the WPARAM and the LPARAM--that contain information specific to the message being sent. The WPARAM (word parameter) is a 16-bit value in 16-bit Windows but is a 32-bit value in 32-bit Windows. The LPARAM (long parameter) is a 32-bit value in either 16- or 32-bit Windows.

Windows manipulates these two parameters to carry information about the particular message being sent. For example, the WM_SIZE message contains three pieces of information: the type of sizing that's occurring (minimizing, maximizing, or restoring), the window's new width, and the window's new height. In this case, the WPARAM contains the size type and the LPARAM contains the new width and height of the window. The LPARAM is packed to hold the width and height values--the first 16 bits (called the low-order word) contain the new width, and the last 16 bits (the high-order word) contain the new height.

Most Windows messages include information sent in this manner. It's up to the application to crack the message parameters and retrieve the information Windows is sending. In some cases, a great deal of information is involved--Windows sometimes passes a pointer to a structure as part of the LPARAM parameter.

The VCL shield

Part of the job of a framework such as VCL is to shield you from the vagaries of handling messages at this level. For example, the OnKeyDown event that handles the WM_KEYDOWN message cracks the message parameters for you. The message handler that C++Builder generates for the OnKeyDown event looks like this:

      void __fastcall
      TForm1::FormKeyDown(
      TObject *Sender, WORD &Key,
      TShiftState Shift)
      {
      }
      

The generic message structure, which could handle any message, looks something like this:

      struct TMessage
      {
        unsigned int Msg;
        long WParam;
        long LParam;
        long Result;
      };
      

Aside from the Msg and Result data members, each message-handling structure will have a number of parameters. For example, the WM_ERASEBKGND message's message-handling structure, TWMEraseBkgnd, looks like this:

      struct TWMEraseBkgnd
      {
        unsigned int Msg;
        HDC DC;
        long Unused;
        long Result;
      };
      

Now, let's look at the message-cracking structure for the WM_SIZE message:

      struct TWMSize
      {
        unsigned int Msg;
        long SizeType;
        unsigned short Width;
        unsigned short Height;
        long Result;
      } ;
      

From time to time, you'll need to handle messages for which VCL doesn't provide events. WM_ERASEBKGND and WM_SETCURSOR come to mind as messages you might want to handle in your applications. To handle messages outside the normal VCL event model, you'll have to do the following:

	Create a message-map table in the class declaration for the window that will handle the message
	Add an entry to the message-map table for the message you want to handle
	Provide a message-handling function

Let's examine these steps more closely.

Create a message-map table

In order for you to handle messages for which no VCL event exists--including user-defined messages--you'll need to create a message-map table. A typical message-map table looks like this:

      BEGIN_MESSAGE_MAP
        MESSAGE_HANDLER(MYMESSAGE, TMessage, OnMyMessage)
        MESSAGE_HANDLER(WM_ERASEBKGND, TWMEraseBkgnd, WmEraseBkgnd)
      END_MESSAGE_MAP(TForm)
      

Figure A: You can use a TForm1 class declaration like this one if you handle the WM_ERASEBKGND message in your main form.

      //---------------------------------------------
      
      #ifndef MyMainH
      #define MyMainH
      
      //---------------------------------------------
      
      #include
      <vcl\Classes.hpp>
      
      #include
      <vcl\Controls.hpp>
      
      #include
      <vcl\StdCtrls.hpp>
      
      #include
      <vcl\Forms.hpp>
      
      #include
      <vcl\ExtCtrls.hpp>
      
      //---------------------------------------------
      
      class TForm1 : public TForm
      {
        __published: // IDE-managed Components
      
        private: // User declarations
      
        //
        // Message handler declaration
        //
      
        void __fastcall WmEraseBkgnd(TWMEraseBkgnd &Message);
        public: // User declarations
      
        virtual __fastcall TForm1(TComponent* Owner);
       
        //
        // The message-map table.
        //
      
        BEGIN_MESSAGE_MAP
          MESSAGE_HANDLER(WM_ERASEBKGND,
          TWMEraseBkgnd, WmEraseBkgnd)
        END_MESSAGE_MAP(TForm)
      
      };
      
      //---------------------------------------------
      extern TForm1 *MainForm;
      
      //---------------------------------------------
     
      #endif
      

Begin by declaring the message handler in the private section of the class that will be handling the message. For the WM_ERASEBKGND message, the declaration would look something like this:

      void __fastcall
      WmEraseBkgnd(
      
      TWMEraseBkgnd&
      Message);
      

Next, you'll need to provide the implementation of the message-handling function, which goes in the source unit of the form or class that's responding to the message. For example, the following WM_ERASEBKGND message handler draws a hatched pattern on the form's background:

      void __fastcall
      
      TForm1::WmEraseBkgnd(TWMEraseBkgnd&Message)
      {
        TCanvas* canvas = new TCanvas();
        canvas->Handle = Message.DC;
        canvas->Brush->Handle = CreateHatchBrush(HS_DIAGCROSS, clBlue);
        canvas->FillRect(ClientRect);
        Message.Result = true;
        delete canvas;
      }
      

Frequently, when you're handling a Windows message, you want to perform some action but also receive the default Windows behavior for that message. For instance, you might want to force all characters in an edit control to be uppercase. Doing so would entail modifying the characters, then sending the message to Windows for handling. In that case, you'd modify the Key parameter of the message-handling structure, then call the base class's Dispatch() member function to pass the message to Windows, as follows:

      void __fastcall
      
      TForm1::OnKeyDown(TWMKeyDown&Message)
      {
        if (Message.CharCode > 96 && Message.CharCode < 123)
        Message.CharCode -= 32;
        TForm::Dispatch(&Message);
      }
      

Listing A: MSGTEST.H

      
      #include
      <vcl\Forms.hpp>
      

//--------------------------------------------- 

class TForm1 : public TForm { 
  __published: // IDE-managed components private: 

  // User declarations 
  void __fastcall WmEraseBkgnd( TWMEraseBkgnd& Message); 

  public: // User declarations 
  virtual __fastcall TForm1( TComponent* Owner); 

  BEGIN_MESSAGE_MAP 
    MESSAGE_HANDLER( WM_ERASEBKGND, TWMEraseBkgnd, WmEraseBkgnd) 
  END_MESSAGE_MAP(TForm) 

}; 

//--------------------------------------------- 
extern TForm1 *Form1; 
//---------------------------------------------

Listing B: MSGTEST.CPP

//-------------------------------------------------- 
#include <vcl\vcl.h> 
#pragma hdrstop 
#include "Unit1.h" 

//-------------------------------------------------- 
#pragma resource "*.dfm" 
TForm1 * Form1; 

//-------------------------------------------------- 
__fastcall TForm1::TForm1( TComponent* Owner) : TForm(Owner) { } 

//-------------------------------------------------- 
void __fastcall TForm1::WmEraseBkgnd(TWMEraseBkgnd& Message) { 
  Canvas* canvas = new TCanvas(); 
  canvas->Handle = Message.DC; 
  canvas->Brush->Handle = CreateHatchBrush(HS_DIAGCROSS, clBlue); 
  canvas->FillRect(ClientRect); 
  Message.Result = true; delete canvas; 
} 

//--------------------------------------------------