be able to do serious work in BCB without understanding them.

Subjects covered in this chapter include

• Using the mouse and the keyboard

  　

• Responding directly to Windows messages such as WM_KEYDOWN or WM_MOUSEMOVE

  　

• Custom event structures such as TWMMouse or TMessage

  　

• Menus and menu IDs

  　

• Setting up a WndProc in a VCL application

  　

• Responding to WM_COMMAND messages

This chapter is not designed to be difficult, but rather to hit the highlights of each of these subjects so you can understand how to use events in your own programs. By the time you are through with this chapter, you should have a thorough understanding of the BCB delegation model and will know how to use events in your own program. Additional material on events is included in the chapters that cover creating components.

Events: The BCB Delegation Model

The two central ideas behind the type of RAD programming of which BCB partakes are components and delegation. Components are treated at length in Part IV of this book, called "Creating Components." This is where I will talk about delegation.

Delegation is an alternative to inheritance. It's a trick to allow you to receive the same benefits as inheritance but with less work.

Delegation is not entirely original with RAD programming; however, it is taken much further in this paradigm than elsewhere. A part of classic windows programming that supports delegation is the way you handle standard WM_COMMAND messages.

Think for a moment about standard Windows programming as it appeared before RAD rewrote the book on Windows programming. I'm talking the Windows programming of Petzold, or of my Teach Yourself Windows 95 Programming in 21 Days (Sams Publishing) book. Suppose that in a standard Windows program you have a button that responds to a particular event, say a message click. You usually handled that click inside the WM_COMMAND section of the window procedure (WndProc). Windows was delegating the event from the button to your WM_COMMAND handler. In other words, Windows did not force you to subclass the button class in order to respond to clicks on a button.

This is the central idea behind the delegation model in BCB. In C++Builder, if you drop a button on a form, you can set up an OnClick event handler to handle clicks on the button. The great advantage this system has over the standard Windows model is ease of use. BCB will create the message handler for you, asking that you write only the code that responds to the event. Specifically, it fills in the class definition with a declaration for your event in the header:

class TForm1 : public TForm

And it creates the even handler itself in your CPP file:

void __fastcall TForm1::Button1Click(TObject *Sender)

This is what is meant by the delegation model in BCB. What is radical about the VCL's use of the delegation model is that it appears everywhere. All sorts of components support the model and enable you to use it to do all sorts of things that required subclassing in standard Windows programming and in OWL or MFC.

One of the primary goals of the delegation model is to allow the main form in your application to handle code that you would have had to use inheritance to handle in OWL or MFC. In the inheritance model you had to override a constructor to change the way an object was initialized. In BCB, you just respond to an OnCreate event. If you want to modify the things a user can type into an edit control, you don't have to subclass the control; instead, you just respond to OnKeyDown events.

Delegation is easier than inheritance. It enables neophytes who don't understand inheritance a way to get up to speed quickly. More importantly, it enables programmers to get their work done quickly without a lot of repetitive typing.

Of course, if you want to use inheritance, it is available. In fact, inheritance is used all the time in BCB. The point is not to eliminate a powerful technique like inheritance, but to give you an alternative to use in the vast majority of cases where inheritance is overkill.

The Delegation Model and Contract-Free Programming

The delegation model supports something called contract-free programming. In some semiliterate circles this has also been known as "contractless" programming.

The idea behind contract-free programming is that there is no contract between the developer of a component and the user of a component as to what can and can't be done inside an event handler.

A classic example of a contract-bound program is found in Windows when you handle WM_KILLFOCUS message. There are some things you can and cannot do in response to this message. For example, if you change the focus during your response to this message, you can crash Windows. There is a contract between you and Windows not to change the focus while responding to this message. Learning all the things you can and cannot do in response to a message is a long, error-prone, and frustrating process.

BCB supports contract-free programming, which means you can do whatever you want while responding to an event. BCB is religious in pursuit of this goal. In my code, I strive to achieve this same goal, though I admit that I have been known to cheat. When I do so, however, I severely limit the usability of my components.

The Basics of the Delegation Model

Event-oriented code is one of the central tenets of Windows programming. Some rapid- application development environments attempt to hide users from this feature altogether, as if it were something so complicated that most programmers couldn't understand it. The truth is that event-oriented programming is not, in itself, particularly complex. However, some features of the way it is implemented in Windows can be confusing under certain circumstances.

BCB gives you full access to the event-oriented substructure that provides Windows with a high degree of power and flexibility. At the same time, it simplifies and clarifies the way a programmer handles those events. The end result is a system that gives you complete access to the power of Windows while simultaneously protecting you from unnecessary complexity.

These next few sections cover the following topics:

• Event-oriented programming basics

  　

