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

1    The Display

User Interface

Exploring Palm OS®

This chapter describes basic concepts you should be familiar with before you design a user interface. It discusses the display capabilities of Palm OS® and the typical user interface you see on a Palm Powered device running Palm OS Cobalt.

Display Coordinate System
Color
Display Layout
Window Sizing and Placement
Receiving Events

Display Coordinate System ^TOP^

As shown in Figure 1.1, the origin is at the top-left of the screen and coordinates grow downward and to the right.

Figure 1.1  Coordinate systems

Palm OS uses one of two coordinate systems, standard or native, depending on the situation.

The standard coordinate system that Palm OS uses is always 160 coordinates wide. On a square screen device, the dimensions are 160 X 160. On a device with a dynamic input area, the screen dimensions are 160 X 240 coordinates.

The native coordinate system has a one-to-one mapping between coordinates and actual pixels on the screen. Thus, the native coordinate system changes depending on the display density of the device. Palm OS Cobalt version 6.0 currently supports only double-density screens, which have 320 X 320 or 320 X 480 pixels. Other versions of Palm OS support single-density screens (160 X 160 or 160 X 240 pixels) and 1.5-density screens (240 X 240 or 240 X 320). Note that double-density screens tend to be the same physical size as single-density screens; they just pack more pixels into the same space (see Figure 1.1).

Palm OS Cobalt uses the standard coordinate system to draw standard user interface elements such as forms, buttons, and menus. If you are doing custom drawing with the Graphics Context functions described in Chapter 8, "Drawing," it uses the coordinate system of the current draw window by default, which in most cases is the standard coordinate system. If you want to use the native coordinate system when drawing, you must explicitly set the drawing functions to use the native coordinate system.

Fonts and bitmaps require special handling that depends on how the font or bitmap is created. See "How Palm OS Displays Bitmapped Fonts" and "How Palm OS Displays Bitmaps."

When designing a user interface, it is usually better to think in terms of standard coordinates rather than pixels. The operating system takes care of mapping coordinates to physical pixels, and drawing functions work in terms of coordinates. So, for example, if you draw a line of text using one of the system bitmapped fonts, that line of text is 12 standard coordinates high. Depending on the display density, that text might be 12 pixels high, 24 pixels high (on a double-density display), 18 pixels high (on a 1.5-density display,) or some other multiple of 12. You can work in native coordinates if you need finer control, but you'll lose device independence.

Color ^TOP^

All Palm OS Cobalt displays are direct color displays. With direct color displays, the value stored into each pixel location specifies the amount of red, green, and blue components directly. For example, a 16-bit direct color display could have 5 bits of each pixel assigned as the red component, 6 bits as the green component, and 5 bits as the blue component.

Earlier releases supported color tables of 1, 2, 4, and 8 bits per pixel. Palm OS Cobalt supports these display depths only in software. If an application changes the display depth, the system creates a color lookup table to translate between the emulated bit depth and the actual bit depth. The lookup table has no effect on the display hardware, since the hardware derives the color from the red, green, and blue bits stored in each pixel location of the frame buffer.

Display Layout ^TOP^

The Palm OS user interface consists of drawing regions called windows. A form uses a window to display other user interface elements. Menus and pop-up lists are also types of windows.

As shown in Figure 1.2, more than one process may display a window on the screen at the same time. In Figure 1.2, there are four different windows:

  • The status bar, which runs in the system process
  • The input area displays a user interface provided by a pinlet, which runs in the background process
  • The slip window displays a user interface provided by a slip, which also runs in the background process
  • The application window displayed by the application, which runs in the application process

Figure 1.2  Palm OS Cobalt user interface


TIP: Not all devices have all of these aspects of the user interface. For example, a device with a built-in keyboard would not have the input area.

Status Bar ^TOP^

The status bar shows the status of important aspects of the system, for example, signal strength, battery life, roaming status, and the presence of awaiting messages. It is also the way users access the Launcher application and the Find facility and open or close the dynamic input area.

The status bar is a full-width window located at the bottom of the display immediately below the input area. The status bar is always present on devices that have screens that are 160 X 240 standard coordinates (320 X 480 double density displays) unless the application specifically hides it. On traditional square screen devices (160 X 160 standard coordinates), the status bar is only displayed when the Launcher application is active. Other applications may choose to display the status bar as well.

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. A dynamic input area is one that is implemented in software. 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.

A pinlet is a character input system that displays its user interface in the input area. Its job is to receive the pen events in the input area and translate them into characters that are sent to the application (or the currently active window).

The book Exploring Palm OS: Input Services explains how to write a pinlet.

Slip Window ^TOP^

A slip window displays when the user taps the icon in the status bar. For example, if the user taps a network connection icon, a slip window displays a user interface that allows the user to connect to the Internet. Slips run in the background process and display a user interface in the slip window.

Window Sizing and Placement ^TOP^

