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.

Figure 8.1. MIDP user interface class hierarchy (all classes not shown)

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: