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

Chapter 20 - Working With the Keyboard

Recipes--The Keyboard

The recipes and sample code in this section demonstrate how to work with various kinds of keystrokes in a MacApp application.

Working With the Keyboard--A General Outline

MacApp gives event-handler objects and behavior objects in the target chain a chance to handle keystrokes. Your application normally works with keystrokes in three ways:

1. If the Command key is not held down when a key is pressed, MacApp calls the HandleKeyCommand method of the current target object, which in turn calls the DoKeyEvent method. To handle a keystroke in your application, do the following:
   • Override the DoKeyEvent method of an event-handling or behavior class.
   • Use the TToolboxEvent parameter to DoKeyEvent to determine if the key is one you wish to handle. Identify the key by examining the parameter's fCharacter field.
   • If the character is one you wish to handle, perform the desired action.
   • If the character is not one you wish to handle, call Inherited::DoKeyEvent to give other event-handler and behavior objects in the target chain a chance to handle the keystroke.

     For a detailed example, see the next section, "Recipe--Handling a Keystroke Other Than a Command-Key Combination."

2. If the keystroke is a Command-key combination and it has a menu command equivalent, MacApp calls the DoMenuCommand method of the current target object, just as if the user had selected the menu command with the mouse.

   For a detailed example, see "Recipe--Responding to a Command-Key Combination," beginning on page 481.

3. If the keystroke is a Command-key combination and it does not have a menu command equivalent, MacApp calls the HandleCommandKey method of the current target object, which in turn calls the DoCommandKeyEvent method. This call travels along the target chain until it is handled by one of the event-handler or behavior objects in the chain. To handle Command-key combinations of this type, do the following:
   • Override the DoCommandKeyEvent method of an event-handling or behavior class.
   • Use the TToolboxEvent parameter to DoCommandKeyEvent to determine whether the key is one you wish to handle. Identify the key that was pressed along with the Command key by examining the parameter's fCharacter field.
   • If the character is one you wish to handle, perform the desired action.
   • If the character is not one you wish to handle, call Inherited::DoCommandKeyEvent to give other event-handler objects and behaviors in the target chain a chance to handle the keystroke.

     For a detailed example, see "Recipe--Responding to a Command-Key Combination," beginning on page 481.

Recipe--Handling a Keystroke Other Than a Command-Key Combination

To handle a keystroke other than a Command-key combination, you perform only one step.

1. Override the DoKeyEvent method of an event-handling or behavior class.
   • If the key is one you wish to handle, perform the desired action.
   • If the key is not one you wish to handle, call Inherited to pass on the keystroke.

The sample code shown in this recipe is from the DemoDialogs application.

Override the DoKeyEvent Method of an Event-Handling or Behavior Class

The DemoDialogs sample application uses the TMonthlyDialog view class to display a window containing 12 number-entry views labeled with the months of the year. TMonthlyDialog overrides the DoKeyEvent method to set the target to the view's window whenever the user presses the Option-Tab combination.

The DoKeyEvent method uses the fCharacter field of the TToolboxEvent parameter to determine whether the Tab key was pressed and uses the IsOptionKeyPressed method to check for the Option key. If the keystroke is Option-Tab, DoKeyEvent sets the current target object to the view's window. If not, it calls Inherited to give other objects in the target chain a chance to handle the keystroke. Your application can use similar code when it needs to process a simple keystroke or a particular keystroke combination.

Note

The DemoDialogs application processes the Option-Tab key combination to demonstrate setting the target object. However, your application may want to avoid using Option-Tab because MacApp uses that combination to tab between the mailer view and the document view for documents with PowerTalk mailers.

void TMonthlyDialog::DoKeyEvent(TToolboxEvent* event) // Override.
{
   TWindow * theWindow = NULL;
   Boolean dummy;
   
   // If Option-Tab is pressed, make the view's window the current
   // target. This is for test purposes only.
   if ((event->fCharacter == chTab) && (event->IsOptionKeyPressed()))
   {
      // Get the view's window and make it the current target.
      // The return value indicates whether the window actually
      // became the target. Since we're just testing, ignore the
      // return value.
      theWindow = this->GetWindow();
      if (theWindow != NULL)
         dummy = theWindow->BecomeTarget();
   }
   else
      Inherited::DoKeyEvent(event);
}

Recipe--Responding to a Command-Key Combination

When your application receives a Command-key combination that has a menu command equivalent, MacApp calls the HandleMenuCommand method of the current target object, which in turn calls the DoMenuCommand method, passing the command constant for the menu command. Your application responds by overriding the DoMenuCommand method of an event-handling or behavior class, as described in "Recipe--Adding, Enabling, and Responding to a Menu Command," beginning on page 314.

When your application receives a Command-key combination that does not have a menu command equivalent, MacApp calls the DoCommandKeyEvent method of the current target object. To respond to the Command-key combination, you perform only one step:

1. Override the DoCommandKeyEvent method of an event-handling or behavior class.
   • Determine whether the key is one you wish to handle.
   • If so, perform the desired action.
   • If not, call Inherited to pass on the keystroke.

The sample code shown in this recipe is based on the TDialogBehavior class from the MacApp class library.

Override DoCommandKeyEvent in an Event-Handling or Behavior Class

MacApp uses the TDialogView view class to provide standard dialog-box behavior. The TDialogView class has few methods and fields--most of its behavior is supplied by an attached behavior object of type TDialogBehavior. For example, TDialogBehavior overrides the DoCommandKeyEvent method to check for the Command-period combination. When it finds this combination, it cancels the dialog; otherwise, it calls Inherited::DoCommandKeyEvent to give other behaviors and event-handler objects in the target chain a chance to handle the keystroke.

The TDialogBehavior::DoCommandKeyEvent method is shown below. It uses the fCharacter field of the TToolboxEvent parameter to determine whether the period key was pressed. If the behavior has a view and the view is enabled and the keystroke is a period and the view can be dismissed, DoCommandKeyEvent attempts to cancel the dialog box. Otherwise, it calls Inherited to give other objects in the target chain a chance to handle the keystroke.

void TDialogBehavior::DoCommandKeyEvent(TToolboxEvent* event) // Override. 
{
	// Maps Command-period to the cancel item (view).
	TView* owner = ( TView* )fOwner;

	if (owner && owner->IsEnabled() && event->fCharacter == '.'
		&& ((long)fCancelItem != (long)kNoIdentifier))
	{
		TView* cancelView = owner->FindSubView(fCancelItem);
		if (cancelView)
		{
			if (cancelView->IsEnabled())
			{
				cancelView->HandleEvent(cancelView->GetEventNumber(), owner, NULL);
			}
		}
		else
			owner->HandleEvent(mCancelKey, owner, NULL);
	}
	else
		Inherited::DoCommandKeyEvent(event);
}