Package javax.microedition.lcdui

The APIs in the LCDUI package provide a set of features for implementing user interfaces in MIDP applications.

See:
Description

Interface Summary

Choice	Choice defines an API for a user interface components implementing selection from predefined number of choices.
CommandLayoutPolicy	This interface is used to implement exact placement of commands.
CommandListener	This interface is used by applications which need to receive high-level events from the implementation.
DisplayListener	The DisplayListener interface defines a series of methods that are called in response to Display events.
ItemCommandListener	A listener type for receiving notification of commands that have been invoked on Item objects.
ItemLayoutHint	ItemLayoutHint is an interface to identify classes containing hints that control the layout of Items by subclasses of FormLayoutPolicy.
ItemStateListener	This interface is used by applications that need to receive events indicating changes in the internal state of the interactive items within a Form screen.
ItemTraversalListener	This interface is used by applications that need to receive events indicating changes in focus for Items in a Form screen.
KeyListener	Classes implementing this interface provide methods that are called when user of the device will generate key events, for example, pressing the keys available in a system keypad or keyboard.
NotificationListener	This interface is used by applications that need to receive events indicating changes in the state of a Notification.
TabListener	This interface is used to receive events related to changes on a TabbedPane.
TextEditorChangeListener	A listener for receiving notification of content changes and other editor events that have been invoked on TextEditor objects.

Class Summary

Alert	An alert is a screen that shows data to the user and waits for a certain period of time before proceeding to the next Displayable.
AlertType	The AlertType provides an indication of the nature of alerts.
AnimatedImage	An AnimatedImage is a special type of Image that encapsulates a series frames and the length of time that each frame should be shown.
Canvas	The Canvas class is a base class for writing applications that need to handle low-level events and to issue graphics calls for drawing to the display.
CanvasItem	CanvasItem abstracts the generic features of it's subclasses, such as TextEditor component.
ChoiceGroup	A ChoiceGroup is a group of selectable elements intended to be placed within a Form.
Command	The Command class is a construct that encapsulates the semantic information of an action.
CustomItem	A CustomItem is customizable by subclassing to introduce new visual and interactive elements into Forms.
DateField	A DateField is an editable component for presenting date and time (calendar) information that may be placed into a Form.
Display	The Display class provides a MIDlet with access to the device's user interface hardware resources.
Displayable	An object that has the capability of being placed on the display.
FileSelector	The FileSelector class allows the user to select a file from file system to be loaded, saved, or to select a directory.
Font	The Font class represents fonts, which are used to render text in a visible way.
Form	A Form is a Screen that contains an arbitrary mixture of items: images, read-only text fields, editable text fields, editable date fields, gauges, choice groups, and custom items.
FormLayoutPolicy	FormLayoutPolicy is subclassed to provide custom layout algorithms.
Gauge	Implements a graphical display, such as a bar graph, of an integer value.
Graphics	Provides simple 2D geometric rendering capability.
IdleItem	This class represents a dedicated UI component that can be used to render content to the idle screen.
Image	The Image class is used to hold graphical image data.
ImageItem	An item that can contain an image.
Item	A superclass for components that can be added to a Form.
List	A Screen containing list of choices.
Menu	A visual container for Commands and other Menus.
Notification	Represents a small unobtrusive informational note to be shown to the user.
NotificationType	Represents the Notification type (or category) used for grouping, sorting and filtering Notification objects of the same type.
ScalableImage	A ScalableImage object encapsulates vector graphics content.
Screen	The common superclass of all high-level user interface classes.
Spacer	A blank, non-interactive item that has a settable minimum size.
StringItem	An item that can contain a string.
TabbedPane	TabbedPane is a Screen subclass that presents a series of Screens to the users and allows them to navigate between screens by selecting the corresponding tab.
TableLayoutPolicy	TableLayoutPolicy displays the Items in a Form aligned in columns.
Text	The Text class is used to layout and render text within a specific area.
TextBox	The TextBox class is a Screen that allows the user to enter and edit text.
TextEditor	A TextEditor is an editable text component that is drawn on a parent object; in LCDUI Canvas or CustomItem (including IdleItem).
TextField	A TextField is an editable text component that may be placed into a Form.
Ticker	Implements a "ticker-tape", a piece of text that runs continuously across the display.

Exception Summary

DisplayCapabilityException	Indicates that a Display's capabilities are insufficient for the requested operation.
FontFormatException	Indicates that a font format is not supported, or that font data is invalid or is not conformant with the specified font format (OpenType with TrueType outlines).
NotificationException	Indicates that an operation on a Notification has failed.

Package javax.microedition.lcdui Description

The APIs in the LCDUI package provide a set of features for implementing user interfaces in MIDP applications.

