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

Chapter 4 - Keyboard Enhancements / About Keyboard Enhancements

About Keystroke Handling

This section provides general information about how keystrokes are handled by the system software and how your application can intercept keystrokes, including the following techniques:

• When you need to apply custom handling to keyboard events, you can intercept those events, including the key-down, key-up, and key-repeat events.
• Sometimes the system groups multiple keystrokes together into keystrings to improve performance. You can also intercept these strings, which are used to improve user response time. Note that rapid successions of keystrokes in all views are grouped together into strings unless you set the vSingleKeystrokes text flag in the view.
  
  For example, if the user quickly types the word "something" into a long paragraph view, each change to the view's contents results in an insertion and redisplay. Grouping the keys into a single insertion and redisplay operation produces a much faster response than responding individually to the entry of each character.
• You can define keyboard commands (command keys) that the system will match and execute where appropriate.

Keystroke Event Sequencing

This section describes the sequence of events that is generated when the user presses, holds down, and then releases a key on the keyboard.

Key-down Events

The following list describes the processing sequence when the user presses down on a keyboard key and a key-down event is generated:

1. If the vSingleKeystrokes text flag is set in the key-view, the view system looks for a *ViewKeyDownScript method in the key-view (proto inheritance only) and calls it. Note that the *ViewKeyDownScript method is also called when there are no other pending, unprocessed keystrokes.
2. If the *ViewKeyDownScript method returns a non-nil value, handling for the key-down event is complete.
3. Otherwise, the system checks for a command key. This is described in detail in "Handling Command Keys".
4. If the key is not a command key, the default view class handling occurs. If the key-view is a clEditView, a new paragraph is created at the caret location. If the key-view is a clParagraphView, the default handling is to insert the appropriate character at the caret, unless the key is a backspace or arrow key, in which case the expected action occurs. Note that if the user is typing in an existing paragraph in an edit view, the paragraph receives the key strokes.

Key-repeat Events

The following list describes the processing sequence when the user holds down a keyboard key and key-repeat events are generated:

1. After a brief delay, the system starts issuing key-repeat events.
2. For each key-repeat event, if vSingleKeystrokes is set in the key-view, the system calls *ViewKeyRepeatScript (proto inheritance only) is called.
3. If the view does not have a *ViewKeyRepeatScript, the system calls *ViewKeyDownScript instead.
4. If this method returns non-nil, the repeated keystroke is considered to have been handled.
5. Otherwise, the system checks for a command key , as described later in this section. Commands can specify whether or not they are executed with repeated keys.
6. If the key is not a command key, the default view class handling occurs.

Key-release Events

The following list describes the processing sequence when the user releases a keyboard key and a key-up event is generated:

1. If vSingleKeystrokes is set in the key-view, the view system the *ViewKeyUpScript (proto inheritance only) is called.
2. If the *ViewKeyUpScript returns a non-nil value, the key-up event handling is complete.
3. No command check occurs with key-up events.
4. Otherwise, the default view class handling occurs. Ordinarily, this is nothing at all -- all characters are inserted at key-down time, and arrows and tabs are handled then as well. The exception is the backspace key when the last paragraph of a paragraph has been deleted: the default key-up handler for a clParagraphView will remove the view from its parent if that view is inside a clEditView.

Typing Without a Caret

The key-view must be established before a keystroke is posted. This means that when the user types and there is not an active caret (the key-view is nil), the system has to set the key-view. However, different actions need to be taken, depending on whether the keystroke is a command key or an insertable character key.

When a key is pressed and the key-view is nil, the system looks for the frontmost view that can handle it. This view may vary, depending on whether or not the key pressed is a command key.