Programming Wireless Devices with the Java2 Platform

8.2 Structure of the MIDP User Interface API

The following sections provide an overview to the MIDP user interface API (javax.microedition.lcdui). The remainder of this chapter and the following two chapters concentrate on the high-level parts of the API. The low-level user interface API features are detailed in Chapter 11, "MIDP Low-Level User Interface Libraries."

The separation of high-level and low-level API is often not very clear-cut. There are many classes that are used both in low-level and high-level APIs. For example, classes Image and Font are used both in high-level Screen components and low-level graphics drawing. Also, in MIDP 2.0 the new CustomItem class makes it possible to mix low-level graphics and high-level components within a Form object.

MIDP 2.0 also includes a new game-specific API provided in javax.microedition.lcdui.game package. The MIDP 2.0 Game API is discussed in Chapter 12.

8.2.1 Displayable Model

The central abstraction of the MIDP user interface is class Displayable. Class Displayable helps organize the user interface into manageable pieces. This results in user interfaces that are easy to use and learn. Each MIDP application has a Display on which a single Displayable object is shown. The application sets and resets the current Displayable object on the Display for each step of the task, based on user interactions. The user tasks (interactions with the user interface) are implemented using Command objects. The application is notified automatically when a Command is selected by the user. As a result of these notifications the application often changes the current Displayable to some other Displayable. The device software manages the sharing of the physical display between the native applications and the MIDP applications.

The rationale behind the displayable-oriented approach is based on the wide variations in display and keypad configurations found in MIDP devices. Each device provides a consistent look and feel by handling the component layout, painting, scrolling, and focus traversal. If an application needed to be aware of these details, portability would be difficult to achieve, and smooth integration with the look and feel of the device and its native applications would place a heavy burden on application developers.

There is a hierarchy of Displayable subclasses called Screens in the lcdui API. Each Screen is a functional user interface element that encapsulates device-specific graphics rendering and user input handling. Figure 8.1 shows the hierarchy of the user interface classes.

There are two types of Displayable subclasses:

• Canvas: low-level objects that allow the application to provide the graphics and handle input

• Screen: high-level objects that encapsulate complete user interface components (classes Alert, List, TextBox, or Form)

Any application may use combinations of Screens and Canvases to present an integrated user interface. For instance, in a game application, Lists and Forms can be used to select or configure the options of a game, while Canvas (or GameCanvas) can be used for the interactive game components.

The Command class is used for implementing the application specific operations. For example, the navigation between different application Displayables is implemented using Commands. Details of Commands are described in Section 8.5, "Commands."

8.2.2 Low-Level User Interface

The low-level user interface API for Canvas is designed for applications that need precise placement and control of graphic elements as well as access to low-level input events. Typical examples are a game board, a chart object, or a graph. Using the low-level user interface API, an application can

• control what is drawn on the display,

• handle primitive events such as key presses and releases, and

• access concrete keys and other input devices.

Applications that are programmed with the low-level API can be portable if the application uses only the standard features; applications should stick to the platform-independent part of the low-level API whenever possible. This means that the applications should not directly assume the presence of any keys other than those defined in class Canvas. Also, applications should inquire about the size of the display and its color capabilities and adjust behavior accordingly. See Section 8.6.2, "Adaptation to Device-Specific User Interface Style."

The CustomItem class allows the application developer to use low-level graphics on a Form. CustomItem provides a way to mix both low-level and high-level components within a single Form. Painting using the CustomItem class is done similarly to painting to Canvas via the Graphics class.

The low-level API is described in detail in Chapter 11, "MIDP Low-Level User Interface Libraries," and in Chapter 12, "MIDP Game API."

8.2.3 High-Level User Interface

The high-level user interface API is designed for business applications whose client components run on mobile information devices. For these applications, portability across devices is important. To achieve such portability, the high-level user interface API employs a high level of abstraction and provides very little control over look and feel. This allows devices to use the native user interface look and feel for the high-level MIDP user interface API components. This means that when an application is written with the high-level API, its look and feel automatically uses the look and feel of the device in which the application is currently running. For the end users this provides seamless user interaction: the MIDP application works the same way as the other (native) applications on the device.

The high-level user interface components described in this section behave consistently with the in-built user interfaces and applications of a device. More specifically, when using the high-level API:

• Drawing to the display is performed by the device's system software. Applications do not define the visual appearance (such as shape, color, and so forth) of the components.

• Navigation, scrolling, and other primitive interactions with the user interface components are performed by the device. The application is not aware of these interactions.

• Applications cannot access concrete input mechanisms, such as individual keys.

The high-level API is provided through the Screen classes, which are:

• List: allows a selection from a predefined set of choices.

• TextBox: is a plain text editor with controllable editing modes.

• Alert: displays temporary messages or simple choice queries.

• Form: is a more generic container that allows to display multiple, closely-related user interface elements called Items.

These different Screen classes are more thoroughly presented in Chapter 9, "MIDP High-Level User Interface ?Screen."

The class Form is defined for cases where a screen with a single function is not sufficient. Class Form is designed to contain a small number of closely related user interface elements, or Items. For example, an application might have two TextFields, or a TextField and a simple ChoiceGroup. If all the Items of a Form do not fit on the screen, the implementation might make the Form scrollable, expand each Item automatically when the user edits it, or use a "pop up" representation. Each Form can contain a combination of the following Item subclasses:

• StringItem, used for static text display, or as a button or hyperlink.

• ImageItem, used for static image display, or as an image button or hyperlink.

• TextField, used for textual input with constraints.

• DateField, used for display or input of time and date values.

• Gauge, used as a progress indicator or as a numeric input from a specific range.

• ChoiceGroup, used for single or multiple selections from a set of elements.

• CustomItem (MIDP 2.0), used to create application specific items; drawing is done with low-level Graphics API.

• Spacer (MIDP 2.0), used to create empty spaces for layout purposes.

Although the Form class allows the creation of arbitrary combinations of components, developers should keep in mind the limited display size and make Forms simple and functional. Chapter 10, "MIDP High-Level User Interface ?Form" discusses the various Form classes in detail.