Unless otherwise noted, passing a null argument to a constructor or method in any class or interface in this package MUST cause a NullPointerException to be thrown.

User Interface

The User Interface features in MIDP have been specifically designed with mobile information devices in mind (i.e., mobile phones and pagers). These devices differ from desktop systems in many ways, especially how the user interacts with them. The following UI-related requirements are important when designing the user interface API:

• The devices and applications should be useful to users who are not necessarily experts in using computers.
• The devices and applications should be useful in situations where the user cannot pay full attention to the application. For example, many phone-type devices will be operated with one hand.
• The form factors and UI concepts of the device differ between devices, especially from desktop systems. For example, the display sizes are smaller, and the input devices do not always include pointing devices.
• The applications run on MIDs should have UIs that are compatible with the native applications so that the user finds them easy to use.

In addition, these devices may have limited memory and processing power. Since the user interface is a primary consumer of such resources, the API's have been designed to avoid the creation of garbage objects and other performance issues wherever possible.

Structure of the MIDP UI API

The API is logically composed of two sets of APIs: the high-level and the low-level.

The high-level API is designed for applications where portability across devices is important. To achieve this portability, the high-level API employs a high level of abstraction and provides less control over the look and feel of the user interface. This abstraction is further manifested in the following ways:

• The actual drawing to the MID's display is performed by the implementation. Applications have limited influence over the visual appearance (e.g., shape, color, font, etc.) of the components.
• Navigation, scrolling, and other primitive interaction is encapsulated by the implementation, and the application does not have control over these interactions.
• Applications cannot access concrete input devices like specific individual keys.

In other words, when using the high-level API, it is assumed that the underlying implementation will do the necessary adaptation to the device's hardware and native UI style. The classes that provide the high-level API are the subclasses of Screen.

The low-level API, on the other hand, provides very little abstraction. This API is designed for applications that need precise placement and control of graphic elements, as well as access to low-level input events. A typical example of such an application would be a game.

Using the low-level API, an application can:

• Have full control of what is drawn on the display.
• Listen for primitive events from keys and touchscreens.

The classes that provide the low-level API are Canvas and Graphics.

Applications that program to the low-level API are not guaranteed to be portable, since use of the low-level API involves details that are specific to a particular device. It is recommended that applications using low-level API be written such that they can adapt to different device characteristics wherever possible. This means that the applications should not directly assume the existence of any keys other than those defined in the Canvas class, and they should not depend on a specific screen size. Rather, the application game-key event mapping mechanism should be used instead of concrete keys, and the application should inquire about the size of the display and adjust itself accordingly.

Class Hierarchy

The Display class represents a given MIDlet's use of a particular display device and it also provides methods to retrieve information about that display device's capabilities. For each active MIDlet, a Display object may be obtained for each display device; a primary Display object is provided for accessing the device's main display. In addition to the primary Display, there may be other display hardware that is an integral part of device, such as the second screen on the outside of the mobile phone's flip; these display hardware are classified as Built-In displays. There may be other display resources that are available to the device via a suitable connection, these are classified as Auxiliary displays. In addition to the primary Display, one or more Built-in and Auxiliary displays may be available to the MIDlet. The Display class provides more details on accessing Displays.

The Display class is also responsible for controlling access to a display device if multiple MIDlets are trying to use simultaneously. Display objects have a state that indicates their relative priority for using the display device.

The main abstraction of the UI is a Displayable object, which encapsulates device-specific graphics rendering with user input. Only one Displayable may be shown at a time on a given Display, and the user can see and interact with only contents of that Displayable. A Displayable is made visible by calling the setCurrent() method of the appropriate Display. When a Displayable is made current, it replaces the previous Displayable.

The Screen class is a subclass of Displayable that takes care of all user interaction with high-level user interface component. The Screen subclasses handle rendering, interaction, traversal, and scrolling, with only higher-level events being passed on to the application.

The rationale behind this design is based on the different display and input solutions found in MIDP devices. These differences imply that the component layout, scrolling, and focus traversal will be implemented differently on different devices. If an application were required to be aware of these issues, portability would be compromised. Simple screenfuls also organize the user interface into manageable pieces, resulting in user interfaces that are easy to use and learn.

There are three categories of Displayable objects:

• Screens that encapsulate a complex user interface component (e.g., classes List or TextBox). The structure of these screens is predefined, and the application cannot add other components to these screens.
• Generic screens (instances of the Form class) that can contain Item objects to represent user interface components. The application can populate Form objects with an arbitrary number of text, image, and other components; however, it is recommended that Form objects be kept simple and that they should be used to contain only a few, closely-related user interface components.
• Screens that are used in context of the low-level API (i.e., subclasses of class Canvas).

Each Displayable can have a title, a Ticker and a set of Commands attached to it.