• Responding to mouse events or key events

  　

• Accessing the information passed in events

  　

• The basics of sets, which are used frequently in BCB event handlers

  　

• Circumventing BCB message handling tools and directly capturing messages

  　

• Creating WM_COMMAND handlers and finding the IDs of the components used in a program

To be really good at programming Windows, you need to be able to look at these subjects from both the perspective of a RAD programmer and of a Windows API programmer. That is, you need to know the VCL inside out, and you need to know the Windows API inside out. This chapter concentrates on the VCL side of that equation, whereas the other side is featured in books such as Teach Yourself Windows 95 Programming in 21 Days (Sams Publishing) and Programming Windows (Microsoft Press). Put both perspectives together and you can go on to create your own VCL components or you can design elegant, well-structured Windows programs.

Before starting, let me reiterate that BCB hides much of the complexity of Windows programming. However, the developers did not want to prevent programmers from accessing any portion of the Windows API. By the time you finish reading this section of the chapter, you should be able to see that BCB gives you access to the full range of power provided by an event- oriented system.

BCB Events

BCB makes it easy to handle keyboard and mouse events. Suppose, for instance, you wanted to capture left mouse clicks in the main form of your program. Here's how to get started. Create a new project and name it EVENTS1.MAK.

In the Object Inspector for the main form, choose the Events Page and double-click the area to the right of the OnClick property. Create the following function:

void __fastcall TForm1::FormClick(TObject *Sender)

This code tells Windows that a dialog box should appear every time the user clicks the left mouse button in the form. The dialog box is shown in Figure 4.1.

FIGURE 4.1. The dialog box displayed by the EVENTS1 program when you click the left mouse button inside the main form.

The previous code presents one of the simplest possible cases of responding to an event in a BCB program. It is so simple, in fact, that many programmers write this kind of code without ever understanding that they are writing event-oriented code. In this case, BCB programmers get the event secondhand, because VCL massages the event before passing it on to the main form. Nonetheless, this is real event-oriented programming, albeit in a very simplified manifestation.

As you saw back in the section on the Windows API, the operating environment notifies you not only of the event, but of several related bits of information. For instance, when a mouse- down event is generated, a program is informed about where the event occurred and which button generated the event. If you want to get access to this kind of relatively detailed information, you should turn to the Events Page for the form and create an OnMouseDown handler:

