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 Forum Nokia wiki.