Class Overview

Many applications will utilize screens with predefined structures like List, TextBox, and Alert. These classes are used in the following ways:

• List is used when the user should select from a predefined set of choices.
• TextBox is used when asking textual input.
• Alert is used to display temporary messages containing text and images.

A special class Form is defined for cases where screens with a predefined structure are not sufficient. For example, an application may have two TextFields, or a TextField and a simple ChoiceGroup. Although the Form class allows creation of arbitrary combinations of components, developers should keep the limited display size in mind and create only simple Forms.

Form is designed to contain a small number of closely related UI elements. These elements are the subclasses of Item: ImageItem, StringItem, TextField, ChoiceGroup, Gauge, and CustomItem. The classes ImageItem and StringItem are convenience classes that make certain operations with Form and Alert easier. By subclassing CustomItem application developers can introduce Items with a new visual representation and interactive elements. If the components do not all fit on the screen, the implementation may either make the form scrollable or implement some components so that they can either popup in a new screen or expand when the user edits the element.

A default layout scheme is provided for laying out the Items in a Form, but the developer may implement a custom layout scheme by creating a subclass of FormLayoutPolicy.

Interplay with Application Manager

The user interface, like any other resource in the API, is to be controlled according to the principle of MIDP application management. The UI may assume the following conditions from the application management software:

• getDisplay() and getDisplays() are callable starting from the MIDlet's constructor until destroyApp() has returned.
• The Display objects for built-in display devices are the same until destroyApp() is called.
• The Displayable object set by setCurrent() is not changed by the application manager.

The application manager assumes the following application behavior with respect to the MIDlet events :

• The application may call setCurrent() to display its first screen at any point after its constructor has been called. However, the Displayable will be shown by the application manager only after startApp() returns.
• destroyApp - The application should release resources and objects.

Event Handling

User interaction generates events, and the implementation notifies the application of the events by making corresponding callbacks. There are four kinds of UI callbacks:

• Abstract commands that are part of the high-level API
• Low-level events that represent single key presses and releases (and pointer events, if a pointer is available)
• Calls to the paint() method of a Canvas class
• Calls to a Runnable object's run() method requested by a call to callSerially() of class Display

All UI callbacks are serialized, so they will never occur in parallel. That is, the implementation will never call an callback before a prior call to any other callback has returned. This property enables applications to be assured that processing of a previous user event will have completed before the next event is delivered. If multiple UI callbacks are pending, the next is called as soon as possible after the previous UI callback returns. The implementation also guarantees that the call to run() requested by a call to callSerially() is made after any pending repaint requests have been satisfied.

There is one exception to the callback serialization rule, which occurs when the Canvas.serviceRepaints method is called. This method causes the Canvas.paint method to be called and waits for it to complete. This occurs even if the caller of serviceRepaints is itself within an active callback. There is further discussion of this issue below.

The following callbacks are all serialized with respect to each other :

• Canvas.hideNotify
• Canvas.keyPressed
• Canvas.keyRepeated
• Canvas.keyReleased
• Canvas.paint
• Canvas.pointerDragged
• Canvas.pointerPressed
• Canvas.pointerReleased
• Canvas.showNotify
• Canvas.sizeChanged
• CommandListener.commandAction
• CustomItem.getMinContentHeight
• CustomItem.getMinContentWidth
• CustomItem.getPrefContentHeight
• CustomItem.getPrefContentWidth
• CustomItem.hideNotify
• CustomItem.keyPressed
• CustomItem.keyRepeated
• CustomItem.keyReleased
• CustomItem.paint
• CustomItem.pointerDragged
• CustomItem.pointerPressed
• CustomItem.pointerReleased
• CustomItem.showNotify
• CustomItem.sizeChanged
• CustomItem.traverse
• CustomItem.traverseOut
• Displayable.sizeChanged
• DisplayListener.displayAdded
• DisplayListener.displayStateChanged
• DisplayListener.hardwareStateChanged
• DisplayListener.orientationChanged
• DisplayListener.sizeChanged
• FormLayoutPolicy.doLayout
• IdleItem.addedToDisplay
• IdleItem.removedFromDisplay
• ItemCommandListener.commandAction
• ItemStateListener.itemStateChanged
• ItemTraversalListener.itemTraversedIn
• ItemTraversalListener.itemTraversedOut
• Runnable.run resulting from a call to Display.callSerially
• TabListener.tabChangeEvent

Note that java.util.Timer events are not considered UI events. Timer callbacks may run concurrently with UI event callbacks, although java.util.TimerTask callbacks scheduled on the same Timer are serialized with each other. Applications that use timers must guard their data structures against concurrent access from timer threads and UI event callbacks. Alternatively, applications may have their timer callbacks use Display.callSerially so that work triggered by timer events can be serialized with the UI event callbacks.

