This chapter is from the book
This chapter is from the book
This chapter is from the book
Anatomy of a Message System: VCL
There's much more to VCL's message system than handling messages with the message directive. After a message is issued by Windows, it makes a couple of stops before reaching your message-handling procedure (and it might make a few more stops afterward). All along the way, you have the power to act on the message.
For posted messages, the first stop for a Windows message in VCL is the Application.Process Message() method, which houses the VCL main message loop. The next stop for a message is the handler for the Application.OnMessage event. OnMessage is called as messages are fetched from the application queue in the ProcessMessage() method. Because sent messages aren't queued, OnMessage won't be called for sent messages.
For posted messages, the DispatchMessage() API is then called internally to dispatch the message to the StdWndProc() function. For sent messages, StdWndProc() will be called directly by Win32. StdWndProc() is an assembler function that accepts the message from Windows and routes it to the object for which the message is intended.
The object method that receives the message is called MainWndProc(). Beginning with MainWndProc(), you can perform any special handling of the message your program might require. Generally, you handle a message at this point only if you don't want a message to go through VCL's normal dispatching.
After leaving the MainWndProc() method, the message is routed to the object's WndProc() method and then on to the dispatch mechanism. The dispatch mechanism, found in the object's Dispatch() method, routes the message to any specific message-handling procedure that you've defined or that already exists within VCL.
Then the message finally reaches your message-specific handling procedure. After flowing through your handler and the inherited handlers you might have invoked using the inherited keyword, the message goes to the object's DefaultHandler() method. DefaultHandler() performs any final message processing and then passes the message to the Windows DefWindowProc() function or other default window procedure (such as DefMDIProc) for any Windows default processing. Figure 3.2 shows VCL's message-processing mechanism.
){kind=link}
NOTE
You should always call inherited when handling messages unless you're absolutely certain you want to prevent normal message processing.
TIP
Because all unhandled messages flow to DefaultHandler(), that's usually the best place to handle interapplication messages in which the values were obtained by way of the RegisterWindowMessage() procedure.
Figure 3.2 VCL's message system.
To better understand VCL's message system, create a small program that can handle a message at the Application.OnMessage, WndProc(), message procedure, or DefaultHandler() stage. This project is called CatchIt; its main form is shown in Figure 3.3.
){kind=link}
Figure 3.3 The main form of the CatchIt message example.
The OnClick event handlers for PostMessButton and SendMessButton are shown in the following code. The former uses PostMessage() to post a user-defined message to the form; the latter uses SendMessage() to send a user-defined message to the form. To differentiate between post and send, note that the value 1 is passed in the wParam of PostMessage() and that the value 0 (zero) is passed for SendMessage(). Here's the code:
procedure TMainForm.PostMessButtonClick(Sender: TObject);
{ posts message to form }
begin
PostMessage(Handle, SX_MYMESSAGE, 1, 0);
end;
procedure TMainForm.SendMessButtonClick(Sender: TObject);
{ sends message to form }
begin
SendMessage(Handle, SX_MYMESSAGE, 0, 0); // send message to form
end;
This application provides the user with the opportunity to "eat" the message in the OnMessage handler, WndProc() method, message-handling method, or DefaultHandler() method (that is, to not trigger the inherited behavior and to therefore stop the message from fully circulating through VCL's message-handling system). Listing 3.2 shows the completed source code for the main unit of this project, thus demonstrating the flow of messages in a Delphi application.
Listing 3.2 The Source Code for CIMain.PAS
unit CIMain;
interface
uses
SysUtils, WinTypes, WinProcs, Messages, Classes, Graphics, Controls,
Forms, Dialogs, StdCtrls, ExtCtrls, Menus;
const
SX_MYMESSAGE = WM_USER; // User-defined message value
MessString = '%s message now in %s.'; // String to alert user
type
TMainForm = class(TForm)
GroupBox1: TGroupBox;
PostMessButton: TButton;
WndProcCB: TCheckBox;
MessProcCB: TCheckBox;
DefHandCB: TCheckBox;
SendMessButton: TButton;
AppMsgCB: TCheckBox;
EatMsgCB: TCheckBox;
EatMsgGB: TGroupBox;
OnMsgRB: TRadioButton;
WndProcRB: TRadioButton;
MsgProcRB: TRadioButton;
DefHandlerRB: TRadioButton;
procedure PostMessButtonClick(Sender: TObject);
procedure SendMessButtonClick(Sender: TObject);
procedure EatMsgCBClick(Sender: TObject);
procedure FormCreate(Sender: TObject);
procedure AppMsgCBClick(Sender: TObject);
private
{ Handles messages at Application level }
procedure OnAppMessage(var Msg: TMsg; var Handled: Boolean);
{ Handles messages at WndProc level }
procedure WndProc(var Msg: TMessage); override;
{ Handles message after dispatch }
procedure SXMyMessage(var Msg: TMessage); message SX_MYMESSAGE;
{ Default message handler }
procedure DefaultHandler(var Msg); override;
end;
var
MainForm: TMainForm;
implementation
{$R *.DFM}
const
// strings which will indicate whether a message is sent or posted
SendPostStrings: array[0..1] of String = ('Sent', 'Posted');
procedure TMainForm.FormCreate(Sender: TObject);
{ OnCreate handler for main form }
begin
// set OnMessage to my OnAppMessage method
Application.OnMessage := OnAppMessage;
// use the Tag property of checkboxes to store a reference to their
// associated radio buttons
AppMsgCB.Tag := Longint(OnMsgRB);
WndProcCB.Tag := Longint(WndProcRB);
MessProcCB.Tag := Longint(MsgProcRB);
DefHandCB.Tag := Longint(DefHandlerRB);
// use the Tag property of radio buttons to store a reference to their
// associated checkbox
OnMsgRB.Tag := Longint(AppMsgCB);
WndProcRB.Tag := Longint(WndProcCB);
MsgProcRB.Tag := Longint(MessProcCB);
DefHandlerRB.Tag := Longint(DefHandCB);
end;
procedure TMainForm.OnAppMessage(var Msg: TMsg; var Handled: Boolean);
{ OnMessage handler for Application }
begin
// check to see if message is my user-defined message
if Msg.Message = SX_MYMESSAGE then
begin
if AppMsgCB.Checked then
begin
// Let user know about the message. Set Handled flag appropriately
ShowMessage(Format(MessString, [SendPostStrings[Msg.WParam],
'Application.OnMessage']));
Handled := OnMsgRB.Checked;
end;
end;
end;
procedure TMainForm.WndProc(var Msg: TMessage);
{ WndProc procedure of form }
var
CallInherited: Boolean;
begin
CallInherited := True; // assume we will call the inherited
if Msg.Msg = SX_MYMESSAGE then // check for our user-defined message
begin
if WndProcCB.Checked then // if WndProcCB checkbox is checked...
begin
// Let user know about the message.
ShowMessage(Format(MessString, [SendPostStrings[Msg.WParam],
'WndProc']));
// Call inherited only if we are not supposed to eat the message.
CallInherited := not WndProcRB.Checked;
end;
end;
if CallInherited then inherited WndProc(Msg);
end;
procedure TMainForm.SXMyMessage(var Msg: TMessage);
{ Message procedure for user-defined message }
var
CallInherited: Boolean;
begin
CallInherited := True; // assume we will call the inherited
if MessProcCB.Checked then // if MessProcCB checkbox is checked
begin
// Let user know about the message.
ShowMessage(Format(MessString, [SendPostStrings[Msg.WParam],
'Message Procedure']));
// Call inherited only if we are not supposed to eat the message.
CallInherited := not MsgProcRB.Checked;
end;
if CallInherited then Inherited;
end;
procedure TMainForm.DefaultHandler(var Msg);
{ Default message handler for form }
var
CallInherited: Boolean;
begin
CallInherited := True; // assume we will call the inherited
// check for our user-defined message
if TMessage(Msg).Msg = SX_MYMESSAGE then begin
if DefHandCB.Checked then // if DefHandCB checkbox is checked
begin
// Let user know about the message.
ShowMessage(Format(MessString,
[SendPostStrings[TMessage(Msg).WParam], 'DefaultHandler']));
// Call inherited only if we are not supposed to eat the message.
CallInherited := not DefHandlerRB.Checked;
end;
end;
if CallInherited then inherited DefaultHandler(Msg);
end;
procedure TMainForm.PostMessButtonClick(Sender: TObject);
{ posts message to form }
begin
PostMessage(Handle, SX_MYMESSAGE, 1, 0);
end;
procedure TMainForm.SendMessButtonClick(Sender: TObject);
{ sends message to form }
begin
SendMessage(Handle, SX_MYMESSAGE, 0, 0); // send message to form
end;
procedure TMainForm.AppMsgCBClick(Sender: TObject);
{ enables/disables proper radio button for checkbox click }
begin
if EatMsgCB.Checked then
begin
with TRadioButton((Sender as TCheckBox).Tag) do
begin
Enabled := TCheckbox(Sender).Checked;
if not Enabled then Checked := False;
end;
end;
end;
procedure TMainForm.EatMsgCBClick(Sender: TObject);
{ enables/disables radio buttons as appropriate }
var
i: Integer;
DoEnable, EatEnabled: Boolean;
begin
// get enable/disable flag
EatEnabled := EatMsgCB.Checked;
// iterate over child controls of GroupBox in order to
// enable/disable and check/uncheck radio buttons
for i := 0 to EatMsgGB.ControlCount - 1 do
with EatMsgGB.Controls[i] as TRadioButton do
begin
DoEnable := EatEnabled;
if DoEnable then DoEnable := TCheckbox(Tag).Checked;
if not DoEnable then Checked := False;
Enabled := DoEnable;
end;
end;
end.
CAUTION
Although it's fine to use just the inherited keyword to send the message to an inherited handler in message-handler procedures, this technique doesn't work with WndProc() or DefaultHandler(). With these procedures, you must also provide the name of the inherited procedure or function, as in this example:
inherited WndProc(Msg);
You might have noticed that the DefaultHandler() procedure is somewhat unusual in that it takes one untyped var parameter. That's because DefaultHandler() assumes that the first word in the parameter is the message number; it isn't concerned with the rest of the information being passed. Because of this, you typecast the parameter as a TMessage so that you can access the message parameters.