Newton Developer Technical Information: Newton Programmer's Guide: 2.1 OS Addendum /

Chapter 4 - Keyboard Enhancements / Using the Keyboard Enhancements

Handling Command Keys

Each view in your application can have a set of key commands associated with it. You can use the functions and methods shown in Table 4-11 to work with key commands.

Table 4-11 Summary of command key methods and functions

Function/Method	Description
view:AddKeyCommand	Adds a key command to a view.
view:AddKeyCommands	Adds an array of key commands to a view.
view:BlockKeyCommand	Blocks a key command from being associated with a view.
view:ClearKeyCommands	Removes all key commands from a view.
view: RemoveKeyCommandFrame	Removes a specific key command frame from a view.
SendKeyMessage	Sends a key message as if a key command had been typed on the keyboard.
FindKeyCommand	Finds the key command that matches a command-key combination.
GatherKeyCommands	Returns an array of the command keys associated with a view.

Searching for Key Commands

If your *ViewKeyDownScript or *ViewKeyRepeatScript methods return nil, the system tests for a key command by searching for a keyCommand frame that matches the entered key(s). By default, the system searches for a keyCommand frame when the the user presses a function key, the escape key, or any key in combination with the command key. You can also force the system to search for key commands after each keystroke by setting the vAlwaysTryKeyCommands text flag in the key view.

Defining Key Commands

To define a set of key commands, you need to create an array of keyCommand frames, each of which defines an individual key command. See "The Command-Key Mapping Frame" for a full description of the keyCommand frame slots. Listing 4-2 shows an example of a key command array.

Listing 4-2 A key command array

 keyCommandArray:

   [
      {
         char: $g,
         modifiers:kCommandModifier,
         keyMessage:'DoGKeyCommand,
         name: "Do G Key",
      },
      {
         char: $b,
         modifiers:kCommandModifier,
         keyMessage:'DoBKeyCommand,
         name: "Do B Key",
      },
    ],

Each keyCommand frame specifies the keys that the user presses to invoke the command, the name to display for the command, and the message that the system sends when the command is invoked.

Adding the Key-Commands

You can use the *AddKeyCommand method of a view to add a single key-command, or you can use the *AddKeyCommands method to add an array of key-commands to the view. You typically add your key-commands during view setup. Listing 4-3 shows an example of setting up key-commands in the ViewSetupFormScript method.

Listing 4-3 Defining key-commands in the ViewSetupFormScript method

ViewSetupFormScript: func()
   begin
   :AddKeyCommands( keyCommandArray );
   end

Note that the most recently added key command for a specific key combination takes precedence. If, for example, your application defines a Cmd-F equivalent and adds it using *AddKeyCommand, and then adds another Cmd-F equivalent, the last one added will be the only one seen by the system.

Invoking the Command-Key Method

When the user presses a command-key combination, the system software sends the message associated with the command key (as defined in its keyCommand frame). The method that is invoked for the command-key message need not be implemented in the same view as is the command key.

Once the system software matches a keyCommand, the system searches the same chain (starting at the key-view and following either _parent or _nextKeyView slots) until the method has been found. The method is called with a single parameter: the current key-view. For example, if the key commands array shown in Listing 4-2 is in use and the user presses the Cmd-g key-combination, the following call is made:

 view:DoGKeyCommand(currentKeyView)

You can examine the current key-view in your implementation to decide which actions you want to take in your method implementation.

Removing Key-Commands

It is good practice to remove your key-commands when your view is closing. To do so, you can call the *ClearKeyCommands method in the ViewQuitScript method of your view. Listing 4-4 shows an example.

Listing 4-4 Removing key-commands

ViewQuitScript: func()
   begin
   :ClearKeyCommands();
   inherited:?ViewQuitScript();
   end

Note

If you do not remove key commands when your view is closing, the key commands can waste valuable heap space.