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

Chapter 4 - Keyboard Enhancements / About Keyboard Enhancements

About Command Key Handling

Each view in your application has a set of key commands associated with it. This section describes how key commands are defined and associated with each view.

To define a key command for one of your views, you need to define a keyCommand frame, as described in "The Command-Key Mapping Frame".

You specify the method associated with a command key in the keyMessage slot of the keyCommand frame. The method need not be implemented in the same view as the command key.

How Command Keys Are Found

The system software searches for command keys when the user presses one of the following keys:

• a function key
• the escape key
• any key pressed while the command key is held down

However, it is also possible to force the system to search for key commands with every keystroke, regardless of whether the command key is down. To do this, set the text flag vAlwaysTryKeyCommands in the key-view.

The following list describes how the system searches for a keyCommand frame when the user enters a potential command key:

1. The command search starts at the view that owns the caret.
2. The system looks through the key commands registered in the current view for a keyCommand that matches the pressed key.
3. If the system finds a match, the search is complete.
4. Otherwise, the system looks for a slot named _nextKeyView in the current view. This slot contains a reference to another view. If the _nextKeyView slot is present, its contents are used as the next view in which to search.
5. If the _nextKeyView slot is not found, the system moves up to the current view's parent and uses that as the next view to search. This continues until the command is found or the root view has been searched.

The search for a command key is analagous to the parent inheritance chain. You can link a slip to your base view, rather than its parent, which is normally the root view. This allows a key command defined in your base view to be available in the slip.

Key commands can be global (available regardless of the context), specific to a certain application, or specific to a slip within an application. Some commands may even be specific to a certain input field of a certain slip. In any case, each key command is associated with a certain view. Table 4-1 shows how commands are associated with views.

Table 4-1 Command definition views

Command Type	Associated view
Global commands	Root view
Application commands	Application's base view
Slip commands	Slip's base view
Field commands	Field's view

About Displaying Command-Key Combinations in Menus

To display a command-key combination for an item in a popup menu, you must define a keyMessage frame for the item.

For example, you can define a popup menu without command-key equivalents by passing an array to the PopupMenu view method. The following array creates a menu with three items:

 [


    "one",

   {icon: i, item: "two"},
   {icon: ii, mark: $-, item: "three"}
]

The second item in the above menu contains an icon and the third item contains an icon and a mark.

To create the above menu with command-key combinations, you specify keyMessage slots in the item frames. When the menu is displayed, the system software searches for a matching command key and then uses the name, character, and modifiers defined in the found keyCommand frame. For example, the menu could be defined with the following array:

 [
  "one",

   {keyMessage: _DoSomething},
   {keyMessage: _AnotherThing} 
]

The names for the second and third items in the menu array above are found in the corresponding keyCommand frames.

Note

To find a keyCommand frame that matches a menu item, the system looks for a keyCommand frame whose keyMessage slot has the same value as the keyMessage slot in the menu item frame.

If you want to display a name in the menu that is not the same as the name specified in the keyCommand frame, you can use a keyMessage slot and an item slot in the item frame. In this case, the item name is used instead of the name in the matching keyCommand frame. For example:

    {keyMessage: _DoSomething, item: "Something"},

In the above example, the name "Something" is displayed in the menu.

Note

An item defined with a keyMessage slot can also have icon and mark slots.