Abstract Commands

Since MIDP UI is highly abstract, it does not dictate any concrete user interaction technique like soft buttons or menus. Also, low-level user interactions such as traversal or scrolling are not visible to the application. MIDP applications define Commands , and the implementation may manifest these via either soft buttons, menus, or whatever mechanisms are appropriate for that device.

Commands are installed to a Displayable (Canvas or Screen) with a method addCommand of class Displayable. There are two methods for deciding where Commands are placed: native style (default) and exact placement (introduced in MIDP 3.0).

The native style of the device may assume that certain types of commands are placed on standard places. For example, the "go-back" operation may always be mapped to the right soft button. The Command class allows the application to communicate such a semantic meaning to the implementation so that these standard mappings can be effected.

The exact placement method lets the application developer specify exact placement of Commands and Menus on a Displayable, when this is appropriate (for example, placement of soft buttons on a screen, or associating a Command with an offscreen key). The normal placements of commands are available from a Display. The available placements for soft keys and the location of the labels can be retrieved from the Displayable. The choice of exact placement is made by the Displayable object adding the Command or Menuobject by adding an optional placement attribute to the addCommand() or addMenu() method.

The implementation does not actually implement any of the semantics of the Command. The attributes of a Command are used only for mapping it onto the user interface. The actual semantics of a Command are always implemented by the application in a CommandListener.

In MIDP 3.0 Commands are mutable, and its attributes may change at any time. It is up to the implementation to act as soon as possible on the change.

Command objects have attributes:

• Label: Shown to the user as a hint. A single Command can have two versions of labels: short and long. The implementation decides whether the short or long version is appropriate for a given situation. For example, an implementation can choose to use a short version of a given Command near a soft button and the long version of the Command in a menu.
• Type: The purpose of a command. The implementation will use the command type for placing the command appropriately within the device's user interface. Commands with similar types may, for example, be found near each other in certain dedicated place in the user interface. Often, devices will have policy for placement and presentation of certain operations. For example, a "backward navigation" command might be always placed on the right soft key on a particular device, but it might be placed on the left soft key on a different device. The Command class provides fixed set of command types that provide MIDlet the capability to tell the device implementation the intent of a Command. The application can use the BACK command type for commands that perform backward navigation. On the devices mentioned above, this type information would be used to assign the command to the appropriate soft key.
• Priority: Defines the relative importance between Commands of the same type. A command with a lower priority value is more important than a command of the same type but with a higher priority value. If possible, a more important command is presented before, or is more easily accessible, than a less important one.
• Enabled: Used to enable/disable a Command that is disabled will typically remain visible, but greyed out, and cannot be chosen.

Device-Provided Operations

In many high-level UI classes there are also some additional operations available in the user interface. The additional operations are not visible to applications, only to the end-user. The set of operations available depends totally on the user interface design of the specific device. For example, an operation that allows the user to change the mode for text input between alphabetic and numeric is needed in devices that have only an ITU-T keypad. More complex input systems will require additional operations. Some of operations available are presented in the user interface in the same way the application-defined commands are. End-users need not understand which operations are provided by the application and which provided by the system. Not all operations are available in every implementation. For example, a system that has a word-lookup-based text input scheme will generally provide additional operations within the TextBox class. A system that lacks such an input scheme will also lack the corresponding operations. Availability of various text input modes (for example, predictive input and numbers-only input) SHOULD be consistent across Java and native applications. This means, for example, that if predictive text input mode is available in native applications, it SHOULD also be available in Java applications.

Some operations are available on all devices, but the way the operation is implemented may differ greatly from device to device. Examples of this kind of operation are: the mechanism used to navigate between List elements and Form items, the selection of List elements, moving an insertion position within a text editor, and so forth. Some devices do not allow the direct editing of the value of an Item, but instead require the user to switch to an off-screen editor. In such devices, there must be a dedicated selection operation that can be used to invoke the off-screen editor. The selection of a List elements could be, for example, implemented with a dedicated "Go" or "Select" or some other similar key. Some devices have no dedicated selection key and must select elements using some other means.

On devices where the selection operation is performed using a dedicated select key, this key will often not have a label displayed for it. It is appropriate for the implementation to use this key in situations where its meaning is obvious. For example, if the user is presented with a set of mutually exclusive options, the selection key will obviously select one of those options. However, in a device that doesn't have a dedicated select key, it is likely that the selection operation will be performed using a soft key that requires a label. The ability to set the select-command for a List of type IMPLICIT and the ability to set the default command for an Item are provided so that the application can set the label for this operation and so it can receive notification when this operation occurs.

Jog Dial Interaction