On a rectangular screen, the sizing and placement of windows is dynamic. The user can close the input area giving more space to the other displayed windows.

The Palm OS Window Manager determines the size and location of all windows. To do so, it uses two attributes that are contained in the WINDOW_CONSTRAINTS_RESOURCE that you add to each form. These attributes are the window layer and the constraints.

The window layer specifies which window may appear on top of another window if a sizing conflict occurs. The possible window layers are:

  • Menu — Used for menus
  • System — Used for the dynamic input area, the status bar, and catastrophic system messages such as the low battery alert dialog
  • Security — Used for password dialogs and other security-related dialogs.
  • Priority — Used for Palm OS system dialogs
  • Slip — Used for slip windows
  • Normal —žUsed for all application windows other than menus

Windows in a higher layer obscure the windows in the lower layer if necessary. See Figure 1.3.

Figure 1.3  Window layers

The constraints specify the location and possible sizes a window may have. You specify minimum, maximum, and preferred horizontal and vertical size (see Figure 1.4).

Figure 1.4  Example constraints

The Window Manager decides how to size the windows from the bottom of the display up:

  • The status bar is always displayed and is always 15 standard coordinates high.
  • The input area is displayed at the pinlet's preferred height if possible. If the application's preferred height conflicts with the pinlet's preferred height, the pinlet constraint overrides the application's constraint.

    If the pinlet's preferred height does not allow enough space for the application's minimum height, the pinlet's minimum height is used. If there still isn't enough room for the application, the input area overlaps the application window.

  • The slip window is displayed above the input area and is always shown at the slip's preferred height. It obscures the application window because it is in a different window layer than the application.

Figure 1.5 shows some examples of how the windows dynamically resize.

Figure 1.5  Sizing and placement examples

When the Window Manager has determined the size of all visible windows, it sends the winResizedEvent to each of them specifying their new bounds. They respond by rearranging the user interface to fit within the available bounds. Chapter 2, "Working with Forms and Dialogs," provides more information about setting constraints for a form and responding to the winResizedEvent.

Receiving Events ^TOP^

Each of the threads displaying a user interface has its own event queue and receives only the events for that thread. Because each thread has a separate event queue, a window displayed by that thread receives only the events (pen taps, and so on) intended for that thread. If the user taps a day in the Date Book, the event is sent to the application, but if the user taps an icon in the status bar, the status bar receives the event.

The application being displayed is considered to have the main event queue. The status bar, the pinlet, and any other process displaying a window are considered to have secondary event queues.

Modal Windows ^TOP^

A window in any thread can be modal. Modal windows (or modal dialogs) tend to be shorter than their modeless counterparts and should have a different look.

If a window is modal, it receives the events intended for it and for all windows in all layers below its own layer. If you create a modal window in the normal layer, the modal window receives all pen taps in the application's form. For example, if the user is displaying the Details dialog of a Date Book application and taps in the title bar of the main Date Book form, the modal dialog receives the event. (Note that the event received is a pen event, not a title select event.)

If the modal window is in the priority layer, it receives all events for all windows in the priority layer, the slip layer, and the normal layer.

The dynamic input area and status bar windows are in the system layer; therefore, as long the modal dialog is not in the system or menu layer, the status bar and dynamic input area still receive their events.

Input Focus ^TOP^

Because each thread displaying a window has a separate event queue, Palm OS needs a way to determine which event queue should receive character input. For this reason, windows have a notion of input focus. The window with the input focus is the one that receives the key events. In general, the user decides which window has the focus by tapping the pen in that window.

The events winFocusGainedEvent and winFocusLostEvent are sent to windows as they gain and lose the input focus.

Most threads should not care if they have or do not have the focus. Threads only receive the events intended for them, so you simply respond to the events you receive.

Note the following about the input focus events:

  • winFocusGainedEvent and winFocusLostEvent are only sent regarding focusable windows. Menus and pop-up lists are not focusable windows, so the display of a menu does not generate one of these events. The input area's window is also not focusable.
  • When a form is first displayed, it requests input focus. That request might be denied if another thread requests the input focus for its window and its window is in a higher layer than the form's window is. The form will still be displayed, but it will not receive the keyDownEvents until the user gives that form the input focus.
  • Some slip windows are not forms and do not use the UI Library. If such a slip window is opened, it does not request the input focus if it does not need to receive keyDownEvents. For example, if you open the Time and Date slip, the application still has the input focus.
  • You may or may not receive a winEnterEvent or winExitEvent around the same time as a winFocusGainedEvent and winFocusLostEvent. The two types of events work independently of each other.

    winFocusGainedEvent and winFocusLostEvent are sent asynchronously and are only about which window will receive keyDownEvents. winEnterEvent and winExitEvent are about which window receives the next pen or key event. They exist for backward compatibility and are only sent within the same thread for windows created using the UI Library.