An earlier J2ME Tech Tip, Using Custom Items in MIDP 2.0,
at http://developers.sun.com/mobility/midp/ttips/customitem/,
described the basic development of custom user interface (UI) components in MIDP 2.0.
That tip showed that a custom UI component extends the javax.microedition.lcdui.CustomItem
class and implements a set of abstract methods that determine the component's recommended
dimensions and how the item paints itself.
It didn't discuss, however, how a custom item interacts with the user.
The MIDP specification supports a variety of user-interaction methods.
A keyboard or keypad is required, but a device may support other input methods, such as a stylus.
To be truly portable, an application cannot make assumptions about what methods are available.
This uncertainty isn't a problem for the predefined UI components because the device's
MIDP implementation maps them to the best input methods available to it,
but it does pose a challenge for developers writing custom components.
Here is where the concept of interaction modes comes into play.
Interaction modes identify the ways that the implementation enables users to interact with an item.
Currently three types of interaction modes are defined: keyboard, pointer, and traversal.
The keyboard modes indicate whether an item can receive events when a key is pressed,
released, or repeated.
The pointer modes indicate whether an item can receive events when a pointer is pressed,
released, or dragged.
The traversal modes indicate whether an item receives internal traversal events,
such as a change of input focus or selection, that are triggered by the device's standard
traversal mechanisms.
Some modes are interdependent.
For example, the key-repeat mode is supported only if both the key-press and key-release
modes are supported.
At runtime, a component can discover which interaction modes are available by calling
the protected method getInteractionModes(), which returns a bitmask.
The CustomItem class defines the constants KEY_PRESS, KEY_RELEASE, KEY_REPEAT, POINTER_PRESS,
POINTER_RELEASE, POINTER_DRAG, TRAVERSE_HORIZONTAL, and TRAVERSE_VERTICAL to represent
each possible mode.
This sample code finds out whether pointer-press events are available:
If the POINTER_PRESS mode is available, the item's pointerPressed() method may be called
in response to user input.
Each of the key and pointer modes has a corresponding event method: keyPressed(),
keyReleased(), keyRepeated(), pointerPressed(), pointerReleased(), and pointerDragged().
Each of these methods is identical to the method of the same name defined in the Canvas class.
Traversal events cause the traverse() method to be invoked.
Traversal is a complex topic, and will be discussed in a separate tech tip.
No matter what interaction modes are available, custom items can always be associated with
Command objects using the addCommand() and setDefaultCommand()
methods defined by CustomItem's base class, Item.
These commands are context-sensitive, available to the user only when the item in question is selected.
The MIDP specification mentions a common design pattern of using a command to launch a
custom editing screen.
To do this, create a Command object and call setDefaultCommand() in
the item's constructor:
You'll need to implement the ItemCommandListener interface and have the object listen
for the triggering of the command object.
In your commandAction() method you must add the code to bring up the editing screen,
usually implemented as an inner class with access to the item's internal state.
The editing screen can do whatever is appropriate for the item.