A device may have a 3-way or 5-way jog dial as a control mechanism. A 3-way jog dial is usually a wheel that rotates in two directions (to indicate scrolling) and can also be pressed (to indicate a selection). A 5-way jog dial is typically similar to a 3-way jog dial with the added possibility to tilt the wheel sideways. A jog dial wheel might have the ability to be rolled several steps in each direction. Alternatively, a jog dial wheel might only have the ability to be rotated by a limited angle, returning to the base position when released. When MIDP is implemented on a device with a jog dial, the requirements are as follows:

• An implementation MUST generate key press events in response to jog dial movements. An implementation MAY reuse key codes assigned to device keys with functions similar to jog dial functions (for example, key codes assigned to cursor keys can also be used for jog dial events). However, an implementation MAY choose to use unique key codes for jog dial events. Key events generated by directional movements may use different key codes to reflect different spatial orientations.
• An implementation MUST map key press events generated by jog dial movements to game actions via the Canvas.getGameAction() method. The mapping of game actions MUST always be natural in relation to the spatial orientation of the device (that is, UP events are always generated when the jog dial is rolled upwards from the user point of view). Consequently, an implementation MAY need to alter its mapping of key events to game actions depending on the spatial orientation of the device. In the same vein, a clamshell device MAY generate different jog dial events when the clamshell is in OPEN or CLOSED mode.
• Since the mapping of key events and game actions may change in response to orientation changes, application should call Canvas.getGameAction() for each event to ensure that the current mapping is used. Applications may also register a DisplayListener to be notified when the orientation changes and the key code mappings may be revised.
• A 3-way jog dial MUST generate key events with key codes mapping to game actions UP, DOWN and FIRE, or game actions LEFT, RIGHT and FIRE, depending on the relative orientation currently in effect.
• A 5-way jog dial MUST generate key events with key codes mapping to game actions UP, DOWN, LEFT, RIGHT and FIRE.
• A jog dial MAY also be used to control high level UI objects.

Note: Depending on the mechanics of the jog wheel, the implementation is not necessarily able to generate key repeat events for some movements (for example, when the wheel is rotated).

High-Level API for Events

The handling of events in the high-level API is based on a listener model. Screens and Canvases may have listeners for commands. An object willing to be a listener should implement an interface CommandListener that has one method :

void commandAction(Command c, Displayable d);
                

The application gets these events if the Screen or Canvas has attached Commands and if there is a registered listener. A unicast-version of the listener model is adopted, so the Screen or Canvas can have one listener at a time.

There is also a listener interface for state changes of the Items in a Form . The method

void itemStateChanged(Item item);
                

defined in interface ItemStateListener is called when the value of an interactive Gauge , ChoiceGroup, or TextField changes. It is not expected that the listener will be called after every change. However, if the value of an Item has been changed, the listener will be called for the change sometime before it is called for another item or before a command is delivered to the Form's CommandListener. It is suggested that the change listener is called at least after focus (or equivalent) is lost from field. The listener should only be called if the field's value has actually changed.

A listener interface is also provided for events related to focus traversal between Items in a Form. The methods

void itemTraverseIn(Item item);
void itemTraverseOut(Item item);
                        

defined in interface ItemTraversalListener are called when an Item gains or loses focus, respectively.

Low-Level API for Events

Low-level graphics and events have the following methods to handle low-level key events :

public void keyPressed(int keyCode);
public void keyReleased(int keyCode);
public void keyRepeated(int keyCode);
                

