Canvas and CustomItem

Unlike high-level LCDUI components, the low-level components Canvas and CustomItem do not automatically implement touch functionality. Instead, you need to implement the functionality separately by receiving touch events for these components and then handling the events appropriately. On Series 40 touch devices, you can also use gesture events to implement the touch functionality.

To receive and handle touch events for Canvas or CustomItem:

  1. Use the following methods to check whether the platform supports touch events:

  2. In LCDUI, touch events are registered as pointer events. To receive these events, implement the following Canvas or CustomItem methods:

    • The pointerPressed method is called on touch down events ("pointer is pressed").

    • The pointerDragged method is called on drag events ("pointer is dragged").

    • The pointerReleased method is called on touch release events ("pointer is released").

    The corresponding coordinates are passed to the MIDlet. Top left is indicated as 0,0.

  3. Handle the touch events (pointer events) in the above methods, or use the above methods to call separately defined event handlers.

    For more information about the different event combinations that make up touch actions, see table Basic touch actions.

Canvas

Canvas supports the following touch features:

  • Graphics scaling alters the touch event coordinates according to the original size of the MIDlet (application attributes are needed for this).

  • If a Canvas has multiple commands assigned to it, touch down and hold on the Canvas opens a pop-up menu containing the commands. The pop-up menu corresponds to the context-specific Options menu of non-touch devices. The pop-up menu is disabled in full screen mode.

Touch devices can have only a few or no physical keys. If no softkeys are available on a Symbian device, MIDlet-defined commands for a Canvas are mapped to the virtual softkeys shown in the on-screen keypad. On Series 40 devices, the commands are mapped to the virtual softkeys shown at the bottom of the screen.

For more information about using Canvas, see section Canvas.

CustomItem

On Series 40 devices, by default, a CustomItem must be focused before it can receive further touch events (pointer events or gesture 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 component 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 FP 1.

For more information about using CustomItem, see section CustomItem.

© Nokia 2010.