Inside Macintosh: Programmer's Guide to MacApp / Part 2 - Working With MacApp

Chapter 20 - Working With the Keyboard

Overview

When a user presses a key while your program is active, the application object receives a key-down event from the operating system. The application passes the event to the target chain, as shown in Figure 5-2 on page 104. The event is passed from object to object in the target chain until an event-handler or behavior object in the chain handles the keystroke.

If the key-down event is a Command-key combination, the application object automatically determines whether it is a keyboard equivalent for a menu command. The application doesn't check for keyboard equivalents that use other modifier keys, such as the Option or Control key.

Your application handles a menu command by overriding the DoMenuCommand method in any event-handling or behavior class, including subclasses of TApplication, TDocument, TView, TWindow, and TBehavior. (These classes already handle certain menu commands in their implementations of DoMenuCommand.) You can specify a Command-key equivalent for a menu command by adding the key equivalent to the menu definition in your resource file, as described in "Defining Menu Contents With a 'CMNU' Resource," beginning on page 303.

MacApp supplies the TTEView class and a number of command classes for working with text entry. For more information on text editing, see "Editing Text" on page 246.

Figure 20-1 shows some of the classes and methods MacApp uses to process keystrokes.

Simple Keystrokes

A simple keystroke is one that does not include a modifier key. Your application typically handles simple keystrokes by overriding the DoKeyEvent method in an event-handling or behavior class. Your implementation of DoKeyEvent handles any key event that has meaning for your application; otherwise, it calls Inherited::DoKeyEvent. This allows other classes in the object's class hierarchy to handle the event. If none does, the event is passed on to the next object in the target chain, if there is one.

Figure 20-1 Keystroke-handling classes and methods

Command-Key Combinations With Menu Command Equivalents

If a Command-key combination has a menu command equivalent, the application object calls the HandleMenuCommand method of the current target object, which in turn calls the DoMenuCommand method. For example, the Open command on the File menu has the command equivalent of Command-O. When a user types Command-O, the application object calls the HandleMenuCommand method of the current target object, passing the cOpen command constant. (Command-key processing is described in detail in "Key-Down Events," beginning on page 110.)

Command-Key Combinations With No Menu Equivalent

Your application handles a Command-key combination that is not equivalent to a menu command by overriding the DoCommandKeyEvent method in an event-handling or behavior class. Command-key combinations are often handled in a subclass of the application class. In your implementation of the DoCommandKeyEvent method, you respond to the Command-key combinations that have special meaning for your application and pass any other combinations down the target chain by calling Inherited.

Other Modifier Keys

Your application can respond to other modifier keys, including the Shift, Option, Control, and Caps Lock keys, by overriding the DoKeyEvent method in an event-handling or behavior class. The DoKeyEvent method is passed the parameter

TToolboxEvent* event

One of the fields of TToolboxEvent is

EventRecord : fEventRecord;

The EventRecord structure contains information about the Toolbox event generated by the original keystroke, including the state of the modifier keys. Your override version of DoKeyEvent can examine fEventRecord to determine whether a modifier key you are interested in was pressed. This is demonstrated in the code sample "Recipe--Handling a Keystroke Other Than a Command-Key Combination," beginning on page 480.

The chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials describes Toolbox events and the EventRecord data type.

Function Keys and Other Extended Keyboard Keys

MacApp provides built-in support for handling the function keys F1 through F4 (Undo, Cut, Copy, Paste) and the Clear key on the numeric keypad. If no other object in the target chain responds first, the application object's DoKeyEvent method maps F1 to cUndo, F2 to cCut, F3 to cCopy, F4 to cPaste, and Clear to cClear and generates a call to the HandleMenuCommand method of the current target object, which in turn calls the DoMenuCommand method, passing the command constant (as it does for Command-key combinations with menu command equivalents).

As a result, your application can respond to the function keys F1 through F4 and the Clear key by overriding DoMenuCommand in an event-handling or behavior class and by looking for the cUndo, cCut, cCopy, cPaste, or cClear command constant.

Note

The TTEView class handles the command constants cCut, cCopy, cPaste, and cClear in its DoMenuCommand method. When you use TTEView or a subclass, you may not need to supply any additional code for these commands.

Your application can also respond to function keys in the DoKeyEvent method of an event-handling or behavior class. Command constants for the function keys F1 through F15, the Esc (Escape) key, the Fwd Del (Forward Delete) key, and the Clear key are defined in the file MacAppTypes.h. In your implementation of DoKeyEvent, you compare the fKeyCode field of the passed TToolboxEvent object to any of these constants to identify special keys your application is interested in.

Scripting Note

Chapter 6, "Scripting," lists scripting issues to keep in mind while designing an application. Factoring the application (separating code that controls the user interface from code that responds to user actions, and breaking functions into discrete operations that can be implemented as separate tasks) is important in handling keystrokes, as it is for other user actions.

Suppose, for example, a user presses the F2 function key (Cut) after selecting a graphic object in a window in your application. The application object's DoKeyEvent method calls the current target object's HandleMenuCommand method, passing the value cCut. Each object in the target chain gets a chance to respond to the cCut command number in its DoMenuCommand method.

The TYourView::DoMenuCommand method handles cCut by creating a command object that knows how to perform the cut operation and send an Apple event to describe it. The DoMenuCommand method sets the command's fUseAppleEvent field to TRUE. When the command is executed, it first sends the Apple event (making the operation recordable and giving any attached script a chance to handle the command), then performs the specified cut (if no script intercepts the command).

When an Apple event describing a similar cut operation is received from a script or an outside source, it is dispatched to your view object. The view's DoScriptCommand method creates a command object of the same type as that created by the DoMenuCommand method. However, in this case it sets fUseAppleEvent to FALSE. (Actually, fUseAppleEvent defaults to FALSE, so no further work is required.) It also calls the command's Process method directly rather than post the command to the command queue. When the command is executed, it performs the specified cut operation but doesn't send an Apple event, because the command itself was created in response to an Apple event.

If you follow this implementation strategy, cutting with the F2 function key will be a scriptable, recordable operation in your application.