This chapter is from the book
This chapter is from the book
This chapter is from the book
Handling Messages
Handling or processing a message means that your application responds in some manner to a Windows message. In a standard Windows application, message handling is performed in each window procedure. By internalizing the window procedure, however, Delphi makes it much easier to handle individual messages; instead of having one procedure that handles all messages, each message has its own procedure. Three requirements must be met for a procedure to be a message-handling procedure:
The procedure must be a method of an object.
The procedure must take one var parameter of a TMessage or other message-specific record type.
The procedure must use the message directive followed by the constant value of the message you want to process.
Here's an example of a procedure that handles WM_PAINT messages:
procedure WMPaint(var Msg: TWMPaint); message WM_PAINT;
NOTE
When naming message-handling procedures, the convention is to give them the same name as the message itself, using camel capitalization and without the underscore.
As another example, let's write a simple message-handling procedure for WM_PAINT that processes the message simply by beeping.
Start by creating a new, blank project. Then access the Code Editor window for this project and add the header for the WMPaint function to the private section of the TForm1 object:
procedure WMPaint(var Msg: TWMPaint); message WM_PAINT;
Now add the function definition to the implementation part of this unit. Remember to use the dot operator to scope this procedure as a method of TForm1. Don't use the message directive as part of the function implementation:
procedure TForm1.WMPaint(var Msg: TWMPaint); begin Beep; inherited; end;
Notice the use of the inherited keyword here. Call inherited when you want to pass the message to the ancestor object's handler. By calling inherited in this example, you pass on the message to TForm's WM_PAINT handler.
NOTE
Unlike normal calls to inherited methods, here you don't give the name of the inherited method because the name of the method is unimportant when it's dispatched. Delphi knows what method to call based on the message value used with the message directive in the class interface.
The main unit in Listing 3.1 provides a simple example of a form that processes the WM_PAINT message. Creating this project is easy: Just create a new project and add the code for the WMPaint procedure to the TForm object.
Listing 3.1 GetMess—A Message-Handling Example
unit GMMain;
interface
uses
SysUtils, Windows, Messages, Classes, Graphics, Controls,
Forms, Dialogs;
type
TForm1 = class(TForm)
private
procedure WMPaint(var Msg: TWMPaint); message WM_PAINT;
end;
var
Form1: TForm1;
implementation
{$R *.DFM}
procedure TForm1.WMPaint(var Msg: TWMPaint);
begin
MessageBeep(0);
inherited;
end;
end.
Whenever a WM_PAINT message comes down the pike, it's passed to the WMPaint procedure. The WMPaint procedure simply informs you of the WM_PAINT message by making some noise with the MessageBeep() procedure and then passes the message to the inherited handler.
MessageBeep(): The Poor Man's Debugger
While we're on the topic of beeping, now is a good time for a slight digression. The MessageBeep() procedure is one of the most straightforward and useful elements in the Win32 API. Its use is simple: Call MessageBeep(), pass a predefined constant, and Windows beeps the PC's speaker. (If you have a sound card, it plays a WAV file.) Big deal, you say? On the surface it might not seem like much, but MessageBeep() really shines as an aid in debugging your programs.
If you're looking for a quick-and-dirty way to tell whether your program is reaching a certain place in your code—without having to bother with the debugger and breakpoints—MessageBeep() is for you. Because it doesn't require a handle or some other Windows resource, you can use it practically anywhere in your code, and as a wise man once said, "MessageBeep() is for the itch you can't scratch with the debugger." If you have a sound card, you can pass MessageBeep() one of several predefined constants to have it play a wider variety of sounds—these constants are defined under MessageBeep() in the Win32 API help file.
If you're like the authors and are too lazy to type out that whole big, long function name and parameter, you can use the Beep() procedure found in the SysUtils unit. The implementation of Beep() is simply a call to MessageBeep() with the parameter 0.
Message Handling: Not Contract Free
Unlike responding to Delphi events, handling Windows messages is not "contract free." Often, when you decide to handle a message yourself, Windows expects you to perform some action when processing the message. Most of the time, VCL has much of this basic message processing built in—all you have to do is call inherited to get to it. Think of it this way: You write a message handler so that your application will do the things you expect, and you call inherited so that your application will do the additional things Windows expects.
NOTE
The contractual nature of message handling can be more than just calling the inherited handler. In message handlers, you're sometimes restricted in what you can do. For example, in a WM_KILLFOCUS message, you cannot set focus to another control without causing a crash.
To demonstrate the inherited elements, consider the program in Listing 3.1 without calling inherited in the WMPaint() method. the procedure would look like this:
procedure TForm1.WMPaint(var Msg: TWMPaint); begin MessageBeep(0); end;
This procedure never gives Windows a chance to perform basic handling of the WM_PAINT message, and the form will never paint itself. In fact, you might end up with several WM_PAINT messages stacking up in the message queue, causing the beep to continue until the queue is cleared.
Sometimes there are circumstances in which you don't want to call the inherited message handler. An example is handling the WM_SYSCOMMAND messages to prevent a window from being minimized or maximized.
Assigning Message Result Values
When you handle some Windows messages, Windows expects you to return a result value. The classic example is the WM_CTLCOLOR message. When you handle this message, Windows expects you to return a handle to a brush with which you want Windows to paint a dialog box or control. (Delphi provides a Color property for components that does this for you, so the example is just for illustration purposes.) You can return this brush handle easily with a message-handling procedure by assigning a value to the Result field of TMessage (or another message record) after calling inherited. For example, if you were handling WM_CTLCOLOR, you could return a brush handle value to Windows with the following code:
procedure TForm1.WMCtlColor(var Msg: TWMCtlColor);
var
BrushHand: hBrush;
begin
inherited;
{ Create a brush handle and place into BrushHand variable }
Msg.Result := BrushHand;
end;
The TApplication Type's OnMessage Event
Another technique for handling messages is to use TApplication's OnMessage event. When you assign a procedure to OnMessage, that procedure is called whenever a message is pulled from the queue and about to be processed. This event handler is called before Windows itself has a chance to process the message. The Application.OnMessage event handler is of TMessageEvent type and must be defined with a parameter list, as shown here:
procedure SomeObject.AppMessageHandler(var Msg: TMsg; var Handled: Boolean);
All the message parameters are passed to the OnMessage event handler in the Msg parameter. (Note that this parameter is of the Windows TMsg record type described earlier in this chapter.) The Handled field requires you to assign a Boolean value indicating whether you have handled the message.
You can create an OnMessage event handler by using a TApplicationEvents component from the Additional page of the Component Palette. Here is an example of such an event handler:
var NumMessages: Integer; procedure TForm1.ApplicationEvents1Message(var Msg: tagMSG; var Handled: Boolean); begin Inc(NumMessages); Handled := False; end;
One limitation of OnMessage is that it's executed only for messages pulled out of the queue and not for messages sent directly to the window procedures of windows in your application. Chapter 13, "Hard-Core Techniques," of Delphi 5 Developers Guide, which is on this book's CD-ROM, shows techniques for working around this limitation by hooking into the application window procedure.
TIP
OnMessage sees all messages posted to all window handles in your application. This is the busiest event in your application (thousands of messages per second), so don't do anything in an OnMessage handler that takes a lot of time because you'll slow your whole application to a crawl. Clearly, this is one place where a breakpoint would be a very bad idea.