package

The UI API provides a set of features for implementation of user interfaces for MIDP applications.

## User Interface

The main criteria for the MIDP have been drafted 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 to the native applications so that the user finds them easy to use.

Given the capabilities of devices that will implement the MIDP and the above requirements, the MIDPEG decided not to simply subset the existing Java UI, which is the Abstract Windowing Toolkit (AWT). Reasons for this decision include:

- Although AWT was designed for desktop computers and optimized to these devices, it also suffers from assumptions based on this heritage.
- When a user interacts with AWT, event objects are created dynamically. These objects are short-lived and exist only until each associated event is processed by the system. At this point, the event object becomes garbage and must be reclaimed by the system's garbage collector. The limited CPU and memory subsystems of a MID typically cannot handle this behavior.
- AWT has a rich but desktop-based feature set. This feature set includes support for features not found on MIDs. For example, AWT has extensive support for window management (e.g., overlapping windows, window resize, etc.). MIDs have small displays which are not large enough to display multiple overlapping windows. The limited display size also makes resizing a window impractical. As such, the windowing and layout manager support within AWT is not required for MIDs.
- AWT assumes certain user interaction models. The component set of AWT was designed to work with a pointer device (e.g., a mouse or pen input). As mentioned earlier, this assumption is valid for only a small subset of MIDs since many of these devices have only a keypad for user input.

### Structure of the MIDP UI API

The MIDP UI is logically composed of two APIs: the high-level and the low-level.

The high-level API is designed for business applications whose client parts run on MIDs. For these applications, portability across devices is important. To achieve this portability, the high-level API employs a high level of abstraction and provides very little control over look and feel. This abstraction is further manifested in the following ways:

- The actual drawing to the MID's display is performed by the implementation. Applications do not define 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 is not aware of 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 {@link javax.microedition.lcdui.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. Some applications also need to access special, device-specific features. 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 like key presses and releases.
- Access concrete keys and other input devices.

The classes that provide the low-level API are {@link javax.microedition.lcdui.Canvas} and {@link javax.microedition.lcdui.Graphics}.

Applications that program to the low-level API are not guaranteed to be portable, since the low-level API provides the means to access details that are specific to a particular device. If the application does not use these features, it will be portable. It is recommended that applications use only the platform-independent part of the low-level API whenever 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 central abstraction of the MIDP's UI is a `Displayable` object, which encapsulates device-specific graphics rendering with user input. Only one `Displayable` may be visible at a time, and and the user can see and interact with only contents of that `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.

The class `Display` acts as the display manager that is instantiated for each active `MIDlet` and provides methods to retrieve information about the device's display capabilities. A `Displayable` is made visible by calling the `setCurrent()` method of `Display`. When a `Displayable` is made current, it replaces the previous `Displayable`.

#### Class Overview

It is anticipated that most 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 this class (`Form` ) 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.

#### 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 expects the following conditions from the application management software:

- `getDisplay()` is callable starting from `MIDlet`'s constructor until `destroyApp()` has returned.
- The `Display` object is the same until `destroyApp()` is called.
- The `Displayable` object set by `setCurrent()` is not changed by the application manager.

The application manager assumes that the application behaves as follows with respect to the `MIDlet` events:

- `startApp` - The application may call `setCurrent()` for the first screen. The application manager makes `Displayable` really visible when `startApp()` returns. Note that `startApp()` can be called several times if `pauseApp()` is called in between. This means that initialization should not take place, and the application should not accidentally switch to another screen with `setCurrent()` .
- `pauseApp` - The application should release as many threads as possible. Also, if starting with another screen when the application is re-activated, the new screen should be set with `setCurrent()` .
- `destroyApp` - The application may delete created objects.

### Event Handling