The API requires that there be standard key codes for the ITU-T keypad (0-9, *, #), but no keypad layout is required by the API. Although an implementation may provide additional keys, applications relying on these keys are not portable.

In addition, the class Canvas has methods for handling abstract game events. An implementation maps all these key events to suitable keys on the device. For example, a device with four-way navigation and a select key in the middle could use those keys, but a simpler device may use certain keys on the numeric keypad (e.g., 2, 4, 5, 6, 8). These game events allow development of portable applications that use the low-level events. The API defines a set of abstract key-events: UP, DOWN, LEFT, RIGHT, FIRE, GAME_A, GAME_B, GAME_C, and GAME_D.

An application can get the mapping of the key events to abstract key events by calling :

public static int getGameAction(int keyCode);
                

If the logic of the application is based on the values returned by this method, the application is portable and run regardless of the keypad design.

It is also possible to map an abstract event to a key with :

public static int getKeyCode(int gameAction);
                

where gameAction is UP,DOWN, LEFT, RIGHT, FIRE, etc. On some devices, more than one key is mapped to the same action, in which case the getKeyCode method will return just one of them. Properly-written applications should map the key code to an abstract key event and make decisions based on the result.

The mapping between keys and abstract events does not change during the execution of the game.

The following is an example of how an application can use game actions to interpret keystrokes.

class MovingBlocksCanvas extends Canvas {
        public void keyPressed(int keyCode) {
                int action = getGameAction(keyCode);
                switch (action) {
                        case LEFT:
                                moveBlockLeft();
                                break;
                        case RIGHT:
                                ...
                }
        }
}
                

The low-level API also has support for pointer events, but since the following input mechanisms may not be present in all devices, the following callback methods may never be called in some devices :

public void pointerPressed(int x, int y);
public void pointerReleased(int x, int y);
public void pointerDragged(int x, int y);
                

The application may check whether the pointer is available by calling the following methods of class Canvas :

public static boolean hasPointerEvents();
public static boolean hasPointerMotionEvents();
                

Some devices may support multi-touch user interfaces (i.e. they can detect and track multiple simultaneous touch points instead of a single 'pointer' location). Since applications cannot distinguish between the different touch points using the MIDP APIs, the delivery of multiple simultaneous touch events has the potential to cause unpredictable behavior. Therefore, implementations MUST NOT deliver secondary touch events to MIDlets using the MIDP APIs; only the primary touch event and its corresponding drag and release events are to be delivered using the MIDP APIs.

Interplay of High-Level Commands and the Low-Level API

The class Canvas , which is used for low-level events and drawing, is a subclass of Displayable , and applications can attach Commands to it. This is useful for jumping to an options setup Screen in the middle of a game. Another example could be a map-based navigation application where keys are used for moving in the map but commands are used for higher-level actions.

Some devices may not have the means to invoke commands when Canvas and the low-level event mechanism are in use. In that case, the implementation may provide a means to switch to a command mode and back. This command mode might pop up a menu over the contents of the Canvas. In this case, the Canvas methods hideNotify() and showNotify() will be called to indicate when the Canvas has been obscured and unobscured, respectively.

The Canvas may have a title and a Ticker like the Screen objects. However, Canvas also has a full-screen mode where the title and the Ticker are not displayed. Setting this mode indicates that the application wishes for the Canvas to occupy as much of the physical display as is possible. In this mode, the title may be reused by the implementation as the title for pop-up menus. In normal (not full-screen) mode, the appearance of the Canvas should be similar to that of Screen classes, so that visual continuity is retained when the application switches between low-level Canvas objects and high-level Screen objects.

Graphics and Text in Low-Level API

The Redrawing Scheme

Repainting is done automatically for all Screens , but not for Canvas ; therefore, developers utilizing the low-level API must ; understand its repainting scheme.

In the low-level API, repainting of Canvas is done asynchronously so that several repaint requests may be implemented within a single call as an optimization. This means that the application requests the repainting by calling the method repaint() of class Canvas. The actual drawing is done in the method paint() -- which is provided by the subclass Canvas -- and does not necessarily happen synchronously to repaint(). It may happen later, and several repaint requests may cause one single call to paint() . The application can flush the repaint requests by calling serviceRepaints().

As an example, assume that an application moves a box of width wid and height ht from coordinates (x1,y1) to coordinates (x2,y2), where x2>x1 and y2>y1 :

    // move coordinates of box
    box.x = x2;
    box.y = y2;

    // ensure old region repainted (with background)
    canvas.repaint(x1,y1, wid, ht);

    // make new region repainted
    canvas.repaint(x2,y2, wid, ht);

    // make everything really repainted
    canvas.serviceRepaints();
                 

The last call causes the repaint thread to be scheduled. The repaint thread finds the two requests from the event queue and repaints the region that is a union of the repaint area :

graphics.clipRect(x1,y1, (x2-x1+wid), (y2-y1+ht));
canvas.paint(graphics);
                

In this imaginary part of an implementation, the call canvas.paint() causes the application-defined paint() method to be called.

Drawing Model

All implementations MUST support double-buffered graphics. Graphics may be rendered either to the display's offscreen buffer or to an off-screen image buffer. The destination of rendered graphics depends on the origin of the Graphics object. A Graphics object for rendering to the display is passed to the Canvas or CustomItem object's paint() method. This is the only way to obtain a graphics object whose destination is the display. Furthermore, applications may draw by using this Graphics object only for the duration of the paint() method.

A Graphics object for rendering to an off-screen Image buffer may be obtained by calling the getGraphics() method on the desired Image. These Graphics objects may be held indefinitely by the application, and rendering operations may be performed with them at any time.

A 32-bit color model is provided with 8 bits each for the red, green, blue, and alpha components of a color. Not all devices support 32-bit resolution, so they will map colors and alpha values requested by the application into values available on the device. Facilities are provided in the Display class for obtaining device characteristics, such as whether color is available and how many distinct colors or gray levels are available. This enables applications to adapt their behavior to a device without compromising device independence.

The Graphics class has a current color and alpha level. These two values can be set with the following methods :

    Graphics.setAlpha(int alpha)
    Graphics.setAlphaColor(int ARGB)
    Graphics.setAlphaColor(int alpha, int red, int green, int blue)
    Graphics.setColor(int RGB)
    Graphics.setColor(int red, int green, int blue)
    Graphics.setGrayscale(int graylevel)
            

All geometric rendering, including lines, rectangles, text, and arcs, uses the current color and alpha. There is no background color; painting of any background must be performed explicitly by the application.

Two Porter-Duff blending modes are supported by the Graphics class. SRC_OVER is the default blending mode and blends the source pixel's color value on top of the destination pixel. If the source pixel is fully opaque, the destination pixel is effectively replaced with the source pixel. If the source pixel is fully transparent, the destination pixel is unchanged. If the source pixel is partially transparent, its color is blended with the color of the destination pixel. The opacity of the destination pixel cannot be reduced using this blending mode, and thus it is available for Graphics objects.

The SRC blending mode replaces the destination pixel with the source pixel's value, regardless of the source pixel's opacity. Both the color and the alpha value of the destination pixel are replaced with those of the source pixel, thus allowing the opacity of the destination pixel to be decreased as well as increased. For this reason, the SRC blending mode can only be used for Graphics objects that render to an Image with an alpha channel.

Coordinate System

The origin (0,0) of the available drawing area and images is in the upper-left corner of the display. The numeric values of the x-coordinates monotonically increase from left to right, and the numeric values of the y-coordinates monotonically increase from top to bottom. Applications may assume that horizontal and vertical distances in the coordinate system represent equal distances on the actual device display. If the shape of the pixels of the device is significantly different from square, the implementation of the UI will do the required coordinate transformation. A facility is provided for translating the origin of the coordinate system. All coordinates are specified as integers.

The coordinate system represents locations between pixels, not the pixels themselves. Therefore, the first pixel in the upper left corner of the display lies in the square bounded by coordinates (0,0), (1,0), (0,1), (1,1).

An application may inquire about the available drawing area by calling the following methods of Canvas :

public int getWidth();
public int getHeight();

Font Support

Each implementation MAY support a different set of system installed fonts. When an application requests a Font using a specific name, style and pixel size, the implementation will return a Font that most closely matches the request. An application may also use the Font class to query the list of available fonts.

To improve portability across devices, applications may use the following abstract attributes to request an appropriate Font without knowledge of the specific names or pixel sizes that are available on the device :

• Size: SMALL, MEDIUM, LARGE.
• Face: PROPORTIONAL, MONOSPACE, SYSTEM.
• Style: PLAIN, BOLD, ITALIC, UNDERLINED.

However, if an application needs to have complete control over text layout and appearance, it may use custom fonts that are loaded via an InputStream. Custom fonts may be packaged in the application's JAR and accessed as a named resource for this purpose. The application may also download a custom font, but it is responsible for persistently storing the font data on the device if required. Implementations MUST NOT automatically store downloaded font data between MIDlet invocations, and making downloaded fonts persistent (if needed) is solely an application's responsibility.

All implementations MUST support OpenType fonts with TrueType outlines. Implementations SHOULD support TrueType hinting and MAY support advanced typographic functions. Support for other font formats is optional.

Downloadable Fonts

MIDlets can use also custom fonts for the rendering of text content. Fonts may be packaged in a MIDlet suite's JAR or in the JARs of the LIBlets a MIDlet suite depends on. Fonts can also be downloaded at runtime and stored on the device in persistent storage for subsequent use (if required by the application). Implementations MUST NOT retain downloaded fonts between MIDlet invocations, but applications can store downloaded fonts in RMS Record Stores. It is the responsibility of a MIDlet to prepare and instantiate the fonts downloaded at runtime (and/or stored in RMS) by explicitly referencing a font resource using the Font.createFont method. Implementations MUST make all individual fonts available (whether downloaded or packaged) to all MIDlets in the MIDlet suite at runtime if the individual font file size does not exceed 200KB. Any individual fonts with a file size that exceeds 200KB MAY be discarded by an implementation.

Fonts that are packaged within a MIDlet Suite JAR or present in dependent LIBlet JARs SHOULD be declared using MIDlet-Font or LIBlet-Font attribute in their respective JAR manifests. Implementations MUST prepare all declared fonts for later instantiation; any such font can then be instantiated using static method calls (e.g. Font.getFont method). Fonts that are packaged but not declared in a JAR manifest will not be prepared by the implementation and can only be instantiated using the Font.createFont method. Applications are responsible for the management of all custom fonts not declared with this attribute.

Implementations MUST ensure that the availability and use of fonts packaged with a MIDlet suite in a JAR, packaged with any dependency LIBlets, or downloaded at runtime and created using createFont method are limited to the MIDlet's runtime execution environment. If a font packaged with a MIDlet or downloaded at runtime has the same font name as a system font available on a device, the downloaded or packaged font overrides the system font and MUST be used for text rendering purposes whenever a font is selected by name by a MIDlet that created it.

Threading Model

The UI API has been designed to be thread-safe. The methods may be called from callbacks, TimerTasks, or other threads created by the application. Also, the implementation generally does not hold any locks on objects visible to the application. This means that the applications' threads can synchronize with themselves and with the event callbacks by locking any object according to a synchronization policy defined by the application. One exception to this rule occurs with the Canvas.serviceRepaints method. This method calls and awaits completion of the paint method. Strictly speaking, serviceRepaints might not call paint directly, but instead it might cause another thread to call paint. In either case, serviceRepaints blocks until paint has returned. This is a significant point because of the following case. Suppose the caller of serviceRepaints holds a lock that is also needed by the paint method. Since paint might be called from another thread, that thread will block trying to acquire the lock. However, this lock is held by the caller of serviceRepaints, which is blocked waiting for paint to return. The result is deadlock. In order to avoid deadlock, the caller of serviceRepaints must not hold any locks needed by the paint method.

The UI API includes also a mechanism similar to other UI toolkits for serializing actions with the event stream. The method Display.callSerially requests that the run method of a Runnable object be called, serialized with the event stream. Code that uses serviceRepaints() can usually be rewritten to use callSerially(). The following code illustrates this technique:

class MyCanvas extends Canvas {
    void doStuff() {
        // <code fragment 1>
        serviceRepaints();
        // <code fragment 2>
        }
}
             

The following code is an alternative way of implementing the same functionality :

class MyClass extends Canvas implements Runnable {
        void doStuff() {
        // <code fragment 1>
        callSerially(this);
        }

        // called only after all pending repaints served
        public void run() {
        // <code fragment 2>;
        }
}
        

Text Truncation in UI Components

Many MIDP LCDUI graphical components can contain text (that is, an alphanumeric string) that is shown to the user. Examples of such components are List,TextBox, Alert, StringItem, Form, and Item. An implementation often needs to truncate such visible text because it does not fit in the designated space of a given UI component. In this case, an implementation MUST use an appropriate visual indication (for example an ellipsis symbol) to signal the user that the text is truncated. The actual symbol or symbols used to represent the truncated text depends on the locale that is currently selected in the device. However, the visual indication SHOULD be consistent with the visual indication used in the device’s native UI.

Activation of Idle Screen MIDlets

The application context of an idle screen MIDlet is the normal MIDlet. The IdleItem is an additional user interface for the MIDlet. The MIDlet can use the available Displays on the device in addition to the IdleItem on the idle screen of each Display that supports idle.

When an idle screen MIDlet is installed to the device, the platform SHOULD add it to the list of idle screen applications. This makes it possible for the user to select an idle screen MIDlet to be added to the idle screen. The MIDlet name and icon information SHOULD be used to identify the MIDlet in the list of idle screen applications. The system MAY restrict the number of idle screen MIDlets added to the idle screen.

When an idle screen MIDlet is added to the idle screen, the system MUST start the idle screen MIDlet if it is not already running. When the idle screen MIDlet is started it should call Display.setIdleItem to set the IdleItem for one or more Displays and be prepared to render content to it. The system MUST call the addedToDisplay method, announcing that the MIDlet's IdleItem has been added to the idle screen. The following list illustrates the steps that SHOULD be taken by the idle screen MIDlet when it is started.

1. Add IdleItem object to the idle screen with Display.setIdleItem method
2. If the MIDlet will use the normal Display then it should set a DisplayListener to be notified when the Displayable needs to be set
3. Handle the callback method IdleItem.addedToDisplay and render content to the idle screen when its paint method is called
4. When the idle screen MIDlet has been removed from the idle screen handle callback method IdleItem.removedFromDisplay

If an idle screen MIDlet has been added to the idle screen and it does not add any content to the idle screen, the system MAY remove the idle screen MIDlet from the idle screen. The MIDlet may be terminated.

If a MIDlet that has not announced itself as an idle screen MIDlet with the JAD or JAR Manifest attribute tries to add content to the idle screen, the system MUST ignore this request.

Implementation Notes

The implementation of a List or ChoiceGroup may include keyboard shortcuts for focusing and selecting the choice elements, but the use of these shortcuts is not visible to the application program.

In some implementations the UI components -- Screens and Items -- will be based on native components. It is up to the implementation to free the used resources when the Java objects are not needed anymore. One possible implementation scenario is a hook in the garbage collector of KVM.

@since MIDP 1.0