void __fastcall TForm1::FormMouseDown(TObject *Sender, TMouseButton Button,

This method writes text to the form every time the user clicks the right mouse button. It sets the brush to bsClear style to make the background of text

transparent.

To test this method, run the program and click the right mouse button in several different locations in the form. You'll see that each spot you click is marked, as shown in Figure 4.2.

FIGURE 4.2. When you click the right mouse button in the form of the EVENTS1 program, the location of the event is recorded.

The Canvas->TextOut function prints text to the screen at the location specified by the variables X and Y. Both of these variables are supplied to you by BCB, which received them in turn from the operating system. The X variable tells you the column in which the mouse was clicked, and the Y variable tells you the row.

As you can see, BCB makes it simple for you to respond to events. Furthermore, not only mouse events are easy to handle. You can respond to keypresses in a similar manner. For instance, if you create a method for the OnKeyDown property on the Events Page for the form, you can show the user which key was pressed on the keyboard whenever the EVENTS1 program has the focus:

void __fastcall TForm1::FormKeyDown(TObject *Sender, WORD &Key,

In the preceding code, the MessageDlg function will pop up the ASCII value associated with a keystroke. In other words, BCB and the operating system both pass you not an actual letter like A, B, or C, but the number associated with the key you pressed. On PCs, the letter A is associated with the number 65. It wouldn't be appropriate for BCB to perform this translation for you automatically, because some keys, such as the F1 or Enter key, have no letter associated with them. Later in this chapter you learn how to use OnKeyDown events to respond sensibly to keypresses on special keys such as F1, Shift, or Caps Lock.

Besides OnKeyDown events, BCB also lets you respond to keyboard activity through the OnKeyPress event:

void __fastcall TForm1::FormKeyPress(TObject *Sender, char &Key)

You can see that this event is similar to an OnKeyDown event. The difference is that the Key variable passed to OnKeyPress events is already translated into a char. However, OnKeyPress events work only for the alphanumeric keys and are not called when special keys are pressed. In short, the OnKeyPress event is the same as a WM_CHAR event.

The code for the EVENTS1 program is shown in Listing 4.1. Get the program up and running and take whatever time is necessary to be sure it all makes sense to you. There is no point in trying to be a Windows programmer if you don't understand events.

Listing 4.1. The main form for the

EVENTS1 program.

///////////////////////////////////////

After this introduction to event-oriented programming, it's time to step back and see some of the theory behind the code. After explaining something of how the system works, this chapter goes on to give examples of how to take full advantage of Windows event-oriented code base.

Understanding Events

Event-oriented programming isn't unique to Windows, nor is it a chore that can be handled only by an operating system. For instance, any DOS program could be based around a simple loop that keeps running the entire time the program is in memory. Here is a hypothetical example of how such code might look:

do

This code represents a typical event-oriented loop. A simple do..while statement checks for keyboard and mouse events and then calls HandleEvents to give the program a chance to respond to the events that are generated by the user or the operating system.

The variable called Events might be a record with a fairly simple structure:

struct TEvent {

X and Y give the current location of the cursor, and Key contains the value of the top event in the key buffer. The TButton type might have a declaration that looks like this:

enum TButton {ButtonLeft, ButtonRight};

These structures permit you to track where the mouse is, what state its buttons are in, and what keys the user has pressed. Admittedly, this is a simple type of event structure, but the principles involved mirror what is going on inside Windows or inside other event-oriented systems such as Turbo Vision. If the program being written was an editor, pseudo-code for the HandleEvent for the program might look like this:

void HandleEvent(TEvent: Events)

Given the preceding code, the program would go to location X,Y and write the letter most recently pressed by the user. If the Enter key was pressed, a carriage return would be written to the screen. A press on the Esc key would cause the program to terminate. All other keypresses would be ignored.

Code like this can be very powerful, particularly if you're writing a program that requires animation. For instance, if you need to move a series of bitmaps across the screen, you want to move the bitmap a few pixels and then check to see whether the user has pressed a button or hit a keystroke. If an event has occurred, you want to handle it. If nothing occurred, you want to continue moving the bitmap.

I hope the short code samples shown here give you some feeling for the way event-oriented systems work. The only piece that's missing is an understanding of why Windows is event- oriented.

Microsoft made Windows event-oriented in part because multiple programs run under the environment at the same time. In multitasking systems, the operating system needs to know whether the user has clicked in a program or whether the click was in the desktop window. If the mouse click occurred in a window that was partially hidden behind another window, it is up to the operating system to recognize the event and bring that window to the foreground. Clearly, it wouldn't be appropriate for the window itself to have to be in charge of that task. To ask that much would place an impossible burden on the programmer who created the window. As a result, it's best for the operating system to handle all the keystrokes and mouse clicks, and to then pass them on to the various programs in the form of events. Any other system would force every programmer to handle all the events that occurred when his or her program had the focus, and to manipulate the entire operating system in response to certain mouse events or keystrokes, such as Alt+Tab.

In short, Windows programmers almost never directly monitor the hardware or hardware interrupts. Instead, the operating system handles that task. It passes all external events on to individual programs in the form of messages. In a typical event-oriented

system, the operating system continually polls the hardware in a loop and then sends each event off to its programs in the form of some kind of event structure or event variables. This is the same kind of activity you saw in the brief code snippets shown earlier.

You have seen that Windows handles mouse and keyboard events, and passes them on to the appropriate window. The message that is generated in these cases gets sent to the default window function, which, as you know, is called DefWindowProc. DefWindowProc is analogous to the HandleEvent function shown earlier.

The important point to understand is that Windows messages contain the information that drives the entire operating environment. Almost everything that happens inside Windows is a message; if you really want to tap into the power of BCB, you need to understand how these messages work.

One of the tricky parts of Windows event-oriented programming is extracting information

from the WPARAM and LPARAM variables passed to the window function. In most cases, BCB frees you from the necessity of performing this task. For instance, if you create an event for the OnMouseDown property, BCB directly tells you the X value and Y value where the event occurred. As a programmer, you don't have to struggle to get the event and its associated values. As you will see in the next section, everything about the event is shown to you in a simple and straightforward manner.

　

---

NOTE: WPARAM and LPARAM are the types of the parameters passed to a standard WndProc as is declared in WinUser.h:

　

typedef LRESULT (CALLBACK* WNDPROC)(HWND, UINT, WPARAM, LPARAM);

　

These variables are usually given names such as wParam and lParam or WParam and LParam:

WndProc(HWND hWnd, UINT Message, WPARAM wParam, LPARAM lParam);

　

You will find that I sometimes refer to these parameters by type in all caps, and sometimes as variable identifiers with mixed caps and small letters. In all cases, I am referring to the same variables passed to the user from the system. Even in the discussion of the TMessage type, which occurs later in the chapter, I am still referring to these same parameters, only in a slightly different context. Specifically, TMessage is a VCL type that contains exact copies of these parameters. The X and Y parameters passed to an OnMouseDown event are not exact copies of WPARAM and LPARAM, but variables designed to display information originally contained in WPARAM or LPARAM after they have been parsed by the VCL.

---

　

Using Sets to Track Messages

Rather than ask you to parse the LPARAM and WPARAM parameters, BCB performs this chore for you and then passes the information on in the form of parameters:

void __fastcall TForm1::FormMouseDown(

This is by far the most convenient way for you to handle events. BCB can also give direct access to the values sent to you by the operating system. That is, you can handle WPARAM and LPARAM directly if you want. After you have studied the EVENTS2 program and learned more about sets, I'll show you exactly how to get at that raw data.

Take a moment to consider the Shift parameter shown in the FormMouseDown header. Shift is declared to be of type TShiftState:

enum Classes_1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

TShiftState is a set, that is, it's an instance of the Set template class from SYSDEFS.H. To find out whether a particular element is a member of the set passed to you by BCB, you can perform simple tests using the Contains method:

ShiftKey->Checked = Shift.Contains(ssShift);

This code asks whether the element ssRight is in the set passed to you via the Shift variable. If it is, the code sets the state of a TCheckBox component.

Here is how you can declare a set at runtime:

TShiftState LeftShift;

Given this set, the Contains operator returns True if you ask about ssLeft or ssShift.

Besides the important Contains method, there are three key operators you can use with the Set class:

+ Union

All three of these operators return a set, whereas Contains returns a Boolean value. The SETSEXP program, shown in Listing 4.2, shows how to work with these key elements of the Set template class.

Listing 4.2. The SETEXP program shows how to use operators to track the members of sets such as TShiftState.

///////////////////////////////////////

The SETEXP program shows how you can read and manipulate sets. In particular, you work with sets of type TShiftState. When you are finished studying the program, you will have all the knowledge you need to work with BCB sets.

The main form for the SETEXP program consists of four checkboxes, two panels, four labels, and three bitbtns, as shown in Figure 4.3. The four checkboxes are placed on top of the first panel, and the fourth label is placed on the top of the second panel.

FIGURE 4.3. The SETEXP program's main form enables you to manipulate variables of type TShiftState.

SETEXP tells you whether the Shift or Ctrl keys are pressed when the mouse is clicked, and it tells you whether the user pressed the right or left mouse button. The code also shows how to use the Intersection, Union, and Difference operators.

The key method in the SETEXP program looks at a variable of type TShiftState and displays its contents to the user through the program's radio buttons:

void TForm1::CheckState(TShiftState Shift)

This code takes advantage of the fact that Contains returns a Boolean variable, and the Checked property of a radio button is also declared to be of type Boolean. As a result, you can test to see whether a particular element is part of the Shift set. If it is, you can easily set the Checked state of a radio button to record the result. For example, in the preceding code, if ssShift is part of the current set, the Shift Key radio button is checked.

Two different routines pass variables of type TShiftState to the CheckState method. The first routine is called whenever the user clicks in the panel at the bottom of the program or the label that rests on the panel:

void __fastcall TForm1::Label4MouseDown(TObject *Sender, TMouseButton Button,

This code passes the Shift variable on to CheckState, which displays the contents of the variable to the user. For instance, if the Shift key is being held down and the right mouse button is pressed, Label4MouseDown is called. Label4MouseDown then passes the Shift variable to CheckState, and CheckState causes the ShiftKey and RightButton controls to be checked. The other two radio buttons are left unchecked.

There are three bitbtns on the right side of the main form. They are labeled Union, Intersection, and Difference. Clicking any of these buttons demonstrates one of the non-Boolean set operators. All three buttons have their OnClick event set to the following function:

void __fastcall TForm1::UnionClick(TObject *Sender)

The UnionClick method declares three variables of type TShiftState. Two of these variables are used to create sets that are used by the rest of the SetBtnClick method:

LeftShift << ssLeft << ssShift;

The first line assigns the LeftShift variable to a set that contains the values ssLeft and ssShift. The next line assigns the LeftCtrl variable to a set that contains ssLeft and ssCtrl. The rest of this method enables the user to see the union, intersection, and difference of these two sets.

The switch statement in the middle of the SetBtnClick method detects which of the three bitbtns the user clicked. This is the old, time-honored technique featuring the use of an enumerated type and the assignment of zero-based ordinal values to the Tag field of each button.

If the user clicks the Union button, the FinalSet variable is set to the union of the LeftShift and LeftCtrl variables:

FinalSet = LeftShift + LeftCtrl;

A click on the Intersection button executes the following code:

FinalSet = LeftShift * LeftCtrl;

The difference of the sets is calculated if the user clicks the Difference button:

FinalSet = LeftShift - LeftCtrl;

After the switch statement ensures the selection of the proper operator, the FinalSet value is passed to CheckState and its contents are displayed to the user. For instance, if the user clicks the Union button, the LeftButton, ShiftKey, and ControlKey radio buttons are all checked. The Intersection button causes the LeftKey to be checked, and the Difference button causes the ShiftKey to be checked. Here is another way of looking at the work accomplished by these operators:

[ssLeft, ssShift] + [ssLeft, ssCtrl] = [ssLeft, ssShift, ssCtrl];

To help the user understand exactly what is happening, the current set operation is displayed at the top of the form. For instance, if the user clicks the Union button, the following expression is shown to the user:

LeftShift + LeftCtrl

Throughout a run of the program, the words LeftShift and LeftCtrl are displayed to the user in a pair of TLabels. A third label displays +, -, or *, depending on the current state of the program:

Label2->Caption = Operators[dynamic_cast<TBitBtn *>(Sender)->Tag];

In this code, Operators is an array of three strings that contains the operators that return a set:

AnsiString Operators[3] = {"+", "*", "-"};

The SETEXP program gives you enough information that you should be able to work

with the sets that are passed to BCB event handlers. The code shown here defines the way sets are usually handled in all BCB programs. However, you can actually directly manipulate the raw data that represents a BCB set. Techniques for performing these manipulations are shown in the GetShift method, which is part of the program examined in the next section of this chapter. You can also review the information on sets in Chapter 3.

Tracking the Mouse and Keyboard

You now know enough to begin an in-depth study of the main event handlers used by BCB forms and controls. The EVENTS2 program, shown in Listings 4.3 through 4.5, enables you to trace the occurrence of all the keyboard or mouse interrupts generated during the run of a program.

Listing 4.3. The EVENTS2 header and main form provide a detailed look at how to track events.

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

Listing 4.4. The EVENTS2 main form provides a detailed look at how to track events.

///////////////////////////////////////

Listing 4.5. The VKeys unit is used by the EVENTS2 program.

///////////////////////////////////////

EVENTS2 shows how to extract the full content of a message sent to you by BCB. The main form for the program (shown in Figure 4.4) provides information on a wide range of mouse and keyboard-generated events.

FIGURE 4.4. The EVENTS2 program tracks key Windows events as they occur.

To use the program, simply compile and run it. Click the mouse in random locations and strike any of the keys on the keyboard. Just rattle away; you won't do any harm unless you press Ctrl+Alt+Del. Every time you move the mouse, click the mouse or strike a key; the exact nature of the event that occurred is shown in the main form of the program. For instance, if you move the mouse, its current location is shown on the form. If you press the F1 key while the Ctrl key is pressed, those keys' values are displayed on the form.

If you don't have the MyMouseMove function defined, the FormMouseMove event handler in the EVENTS2 window tracks the current location of the mouse and the state of its buttons. It does this by responding to OnMouseMove events:

void __fastcall TForm1::FormMouseMove(TObject *Sender, TShiftState Shift, int X,

The method for tracking the X and Y values is fairly intuitive.

X stands for the current column, and Y stands for the current row, with columns and rows measured in pixels. Before these values can be shown to the user, they need to be translated into strings by the IntToStr function.

Nothing could be simpler than the techniques used to record the current location of the mouse.

The technique for recording the current shift state, however, is a bit more complex. As you saw earlier, the elements of this set track all the possible states of the Shift, Alt, and Ctrl keys, as well as the mouse buttons.

The Set class makes it a simple matter to create a function that will find all the currently selected elements of a variable of type TShiftState:

AnsiString GetShift(TShiftState State)

The preceding code takes advantage of the following constant array:

AnsiString ShiftArray[8] = {"ssShift", "ssAlt", "ssCtrl", "ssLeft",

More specifically, the code checks to see whether the first possible element of the set is active, and if it is, "ssShift" is added to the string returned by the function. If the next element in the enumerated type underlying the set is present, the string "ssAlt" is added to the string returned by the function, and so on. As you move through the elements in the underlying enumerated type, you get a picture of the current state of the mouse and keyboard. For instance, if the Shift and Ctrl keys are pressed, as well as the right mouse button, the string returned by the function looks like this:

ssShift ssCtrl ssRight

Trapping Virtual Keys

When keys are pressed in a Windows program, two different messages can be sent to your program. One message is called WM_KEYDOWN, and it is sent whenever any key on the keyboard is pressed. The second message is called WM_CHAR, and it is sent when one of the alphanumeric keys is pressed. In other words, if you press the A key, you get both a WM_KEYDOW and a WM_CHAR message. If you press the F1 key, only the WM_KEYDOWN message is sent.

OnKeyPress event handlers correspond to WM_CHAR messages, and OnKeyDown events correspond to WM_KEYDOWN events. That's why OnKeyPress handlers are passed a Key variable that is of type char, and OnKeyDown handlers are passed a Key variable that is of type WORD.

When you get a WM_KEYDOWN message, you need to have some way of translating that message into a meaningful value. To help with this chore, Windows declares a set of virtual key constants that all start with vk. For example, if you press the F1 key, the Key variable passed to an OnKeyDown event is set to VK_F1, in which the letters vk stand for virtual key. The virtual key codes are found in the WINDOWS unit and also in the online help under Virtual Key Codes.

You can test to see which virtual key has been pressed by writing code that looks like this:

if (Key == VK_CANCEL)

This code simply tests to see whether a particular key has been pressed. If it has, the code calls the DoSomething function.

To help you understand virtual keys, the GetKey method from the VKEYS unit returns a string stating exactly what key has been pressed:

AnsiString GetKey(WORD K)

This function is really just a giant case statement that checks to see whether the Key variable is equal to any of the virtual keys. If it is not, the code assumes that it must be one of the standard keys between A and Z. (See the else clause in the code to see how these standard keys are handled.)

As explained in the last paragraph, the virtual key codes do not cover normal letters such as A, B, and C. In other words, there is no value VK_A or VK_B. To test for these letters, just use the standard ASCII values. In other words, test whether Key is equal to 65, or whether char(key) = `A'. The point here is that these letters already have key codes. That is, the key codes for these letters are the literal values A, B, C, and so on. Because these are perfectly serviceable values, there is no need to create virtual key codes for the standard letters of the alphabet, or for numbers.

To see the value as a number, make the default section of the code look like this:

S = K;

Then if you press the A key, you get back 65. If you want to see the letter `A' instead, write the following:

S = char(K);

You probably won't have much use for the GetKey routine in a standard BCB program. However, it is useful when you are trying to understand virtual keys and the OnKeyDown event. As a result, I have included it in this program.

Handling Events Directly

If you look at the bottom of the EVENTS2 form, you see that there is a special event that tracks the position of the mouse. The EVENTS2 program tracks the mouse movements in two different ways because I wanted to show you that you can get information about the mouse either by responding to OnMouseMove events or by directly tracking WM_MOUSEMOVE messages.

Here is how you declare a function that is going to directly capture a message:

class TForm1 : public TForm

The declaration shown here tells BCB that you want to respond directly when the operating system informs your program that the mouse has moved. In other words, you don't want the BCB VCL to trap the message first and then pass it on to you in an

OnMouseMove event. Instead, you just want the message sent straight to you by the operating system, as if you were working with one of the Windows API programs shown earlier in the book. In short, you're telling the VCL: "Yes, I know you

can make this task very simple and can automate nearly the entire process by using visual tools. That's nice of you, but right now I want to get the real event itself. I have some reason of my own for wanting to get very close to the metal. As a result, I'm going to grab the message before you ever get a chance to look at it!"

Here's the code for the MyMouseMove function:

void TForm1::MyMouseMove(TWMMouse &Message)

You can see that the code begins by calling the Dispatch method inherited from TObject. If you didn't make this call, the program would still run, but the OnMouseMove event would never be sent to the FormMouseMove function. It isn't an error if you don't pass the message back to BCB. You can either keep the message for yourself or pass it on, as you prefer.

If you omit the call to Dispatch from the MySpecialMouse function, the FormMouseMove method in the EVENTS2 program is no longer called. In other words, you are directly trapping WM_MOUSEMOVE messages and not passing them on to the VCL. As a result, the VCL does not know that the event occurred, and FormMouseMove is not called.

The explanation in the last paragraph might not be easy to grasp unless you actually experiment with the EVENTS2 program. You should run the program once with the default version of the MyMouseMove method, and once with the call to Inherited commented out:

void TForm1::MyMouseMove(TWMMouse &Message)

Notice that when you run the program this way, the OnMouseMove message at the top of the form is left blank.

If you look at the header for the MyMouseMove function, you can see that

it is passed a parameter of type TWMMouse. As you recall, the TWMMouse record, found in MESSAGES.PAS, looks like this:

struct TWMMouse

If you break out both of the options shown in this variant record, you can further

simplify this record by writing

struct TWMMouse

or

struct TWMMouse

For most users, one of these two views will be the most useful way to picture the record.

The same information is present in a TWMMouse record that you would find if you responded to an OnMouseMove or OnMouseDown event. If appropriate, you can find out the row and column where the mouse is located, what key is pressed, and what state the Shift, Alt, and Ctrl keys are in. To pursue this matter further, you should look up WM_MOUSEMOVE and WM_MOUSEDOWN messages in the online help.

TWMMouse plays the same role in a BCB program that message crackers from WINDOWSX.H play in a C++ program. In other words, they automatically break out the values passed in lParam or wParam parameters of the WndProc. However, if you want, you can pass a variable of type TMessage as the parameter sent to the WM_MOUSEMOVE message handler.

Because TMessage and TWMMouse are both the same size, BCB doesn't care which one you use when trapping WM_MOUSEMOVE events. It's up to you to decide how you want to crack the wParam and lParam parameters passed to the WndProc.

In this section, you have learned something about directly handling Windows messages. When you write code that captures messages directly, you are in a sense reverting back to the more complicated model of programming found in Borland C++ 5.x. However, there are times when it is helpful to get close to the machine; BCB lets you get there if that is what you need to do.

Menu IDs, Handling WM_COMMAND, Finding TForms WndProc

In standard Windows programming, as it was conducted before the appearance of visual tools, one of the most important messages was WM_COMMAND. This message

was sent to a program every time the user selected a menu item or a button, or clicked almost any other control that is part of the current program. Furthermore, each of the buttons, menu items, and other controls in a program had a special ID, which

was assigned by the programmer. This ID was passed to WM_COMMAND handlers in the wParam variable.

BCB handles WM_COMMAND messages in such a way that you almost never have to think about them. For instance, you can get clicks on a button or menu by using the delegation model. Standard BCB controls still have IDs, but BCB assigns these numbers automatically, and there is no obvious way for you to learn the value of these IDs.

Despite BCB's capability to simplify this aspect of Windows programming, there are still times when you want to get down to the bare bones and start handling WM_COMMAND messages yourself. In particular, you will want to find a way to discover the ID associated with a particular command, and you will want to trap that ID inside a WM_COMMAND handler.

　

---

WARNING: If you are new to good RAD programming tools like BCB, you are likely to think you need to get hold of menu IDs a lot more often than you really need to get hold of them. When I first came to this paradigm, I was used to using menu IDs and I had a lot of tricks that were associated with them. As a result, I was determined to use them in my first RAD programs. That was a mistake, and I did nothing but waste time trying to walk down that road.

If the developers of the VCL thought you had any need at all for these ids, they would have made them readily available. The fact that they are a bit difficult to get at should tell you that it is very rare for anyone to ever need to access these items. It wouldn't have been hard to make these IDs available; there was simply no need to do it, and some good reasons to hint broadly that RAD had some better ways to do this type of programming. The obscurity of menu IDs is not a weakness of RAD; they are just a broad hint that you don't need to worry about that side of Windows programming any more.

The people who designed the VCL are very bright folks who know the Windows API in intimate, excruciating detail. Their goal was to create an easy-to-use programming environment that still gives users full access to all the features of Windows. They would never deliberately cut you off from something you needed.

Don't forget that both Delphi and BCB are built in the VCL by the same people who created the VCL in the first place. One of the reasons the VCL is so good is that it was honed by its creators during the process of creating the Delphi and BCB IDEs. If there were something wrong with the way the VCL was designed, it became apparent to the developers while they were creating the IDE, and it was fixed.

This was not a tool created cynically in a back room by a bunch of guys who looked down on their own users as second-rate programmers. They themselves were the programmers who first used their tools, so they did everything they could to build them correctly.

---

　

The MENUDEF program gives a general overview of how to handle WM_COMMAND messages. The program enables you to discover the ID used by a series of menu items

and then enables you to trap these IDs when they are sent to a WM_COMMAND handler in the form of a TMessage.wParam variable.

As a bonus, the program also shows how to use the TForm WndProc method, which lets you set up your own window function that receives all the messages sent to your form. It is extremely rare that you would ever need to override this virtual method in your own programs, but I show you how to do it just so you will understand a little more about how the VCL operates. You should be warned that this is a dangerous method to override, because it might come into existence before your controls are initialized and ready for use and might disappear after the controls have been disposed. For instance, I check for WM_CLOSE messages, and once I get one, I don't try to show you any more messages coming into the WndProc. Needless to say, you would crash your program immediately if you overrode this method and did not call its ancestor.

Figure 4.5 shows the form for the MENUDEF program. Here are the menu items that you can't see in Figure 4.5:

Caption = `File'

FIGURE 4.5. The MENUDEF program uses a TMemo, a TButton, and a TMainMenu control.

The code for the MENUDEF program is in Listings 4.6 and 4.7. You can see that it features two standard BCB event handlers, as well as a WM_COMMAND handler and the overridden WndProc virtual method.

Listing 4.6. The MENUDEF program shows how to retrieve the ID of a BCB menu item.

#ifndef MainH

Listing 4.7. The MENUDEF program uses a TMemo, a TButton, and a TMainMenu control.

///////////////////////////////////////

The MENUDEF program has two features:

• If you click the button at the bottom of the main form, the program's memo control displays a list of all the items in the menu, along with their IDs.

  　

• If you click any of the menu items, a message box appears stating the name of the menu item and its ID.

  　

Here is the code that grabs the ID of all the menu items and displays the ID along with the menu item's caption in a TMemo:

void __fastcall TForm1::MenuIDClick(TObject *Sender)

The code begins by clearing the current contents of the memo control. It then iterates through all the components on the form and finds any of them that are of type TMenuItem. The next step is to get the ID and the caption of the menu items. To get the ID, you need only reference the Command property of the TMenuItem component. The caption can be retrieved the same way, and then you can add this information to the list box.

The use of a dynamic_cast in the previous code demonstrates BCB's capability to work with Run Time Type Information (RTTI). RTTI enables you to test the type of a particular variable and respond accordingly. For instance, in this case the program simply asks whether a particular component is of type TMenuItem; if this Boolean question returns True, the program examines the component in more depth.

The remaining code in the program captures the IDs of the menu items in an array and then responds to WM_COMMAND messages generated by clicks in one of the program's menu items. As explained earlier, the code displays a message box stating that the menus are not yet functional. In the caption of the menu box, you can read the ID of the control that was clicked.

The code that captures the menu items in an array occurs in a Forms constructor:

__fastcall TForm1::TForm1(TComponent* Owner)

This code is almost identical to the MenuIDClick method, except that the IDs of the TMenuItems are stored in an array rather than being shown in a TMemo. The declaration for the array looks like this:

int MenuItemArray[100];

The declaration for the WM_COMMAND handler should be familiar to you by this time:

MESSAGE void WMCommand(TMessage &Message);

Here, the message directive tells the compiler that this is a dynamic method and the offset in the dynamic method table is established by the WM_COMMAND constant.

The WMCommand method compares the values sent in Message.wParam to the values in the MenuItemArray. If it finds a match, it displays the message box previously described.

void TForm1::WMCommand(TMessage &Message)

This code calls the Windows API MessageBox function rather than MessageDlg.

Here is the code that overrides the window function:

void __fastcall TForm1::WndProc(Messages::TMessage &Message)

The TMessage struct looks like this:

struct TMessage

This structure has all the information in it that you would get if you were inside a standard windows function. For all intents and purposes, you are inside a standard window function. (See TApplication.Create in the Pascal source, as well as the TForm object, for more information.)

At this stage I could begin a 400- or 500-page analysis of window functions, messages, and the structure of the Windows operating system. (That was pretty much what I did in Teach Yourself Windows 95 Programming in 21 Days (Sams Publishing), so there is a source for this kind of information if you want it.) However, this book is not about that kind of material, so I will leave this method hanging and let you explore it to the degree to which the subject matter calls you. Remember, however, that this method can be dangerous to handle, as it is active even when the controls on your form have not been created, and it is still active after they have been destroyed.

One final point about working with the IDs of a control: If you build the interface of your program and then don't change its menus or any other aspect of its interface, the IDs that BCB associates with each control will (at least theoretically) remain the same throughout the development of your application. This might give some people the idea of using the MenuIDClick method, shown earlier, as a temporary response to a click on one of your controls and the storing of the output to a file. Thereafter, you would hope to know the ID associated with each of your controls and could handle them in a WM_COMMAND routine. This technique is theoretically possible, but I wouldn't recommend it as part of the framework for any serious application. In short, if you have to know the ID of a particular control, I would determine it in the FormCreate method, thereby ensuring that the ID is correct for that build of your program.

Summary

In this chapter you learned how to handle events using the standard BCB delegation model. You saw that when the need arises, you can circumvent this system and handle events directly by employing message maps. You can also pass messages back to the system by calling the inherited Dispatch method. Events represent one of the most important subjects in BCB programming, and you probably shouldn't move on until you have a good idea of what's going on in the EVENTS2 program.

This chapter also explained that you can handle wParam and lParam variables directly. Furthermore, BCB gives you a way to parse the information passed

with events, so that you can place a custom record as the parameter to a message handler. For instance, if Windows conceals a set of X and Y coordinates inside the high or low words of wParam, BCB enables you to define a custom record that automatically breaks up wParam into two separate variables called X and Y. This is the same functionality that is found in the message crackers provided in WINDOWSX.H. The TWMMouse record discussed earlier is one of these records; TMessage is another. If you want, you can create your own records that parse the information associated with standard BCB events or with events that you create yourself. You are not limited to custom BCB handlers such as TMessage or TWMMouse.