User interaction causes 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 {@link javax.microedition.lcdui.Canvas#serviceRepaints Canvas.serviceRepaints} method is called. This method causes the 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:

- {@link javax.microedition.lcdui.Canvas#hideNotify Canvas.hideNotify}
- {@link javax.microedition.lcdui.Canvas#keyPressed Canvas.keyPressed}
- {@link javax.microedition.lcdui.Canvas#keyRepeated Canvas.keyRepeated}
- {@link javax.microedition.lcdui.Canvas#keyReleased Canvas.keyReleased}
- {@link javax.microedition.lcdui.Canvas#paint Canvas.paint}
- {@link javax.microedition.lcdui.Canvas#pointerDragged Canvas.pointerDragged}
- {@link javax.microedition.lcdui.Canvas#pointerPressed Canvas.pointerPressed}
- {@link javax.microedition.lcdui.Canvas#pointerReleased Canvas.pointerReleased}
- {@link javax.microedition.lcdui.Canvas#showNotify Canvas.showNotify}
- {@link javax.microedition.lcdui.Canvas#sizeChanged Canvas.sizeChanged}
- {@link javax.microedition.lcdui.CommandListener#commandAction CommandListener.commandAction}
- {@link javax.microedition.lcdui.CustomItem#getMinContentHeight CustomItem.getMinContentHeight}
- {@link javax.microedition.lcdui.CustomItem#getMinContentWidth CustomItem.getMinContentWidth}
- {@link javax.microedition.lcdui.CustomItem#getPrefContentHeight CustomItem.getPrefContentHeight}
- {@link javax.microedition.lcdui.CustomItem#getPrefContentWidth CustomItem.getPrefContentWidth}
- {@link javax.microedition.lcdui.CustomItem#hideNotify CustomItem.hideNotify}
- {@link javax.microedition.lcdui.CustomItem#keyPressed CustomItem.keyPressed}
- {@link javax.microedition.lcdui.CustomItem#keyRepeated CustomItem.keyRepeated}
- {@link javax.microedition.lcdui.CustomItem#keyReleased CustomItem.keyReleased}
- {@link javax.microedition.lcdui.CustomItem#paint CustomItem.paint}
- {@link javax.microedition.lcdui.CustomItem#pointerDragged CustomItem.pointerDragged}
- {@link javax.microedition.lcdui.CustomItem#pointerPressed CustomItem.pointerPressed}
- {@link javax.microedition.lcdui.CustomItem#pointerReleased CustomItem.pointerReleased}
- {@link javax.microedition.lcdui.CustomItem#showNotify CustomItem.showNotify}
- {@link javax.microedition.lcdui.CustomItem#sizeChanged CustomItem.sizeChanged}
- {@link javax.microedition.lcdui.CustomItem#traverse CustomItem.traverse}
- {@link javax.microedition.lcdui.CustomItem#traverseOut CustomItem.traverseOut}
- {@link javax.microedition.lcdui.Displayable#sizeChanged Displayable.sizeChanged}
- {@link javax.microedition.lcdui.ItemCommandListener#commandAction ItemCommandListener.commandAction}
- {@link javax.microedition.lcdui.ItemStateListener#itemStateChanged ItemStateListener.itemStateChanged}
- `Runnable.run` resulting from a call to {@link javax.microedition.lcdui.Display#callSerially Display.callSerially}

Note that {@link java.util.Timer Timer} events are not considered UI events. Timer callbacks may run concurrently with UI event callbacks, although {@link java.util.TimerTask 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 {@link javax.microedition.lcdui.Display#callSerially 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` .

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 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`.

`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.

#### 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.

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.

#### 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.

#### 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 last call, `keyRepeated` , is not necessarily available in all devices. The applications can check the availability of repeat actions by calling the following method of the `Canvas` :

        public static boolean hasRepeatEvents();

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 game 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();

#### 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

The primary drawing operation is pixel replacement, which is used for geometric rendering operations such as lines and rectangles. With offscreen images, support for full transparency is required, and support for partial transparency (alpha blending) is optional.

A 24-bit color model is provided with 8 bits each for the red, green, and blue components of a color. Not all devices support 24-bit color, so they will map colors requested by the application into colors 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 gray levels are available. This enables applications to adapt their behavior to a device without compromising device independence.

Graphics may be rendered either directly to the display 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` 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 requests may be issued on these graphics objects at any time.

The `Graphics` class has a current color that is set with the `setColor()` method. All geometric rendering, including lines, rectangles, and arcs, uses the current color. The pixel representing the current color replaces the destination pixel in these operations. There is no background color. Painting of any background be performed explicitly by the application using the `setColor()` and rendering calls.

Support for full transparency is required, and support for partial transparency (alpha blending) is optional. Transparency (both full and partial) exists only in off-screen images loaded from PNG files or from arrays of ARGB data. Images created in such a fashion are immutable in that the application is precluded from making any changes to the pixel data contained within the image. Rendering is defined in such a way that the destination of any rendering operation always consists entirely of fully opaque pixels.

#### 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 static final int getWidth();
        public static final int getHeight();

#### Font Support

An application may request one of the font attributes specified below. However, the underlying implementation may use a subset of what is specified. So it is up to the implementation to return a font that most closely resembles the requested font.

Each font in the system is implemented individually. A programmer will call the static `getFont()` method instead of instantiating new `Font` objects. This paradigm eliminates the garbage creation normally associated with the use of fonts.

The `Font` class provides calls that access font metrics. The following attributes may be used to request a font (from the `Font` class):

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

### Concurrency

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 {@link javax.microedition.lcdui.Canvas#serviceRepaints 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 {@link javax.microedition.lcdui.Display#callSerially 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>;
            }
        }

### 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