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

Chapter 4 - Keyboard Enhancements / About Keyboard Enhancements

About Keyboard Support in Pickers

In most Newton applications, when the user selects an item in a picker, the picker's PickActionScript is called, and when the user taps outside of the picker, the picker's PickCancelledScript is called. When you have key commands defined in a picker view, this changes.

In the Newton 2.1 OS, when the user selects an item in a picker, the system first determines if the item has a key-command associated with it. If so, the method associated with that key-command (its keyMessage) is called instead of the PickActionScript.

You can override this by adding the alwaysCallPickActionScript flag to your picker. When this flag is on (set to true), the system software always calls the PickActionScript, regardless of whether or not there's a key-command for the item. If the alwaysCallPickActionScript flag is off (set to nil), the system software calls the key-command method for the item if there is one, and calls the PickActionScript method for the item if there is not a key-command associated with it.

WARNING

You must always set the alwaysCallPickActionScript flag to true in the protoLabelPicker and protoLabelInputLine protos; otherwise, these protos do not function properly. Note that you can still call the key-command method for an item in one of these pickers, as shown in "Calling a Key-Command Method From a Picker Script".

Calling a Key-Command Method From a Picker Script

As described in "About Keyboard Support in Pickers", your key-command methods can be automatically called when a user selects an item in a picker. This happens when the alwaysCallPickActionScript flag is set to nil in a picker.

There are two picker protos that do not work properly when the alwaysCallPickActionScript flag is set to nil: protoLabelPicker and protoLabelInputLine. You must set the alwaysCallPickActionScript flag to true in these protos.

If you want to call a key-command method when the user selects an item in a protoLabelInputLine or protoLabelPicker, you need to call the key-command method from the PickActionScript for that proto.

Listing 4-1 shows an example of calling a key-command method from a picker. In this sample code, the method is called from the labelActionScript, which is called by the proto's pickActionScript.

Listing 4-1 Calling a key-command method from a picker

 labelActionScript: func(cmd)

   begin
   local item := labelCommands[cmd];
   if item.keyMessage then
      SendKeyMessage( self, item.keyMessage );
   else
      // do normal item processing here
   end;