Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

1    Receiving Input

Input Services

Exploring Palm OS®

Users send input to an application by tapping the pen inside an application's form, in the input area, or in the status bar, by pressing hardware buttons on the device, and by writing letters, numbers, or symbols in the input area (see Figure 1.1).

Figure 1.1  Receiving input

This chapter describes what happens when the user performs any of the above actions. It covers:

Pen Taps
Input Area
Hardware Controls

Pen Taps ^TOP^

When the user taps the pen on the device's display, the following happens:

  • A penDownEvent is generated specifying where the user tapped the pen.
  • A penUpEvent is generated for the same location.

When the user drags the pen on the device's display, one or more penMoveEvents are generated in between the penDownEvent and penUpEvent.

Your application, however, often does not care about these events. Instead, they are converted into other events that your application is more likely to handle.

If the user has tapped inside of a form, the FrmHandleEvent() checks the coordinates and sends them to the user interface element that was tapped. For example, if the user taps a command button, FrmHandleEvent() calls CtlHandleEvent(), which enqueues a ctlSelectEvent for that button. If the user taps in a text field, FrmHandleEvent() calls FldHandleEvent(), which enqueues a fldEnterEvent and so on.

Your application only receives events intended for it. If the user has tapped an area of the display that is outside of the bounds of your application's forms, your application does not receive the pen events. For example, if the user has tapped the status bar or in a window that is displayed by the status bar, the Status Bar Manager passes the event to the appropriate part of the system.

If the pen events are within the input area, the currently active pinlet receives and handles the events (see "Input Area") by converting them into keyDownEvents. Each keyDownEvent contains a character. This character may either be text input, such as a letter or number, or a virtual character. A virtual character is a character that performs an action, such as moving to the next field or launching a new application.

Most applications do not need to receive or handle pen events. Of course, there are exceptions. If you want to write a drawing application, you need to receive pen events to capture what the user has drawn. You might also want to directly receive pen events if you're writing a game.

If you want to capture pen events, you simply need to check for them in your form's event handler, which is called before FrmHandleEvent() is called. (FrmDispatchEvent() calls FrmHandleEvent().) See Exploring Palm OS: Programming Basics for more information about the event loop.

Input Area ^TOP^

The input area is the area of the display where the user enters textual data. There are two kinds of input areas: static and dynamic. A static input area is one that is silk-screened onto the device, such as the input area on the Palm V handheld. A dynamic input area is one that is implemented in software. On most devices with a dynamic input area, users can collapse a dynamic input area when they want to see more of the application and expand it when they want to enter more data (see Figure 1.2).

Figure 1.2  Dynamic input area

In either case, when the user taps or drags the pen in the input area, those pen events are turned into a series of keyDownEvents representing textual input that is sent to the active window. The user interface elements handle displaying that data on the screen. You typically do not have to write any extra code to display the text the user has entered.

If your application is running on a device with a dynamic input area, it is strongly recommended that you set up constraint resources for each form so that they can respond by expanding and contracting or by moving as the user opens and closes the input area. Doing so is described in Exploring Palm OS: User Interface.

Resizing is the only interaction with the input area that most applications have. It is possible to open and close the input area programmatically and to have some interaction with the pinlet that runs in the dynamic input area. See Chapter 2, "Working with the Dynamic Input Area."

Hardware Controls ^TOP^

All Palm Powered devices have a power button and some of the following:

  • One or more application buttons. Most handhelds have four application buttons for Datebook, Address Book, and so on.
  • Scroll buttons that scroll text fields and some forms up or down.
  • Contrast/brightness controls.
  • A thumb wheel used for form navigation.
  • A five-way rocker used for form navigation.
  • A built-in keyboard.

Hardware controls or buttons are often called hard keys. When a hard key is pressed, Palm OS® generates a keyDownEvent containing a virtual character specifying which button was pressed. When a hard key is released, a keyUpEvent containing the same information is sent.

Most applications should let the system handle the virtual characters. For hard keys that are intended for form navigation (such as the scroll buttons, thumb wheels, or rocker keys), you may have to write code to perform the navigation. See Exploring Palm OS: User Interface for more information.

Sometimes, you may want to have special handling for a hard key. If so, see the chapter Chapter 4, "Customizing Hardware Input." It describes how to respond to the virtual characters, remap the hard keys, and intercept them entirely.