Programming Wireless Devices with the Java2 Platform

10.8 CustomItem

The abstract class CustomItem allows applications to create new visual and interactive elements that can be used in Forms. To do this, a new subclass of CustomItem is created: it is responsible for creating the visual representation for the Item, including sizing and rendering. The subclass fully controls what is presented within item area. It defines the colors, fonts, and graphics that are used, including rendering of special highlight and focus states the item may have. Only the label of the item is rendered by the device, but the label is always rendered outside the CustomItem content area.

A CustomItem can trigger notifications to the ItemStateListener of a Form in which the CustomItem is contained. This is done by calling the notifyStateChanged method inherited from Item.

Like all Items, CustomItems have the concept of minimum and preferred sizes. These sizes pertain to the total area of the Item, which includes space for the content, label, borders, and so forth. (See Section 10.9.4, "Item Sizing," for a full discussion of the areas and sizes of Items.) A CustomItem does not itself fully control this area. There is, however, a smaller region within the CustomItem called the content area that the CustomItem subclass paints and from which it receives input events.

A CustomItem subclass overrides the methods getMinContentHeight, getMinContentWidth, getPrefContentHeight, and getPrefContentWidth to return the minimum and preferred sizes for the content area. The device is responsible for calculating the minimum and preferred sizes for the whole item. The device also defines the actual content area space made available for CustomItem. The size of this area is given in calls to the methods sizeChanged and paint:

protected void sizeChanged(int w, int h)
protected abstract void paint(Graphics g, int w, int h)

The actual size might be smaller than the requested minimum content size if the device cannot allocate the space requested. For example, if no horizontal scrolling is available in a device, there is a device-specific maximum size for item width, which in turn affects the maximum content size for CustomItems.

If the minimum or preferred content area size changes, an application must call the method invalidate, and the subsequent calls to the size methods must return the new content area sizes. The method invalidate tells a device that it needs to perform its layout computation, which calls the content size methods to get new values based on the new contents of the CustomItem.

10.8.1 Interaction Modes

Each CustomItem is responsible for adapting its behavior to the interaction methods available on a target device. A CustomItem subclass needs to call the method getInteractionModes to inspect the interaction modes that are supported by a particular device. This method returns a bit mask of the supported modes with bits set or unset for the following modes:

• KEY_PRESS, KEY_RELEASE, and KEY_REPEAT for indicating the level of key press event support. Devices support either none of the key event modes, both press and release event modes, or all key event modes. It is not valid for a device to support key press events without supporting key release events.

• POINTER_PRESS, POINTER_RELEASE, and POINTER_DRAG for indicating the level of pointer event support. Similar to key events, devices support either none of the pointer event modes, both press and release event modes, or all of the pointer event modes.

• TRAVERSE_HORIZONTAL and TRAVERSE_VERTICAL for indicating support for internal traversal in a given direction, as discussed below.

10.8.2 Traversal

An implementation may support traversal inside a CustomItem; that is, the implementation may temporarily delegate the responsibility for traversal to the item itself. Even if there is only one traversal location inside the CustomItem, the item might want to support the internal traversal protocol so that it can perform specialized highlighting, animation, and so forth when the user has traversed into it.

The implementation indicates its support for traversal inside a CustomItem by setting one or both of the TRAVERSE_HORIZONTAL or TRAVERSE_VERTICAL bits in the value returned by getInteractionModes. If neither of these bits are set, the implementation is unwilling to let CustomItems traverse internally, or else the implementation does not support traversal at all. If the implementation does support traversal but has declined to permit traversal inside CustomItems, the implementation will supply its own highlighting outside the CustomItem's content area.

The CustomItem need not support internal traversal at all. It can do this by returning false to the initial call to the traverse method. (This is the default behavior if this method has not been overridden by the CustomItem.) If this occurs, the device must arrange for the user to be able to traverse onto and past this item. The device must also arrange for proper scrolling to take place, especially if the item size exceeds the height of the screen, regardless of whether internal traversal is occurring.

Refer to the documentation of the traverse method for a full specification of the required behavior and responsibilities of a CustomItem for performing internal traversal.