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

Chapter 13 - Working With Events and Commands

Overview

MacApp provides a sophisticated mechanism for receiving events and dispatching them to objects in your application. MacApp also supplies a mechanism for creating command objects to respond to events by performing an operation that can be done, undone, and redone. MacApp classes used in handling events and commands are shown in Figure 5-1 on page 99.

Although there are many kinds of events, the ones your application most often works with are mouse events, key events, menu events (which MacApp translates into command choices), and Apple events.

Which Object Should Handle an Event or Menu Command

MacApp dispatches events to event-handler objects--objects based on classes that descend from the TEventHandler class. MacApp applications use command-handler objects--objects based on the TCommandHandler class--to respond to events by posting a command. The TCommandHandler class is itself a descendant of TEventHandler. MacApp's TApplication, TDocument, TWindow, and TView classes all descend from TCommandHandler, so any class you define based on one of these classes can both handle events and post commands. In fact, applications rarely define a direct subclass of TEventHandler.

Classes that handle Apple events, either directly or in an attached script, mix in the MScriptableObject class. The TDocument, TFile, TDesignator, TWindow, and other MacApp classes already mix in MScriptable, and the TApplication class mixes in MDefaultScriptableObject. Any class you define that descends from one of these classes has access to the MScriptable methods and fields. You can also mix in MScriptable to any class you define that doesn't already use it.

In general, the objects in a MacApp application divide the responsibility for handling events as follows:

• Application object. The application object handles key-down events, although view objects that handle text or key selection also handle these events and behavior objects are used to intercept special keystrokes. The application object maps menu events into menu commands and does the same for Command-key equivalents that specify menu choices. Menu commands can be handled by any event-handler object or behavior object in its DoMenuCommand method. The application object handles a number of Apple events in its DoScriptCommand method, including certain Apple events from the Finder and the Edition Manager.
• Behavior objects. Behavior objects attached to event-handler objects are capable of handling key events, menu commands, mouse events, and Apple events. Behaviors are described in the next section.
• Document objects. A document object handles menu commands that affect the document; less commonly, a document handles key events. Documents handle File commands such as Open and Save, and Edition Manager commands such as Create Publisher and Hide/Show Borders. For document classes that descend from TMailableDocument, the DoMenuCommand method calls the DoMailMenuCommand method of the document's mixed-in MMailable class to give a letter a chance to handle certain menu commands from the Mail menu.
• Global dispatcher object. MacApp's global dispatcher object (accessed through TOSADispatcher::fgDispatcher) aids in dispatching Apple events; the events themselves are handled by the specified object. An object that handles Apple events is instantiated from a class that mixes in the MScriptableObject class and usually responds to Apple events in its DoScriptCommand method.
• Letter objects. An object based on the TLetter class (or its subclass, TFileBasedLetter) handles many Mail menu commands in its DoMailMenuCommand method.
• View objects. View objects handle mouse-down and mouse-up events. They also provide drag-and-drop support and create commands to track the cursor during user operations such as drawing. View objects handle menu commands that affect the state of the view; they sometimes handle key events as well.
• Window objects. Window objects handle update and activate events.

When you add a new function to your application, it is usually clear whether one of these classes should handle the function or whether it should be handled by some other class you have defined.

Working With Behaviors

MacApp supplies the TBehavior class and a number of subclasses to provide a mechanism for altering the behavior of event-handler objects in your application. MacApp's behavior mechanism is described in detail in "Behaviors," beginning on page 101.

Using a behavior object, you can modify an event-handling object without having to change its class definition or define a new subclass. Instead, you define a behavior class, override one or more event-handling methods, instantiate a behavior object, and attach it to the event-handler object whose behavior you wish to modify. In addition to offering great flexibility, the behavior classes you define don't carry around all the fields and methods of an event-handling class, so they tend to be simpler, smaller, and more efficient.

Behaviors can be specified through resources or they can be created and attached procedurally, allowing you to modify event-handler objects "on the fly." For code samples that demonstrate the use of behavior objects, see "Recipe--Using a Behavior Object to Implement Alphabetic Type-Ahead," beginning on page 344, and "Recipe--Using Dependencies and Behaviors to Synchronize Control Views," beginning on page 588.

The TBehavior class contains methods you can override to modify most event-handling behavior. These methods include DoCommandKeyEvent, DoEvent, DoKeyEvent, DoKeyUp, DoMenuCommand, DoMouseCommand, DoMouseUp, DoScriptCommand, DoSetCursor, DoSetupMenus, Draw, and DoToolboxEvent.

You can read more about these methods in the MacApp Class and Method Reference.