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

Chapter 4 - Keyboard Enhancements / Using the Keyboard Enhancements

Keystroke Handling

This section describes how to handle keystrokes in your Newton applications. Table 4-9 shows the functions and methods that you can use to handle keystrokes.

Table 4-9 Summary of keystroke-handling methods and functions

Function/Method	Description
IsCommandKeystroke	Determines if a keystroke is a command key combination.
ViewKeyDownScript	Sent to the key-view when the user presses a key.
ViewKeyUpScript	Sent to the key-view when the user releases a key.
ViewKeyStringScript	Sent to the key-view when a group of keystrokes needs to be processed. This can occur when single keystroke handling is not applied to the key-view (when the vSingleKeystrokes flag is not set.
ViewKeyRepeatScript	Sent to the key-view while the user holds a key down.

Intercepting Keystrokes Directly

To intercept keystrokes directly, you need to respond to the key-down, key-repeat, and key-up events. If you set the vSingleKeystrokes text flag for your view, you are guaranteed that the scripts for these key events are called for every keystroke. If you do not set the vSingleKeystrokes text flag for your view, the scripts are called only under certain circumstances.

Note

Setting the vSingleKeystrokes text flag in a paragraph view results in a substantial reduction in typing performance for the user. This is because the system processes each keystroke individually, rather than batching a set of keystrokes into a string.

The system software calls a method for each of the keyboard events. For an overview of the sequencing of actions when the user presses keys, see "Keystroke Event Sequencing". If the method returns nil (to indicate that the system should continue processing the key event), the system next checks the key to determine if it is a command key. If the event is not a command key, the system hands the key event to the appropriate view for default handling.

The functions and event scripts for handling keystrokes are shown in Table 4-9; their use is described in the remainder of this section.

Intercepting Individual Keystrokes

Here is an example of code that processes individual keystrokes.

 ViewKeyDownScript: func( char, flags )

   begin
   if char = unicodeCR then
      begin
      :OutputTextLine( self.text );
      SetValue( self, 'text, "" );
      return true;
      end;

      // Explicitly return nil just for clarity
   nil;
end;

Intercepting Grouped Keystrokes

If you have not set the vSingleKeystrokes flag for the key-view, the system groups together a set of keystrokes (a keystring) for batch processing and sends the *ViewKeyStringScript message when a group of keystrokes is ready to be handled.

Note

Although the system can group keystrokes into keystrings, this only happens when the user is typing at a very high speed. If the system can keep up with individual keystrokes, the keystrokes are not grouped into a keystring.

Text Flags and Keyboard Input

Paragraph views, edit views, and text editing views all accept both command keys and normal keys (for insertion). For other views, there are two additional textFlags that you can use to specify the kinds of keystrokes you want to handle, as shown in Table 4-10.

Table 4-10 Text flags to specify the kind of keystrokes a view accepts

Text Flag	Description
vTakesCommandKeys	The view accepts command keys.
vTakesAllKeys	The view accepts all keys, including command keys.

Note:

Do not use the text flags shown in Table 4-10 for edit views, paragraph views, or word-processing (*protoTXView) views, all of which always act as if both flags are on (as long as they are not read-only views).

These flags are also significant when a normal key is typed. If a normal key is typed when the key-view accepts only command keys, the key-view is switched to the frontmost view that accepts normal keys.

You can determine which view is the frontmost view that accepts normal keystroke by calling GetView as follows:

 view := GetView('viewfrontkey);

You can determine which view is the frontmost view that accepts command keystrokes by calling GetView as follows:

 view := GetView('viewfrontcommandkey);