Custom Items

A custom item is an item created by the app developer to be added to a form screen. For example, an app developer could use a custom item to create a media player, a map viewer, a combo box, and so on. Like a canvas (covered in ) a custom item must be implemented carefully so that it is portable. It can be a valuable component if implemented carefully. Screenshot shows a custom item, which shows a theater seating chart so that the user can choose a seat.

Screenshot A Custom Item on a Form

app Developers

Strongly Recommend: Provide a consistent visual appearance by using the same colors and fonts as the system. The system makes these attributes available, as well as the stroke style that it uses for drawing borders. (See Programming Wireless Devices with the Java 2 Platform, Micro version [17] for more information.)

Strongly Recommend: Supply minimum and preferred sizes to the form. Ensure that your item is usable at the minimum size. In addition to the minimum and preferred size you must provide a content size, so that the MIDP implementation can determine the bounding box of the custom item on the form.

MIDP Implementors

Strongly Recommend: Place labels outside the bounding box of the custom item. This enables you to maintain a consistent user interface for labels on form.

Traversal Into, Through, and Out of Custom Items

Since there is no way for a MIDP implementation to tell whether a custom item is interactive, it must support traversal into and out of custom items.

MIDP Implementors

Recommend: When a user traverses to a custom item, you should highlight it in case it is interactive. The visual representation of the highlight needs to be around but not on the custom item. It is possible that drawing a highlight on top of the custom item might interfere with its use. Screenshot shows a custom item with a traversal highlight.

Screenshot Custom Item with a Traversal Highlight

You can enable custom items to perform internal traversal, but you are not required to give custom items this option.

Strongly Recommend: Determine and publish whether your MIDP implementation will support internal traversal for custom items.

Strongly Recommend: If you support internal traversal for custom items, always check whether traversal is occurring. The developer supplies information on whether the traversal state within the custom item has changed with the user's last traversal action. If the custom item indicates that it is not responding to the traversal action, you should traverse to the next item on the form, if possible. (If the custom item is the first or last item on the form, it may not be possible for you to traverse to the next item. The user may have traversed as far as possible in the requested direction.)

app Developers

You can, but are not required to, have your custom items support traversal. If there is no traversal possible within the custom item, the app developer can let the MIDP implementation know this (through a method's return value; see Programming Wireless Devices with the Java 2 Platform, Micro version [17] for more information). The implementation will then continue the traversal to the next item on the form.

Strongly Recommend: If you support traversal within your custom items' content, provide users with obvious feedback so that they know where they are in the custom item. (See "Traversing and Scrolling Forms" on page 82 for advice on how to handle traversal through content.)

Strongly Recommend: If you support traversal within your custom item, you must ensure that the user can traverse into and out of it. Test your MIDlet thoroughly to ensure that you have not created a trap that enables users to traverse into, but not out of, your custom item.

Strongly Recommend: If your custom item contains content that the user can interact with, then provide clear highlight feedback to the user and support traversal within the content. (See "Traversal and Selection Highlighting" on page 85 and "Traversal Into, Through, and Out of Custom Items" on page 120 for more information.)

Interaction Modes for Custom Items

The MIDP 2.0 Specification [19] defines interaction modes for a custom item. They are a way for the MIDP implementation to inform the custom item of its capabilities. There are interaction mode constants for traversal, keypad input, and pointer input. If a MIDP implementation supports traversal within a custom item, it informs the app by using either the TRAVERSE_HORIZONTAL or TRAVERSE_VERTICAL constant, or both. If a MIDP implementation supports keypad input for custom items, it indicates this by using one or more of the constants KEY_PRESS, KEY_RELEASE, and KEY_REPEATED.

MIDP Implementors

Strongly Recommend: Determine and publish whether you will support keypad input to a custom item. You are not required to support it at all, but if you support key release events, you must also support key press events. Similarly, if you support key repeated events, you must also support key press and key release events.

Strongly Recommend: If you support keypad input, you must be able to deliver events for the phone keypad keys. (That is, you must map the phone keypad events onto user actions, and deliver the events to the app.)

Strongly Recommend: If you support keypad input, you must be able to map keypad input onto game actions. You are also permitted to provide access to device-specific key events.

The set of keys and the key events available to a custom item may differ from what is available on a canvas, as may the mapping between key codes and game actions. For example, if your device supports traversal, you might use the left, right, up, and down keys for traversal instead of delivering these key events to custom items. You might also change which key events are available to an app depending on whether the custom item has a command associated with it. If a MIDP implementation supports touch input, it indicates this by using one or more of the constants POINTER_PRESS, POINTER_RELEASE, and POINTER_DRAG.

Strongly Recommend: Determine and publish whether you will support touch input to a custom item. You are not required to support touch input to a custom item. If you do support pointer release events, however, you must also support pointer press events. Similarly, if you support pointer drag events, you must also support pointer press and pointer release events.

The MIDP Reference Implementation supports all interaction modes except horizontal traversal and touch input. It maps the Select key to the default command if there is one associated with the custom item.

Strongly Recommend: Using different buttons to activate the default commands of different items is likely to result in very poor usability. Ideally, activating a custom item should be consistent with the way other form items are activated.

Strongly Recommend: Consider the behaviors you provide to other items on a form when you choose which interaction modes to make available to a custom item. Indiscriminately mixing interaction modes can result in serious usability problems.

app Developers

Strongly Recommend: Design your custom item so that it indicates to users how to use the interaction modes. For example, provide Help screens. Users will need clear hints to understand how to operate a custom item.

Recommend: Have users edit your custom item in place on the form (using one or more interaction modes) or off the form. You should support both modes to ensure that the item can be edited across a variety of platforms.

For example, you might implement a custom item that a user can edit in place using touch input. At runtime, you should query the system to determine whether it supports your interaction mode. If it does, you can have the user edit the custom item in place; otherwise, you can have the user edit the item off the form.

Consider: If you want the user to be able to edit your custom item with full interaction, you could make the custom item display-only and use a canvas as an offscreen editor. (Canvases are covered in .) This could result in a more consistent user interface across devices, though potentially more complex to interact with.

If you do this, use an item-specific abstract command to invoke a separate editing screen. Make it the custom element's default command so that it is easy and fast to use. When the user issues a command on the Editing screen that indicates that editing is complete (or canceled), you can incorporate any edits into the custom item, and return to the form.

MIDP Implementors

Strongly Recommend: If there is a default command assigned to a custom item, determine which key the user must press to initiate the command. The set of keys and the key events available to a custom item may differ from what is available on a canvas.