Programming Wireless Devices with the Java2 Platform

8.4 Displayables

Displayable objects are the views in which the application interaction takes place. Application-defined operations in Displayable objects are implemented using Commands. The device implementation provides additional operations based on displayable type, as will be discussed in Section 8.6.3, "Device-Provided Operations."

All Displayable objects have the following properties:

• Zero or more Commands for application specific user operations on the Displayable

• A CommandListener (set by the application with the method setCommandListener^[1]) that gets notified when the user selects any of the Commands

  ^[1] Note that only a single CommandListener can be added because of the unicast listener model is used in the lcdui API.

• A title^[2] string (set with the setTitle method) that is presented to the user in a standard place, for example, as a header text for the Displayable

  ^[2] In MIDP Specification version 2.0, the title and Ticker properties were added to class Displayable, which means that they are also available in class Canvas. In MIDP 1.0, these properties were only available in the Screen classes.

• A Ticker object (set with the setTicker method) that provides automatically scrolling text attached to the Displayable

Both the title and Ticker can be null, which means that no title text or Ticker is displayed. Depending on the user interface implementation of the device, the existence of a Ticker or title can consume space from the rest of the displayable content.

The application is responsible for providing the means for the user to progress through different Displayables. The transition from one Displayable to another is performed using the Commands that the application has added to the current Displayable. When user selects a command, the command listener of the Displayable is activated. The listener typically changes the Displayable by calling the method setCurrent of class Display.

A badly behaving application might set up a Displayable that has no Commands. This is allowed by the API, but is generally not useful. If this occurs, the user would have no means to move to another screen. Often a device provides the means for the user to request the application manager to kill such an erroneous application.

An application can also implement Displayable changes in Canvas as actions resulting from low-level events, such as key events. In addition, nothing prevents an application from automatically changing its Displayable, for example, using a timer or thread. A possible scenario for such usage is when an application wants to continue its execution from a progress bar view^[3] after a long network transaction has finished. Generally these types of automatic displayable changes should be used with care.

^[3] This kind of a view could be implemented, e.g., using an Alert (MIDP 2.0 only) or Form with a non-interactive Gauge item. These user interface structures are discussed later.

Displayable classes that form the high-level API are called Screens. The use of different Screens is described in Chapter 9, "MIDP High-Level User Interface ?Screen." The Canvas class is the main displayable on graphic-intensive applications such as games. Canvas is also used for custom components when high-level Screen classes do not provide the necessary components. For example, a data grid or table could be implemented using the Canvas low-level drawing primitives. (See Section 11.5, "Drawing Primitives.")

8.4.1 Ticker

The Ticker class implements a "ticker-tape," a piece of text that runs continuously across the display. The direction and speed of scrolling are determined by the device. The ticker string scrolls continuously; that is, when the string finishes scrolling off the display, the ticker string starts over at the beginning of the string.

There is no API provided for starting and stopping the Ticker. Rather, the application model is that the Ticker is always scrolling continuously.

A Ticker can be added to any instance of Displayable with the method addTicker, and it can be removed with the method setTicker(null). Applications should not use Ticker on Alert screens because some devices present Alerts as pop-up dialogs that may not have space for the Ticker. The same Ticker may be shared by several Displayable objects.

Setting a Ticker often affects the size of the area available for contents of Displayable. For example, fewer elements may be visible on a List. This change in content size is especially important to note when a Ticker is used in a Canvas. If the available area changes, the application is notified via a call to the sizeChanged method. Also, the getHeight and getWidth methods of class Canvas report smaller sizes.

In a typical usage scenario, an application uses the same Ticker on all of its Displayables. When the application switches between two Displayables that have the same Ticker, the desirable consequence is for the Ticker to be displayed at the same location on the display and to continue scrolling its contents at the same position. This gives the illusion of the Ticker being attached to the display instead of separately to each Displayable.

Nothing prevents an application from using different Tickers on different sets of Displayables, or even a different one on each Displayable. For example, a Ticker can be added to a List and the Ticker can be running while the List is being presented.

Ticker ticker = new Ticker(
    "Special offer! Apples only"
    + " two gold coins per box.");
List list = new List("", List.IMPLICIT);
... // Add choices to the List
    // and set command listener
list.addCommand(okCommand);
list.addCommand(backCommand);
list.setTicker(ticker);
display.setCurrent(list);