Displayables and Commands

Form and Form Items

Supported touch events:

• Touch down and release on an unfocused and focusable Item changes focus. If the touch event has been on an editable text field (a DateField, for example), a touch input window is also opened (virtual keyboard).

• Dragging from Item to another moves focus on the Form. If dragging continues from Form area to status or control pane, the Form is scrolled as long as there is no touch release in status/control pane area and there is Form content to scroll. Dragging must start from an unfocused Form Item.

  • When dragging inside a Form it should be noted that touch release event will be delivered to that Form Item that originally received the touch down event. This may have some implications when an application creates internal scrolling for a Form Item (for example a CustomItem).

• The scrollbar supports touch UI.

• All Form Items support touch down and hold. The action opens a pop-up menu containing Item specific commands, if available In other words, it corresponds to a context specific options menu in a non-touch device.

All focusable Items gain focus on touch down events. Touch down and drag does not have effect in all Items, but when internal focus change is possible (ChoiceGroup, DateField) drag can be used. Gauge value can also be changed by dragging the thumb. Touch release is typically used for launching commands, toggling or mark/unmark functionality. Form has touch enabled scrollbar.

CustomItem works much like Canvas. GetInteractionModes function can be used to check whether touch is supported or not. Touch events are dispatched to the MIDlet and internal focus traversal can be implemented to interact with touch events.

The following should be noted about the default command functionality of Form Item:

List

Supported touch events:

• Touch down and release on an unfocused element or its selection graphic changes the focus and selection.

• Touch down and drag scrolls the List with highlight (focus changing).

• Touch down and hold opens a pop-up menu containing item specific commands, if available (corresponding to a context specific options menu in a non-touch device).

• On IMPLICIT List type: touch down and release on a focused list element activates the set select command.

For more information on List, see List implementation notes.

Alert

Supported touch events:

• Timed Alert is closed on touch down and release anywhere in the display area.

• If the Alert is modal and has at least one softkey associated with it, only touch down and release on the softkey closes the Alert.

• Touch down and hold opens a pop-up menu containing item specific commands, if available (corresponding to a context specific options menu in a non-touch device)

Alert has touch enabled scrollbar, if needed.

For more information on Alert, see Alert implementation notes.

TextBox/TextField

Supported touch events:

• 1st touch down and release on editable text field opens the touch input window (virtual keyboard).

• Cursor can be moved by touching the text area.

• Text can be selected by touch down and drag.

• Text can be edited by using touch input window.

• The scrollbar supports touch UI.

• Touch down and hold opens a pop-up menu containing item specific commands, if available (corresponding to a context specific options menu in a non-touch device)

• TextBox has touch enabled scrollbar

• In TextField text can be scrolled by touching the top or bottom most row. The text is scrolled one line up or down.

For more information on TextBox and TextField, see TextBox implementation notes.

Command

Supported touch events:

• Touch down and release on menu item executes it

• Touch down and drag on menu changes the highlighted menu item

• Touch release outside menu does nothing

Command menus have touch enabled scrollbar.

For more information on Commands, see Command implementation notes and section Command.

Canvas

Unlike with the high-level UI components listed above, Touch UI functions are not implemented automatically in Canvas. Instead, you need to implement them with the following methods:

• pointerPressed(int x, int y), pointerDragged(int x, int y) and pointerReleased(int x, int y) functions of Canvas class are called when touch down, drag and release events take place on the screen accordingly. Corresponding coordinates are passed to the MIDlet (top left is 0,0).

• hasPointerEvents and hasPointerMotionEvents can be used to check whether the device or the current Display supports touch events.

Other supported touch events:

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

• Touch down and hold opens a pop-up menu containing item specific commands, if available (corresponding to a context specific options menu in a non-touch device) except in full screen mode Canvas.

In a touch-enabled device there might be limited or no physical softkeys available. If no softkeys are available, the MIDlet defined commands in Canvas are mapped to the softkeys displayed in an on-screen keypad. For Canvas key mappings, game actions and on-screen keypads in touch enabled devices, see section On-screen keypad in Canvas.

For more information on Canvas, see Canvas implementation notes.