CustomItem is a Form component that has no predefined
appearance or behaviour. Practically, CustomItems are content area elements where it is possible to add user interaction
and visual content. MIDlets can extend the CustomItem class and provide necessary functionality such as painting or focus
handling.
Basically, a CustomItem can be considered
as a Canvas element in an otherwise high-level
UI environment. It can receive low-level key events and include custom
drawn graphics.
Faulty CustomItems in a Form only display a single Alert with the text "Application
error", regardless of how many CustomItems are
in the Form.
The standard navigation or arrow keys are used for CustomItem internal and external focus traversal (between Form items). With TRAVERSE_HORIZONTAL and TRAVERSE_VERTICAL fields, it is possible
to add internal traversal within the CustomItem. TRAVERSE_HORIZONTAL is not supported on devices
with only 2-way navigation.
Series 40 and Symbian devices also
support KEY_PRESS, KEY_RELEASE, and KEY_REPEAT interaction modes.
In general, the keys that are visible in Canvas to MIDP applications are also visible in CustomItem. The two exceptions in this are the navigation keys, which are used
for CustomItem internal and external focus traversal,
and a possible Selection key that is used for activating the Item default Command. These keys
are not visible as low-level key events.
If the CustomItem supports internal focus
traversal then it is displayed in the Form with
no additional border. Otherwise it is displayed in the Form surrounded by implementation specific border.
A Form containing a CustomItem object is set current Displayable and CustomItem's content remains blank although it should
be visible.
This issue can be avoided if Display.getDisplay is called at least once during the
MIDlet's lifecycle before creating the CustomItem, for example at the beginning of the MIDlet's constructor.
Note: CustomItem does not get low-level
key events even if there is no CommandListener. The command mapping is the same as in any Form Item. However, for backward compatibility to
Symbian releases prior to 3.2, it is possible to enable low-level
key event triggering from Selection key in CustomItem. If this feature is enabled, no Commands are
mapped to Selection key. Instead the relevant low-level key event
will be triggered. To enable this feature the following attribute
should be added to the JAD or manifest file of the Java application
with value true: Nokia-MIDlet-S60-Selection-Key-Compatibility. For more information, see section JAD and JAR manifest
attributes.
For an example on using CustomItem, see article Creating CustomItem in Java ME in the Nokia
Developer Wiki.