×

CustomItem

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.

Interaction modes

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.

Nokia Asha and Series 40 software platform 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.

On touch enabled devices, by default, a CustomItem must be focused before it can receive further touch events (pointer events or gestures events). In other words, the user must first tap the unfocused CustomItem or the MIDlet must first focus it by calling the Display.setCurrentItem method, before the content of the CustomItem can receive touch events. You can change this behavior with the LCDUIUtil.setObjectTrait method:

  • If you want the first touch event on an unfocused CustomItem to both focus the element and register the touch event for the content, call setObjectTrait as follows:

    // Import class com.nokia.mid.ui.LCDUIUtil
    
    // Create the CustomItem
    CustomItem customItem = new CustomItem("customItem");
    
    // Set the CustomItem to use single tap interaction,
    // so that it does not need to be focused first
    setObjectTrait(customItem, "nokia.ui.s40.item.direct_touch", Boolean(true));
    
  • If you want to revert back to the default behavior, whereby the unfocused CustomItem must be focused first, call setObjectTrait as follows:

    // Set the CustomItem to use focus and select,
    // so that it needs to be focused first
    setObjectTrait(customItem, "nokia.ui.s40.item.direct_touch", Boolean(false));
    

The nokia.ui.s40.item.direct_touch trait is supported since Series 40 6th Edition Feature Pack 1.

The CustomItem component can receive pointer with the methods pointerPressed, pointerDragged and pointerReleased, similarly to Canvas components. For more information see Touch interaction in Canvas and CustomItem.

Known issues

  • 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.

For an example on using CustomItem, see article Creating CustomItem in Java ME in the Nokia Developer Wiki.


Last updated 11 December 2013

Back to top