com.nokia.mid.ui
Interface TextEditorTouchControl

public interface TextEditorTouchControl

Touch-devices can use a virtual control-panel to replace physical keys, and to facilitate textual input. The purpose of this interface is to provide some level of access and control over such a panel, when using the TextEditor-API.

MIDlets can obtain an instance of this interface via the TextEditorExtensionAccess in the following way:

 TextEditor editor = com.nokia.mid.ui.TextEditor.createTextEditor("hello world", 50, TextField.ANY, 100, 100);
 TextEditorTouchControl touchControl = ((TextEditorExtensionAccess)editor).getTouchControl();
 if(touchControl!=null){
   // this is a touch-device
 }
 else{
   // this is a non-touch-device
 }
 

The instance is associated with the editor it has been obtained from, and controls only this editor.

Because a control-panel covers parts of the display which would otherwise be available to the application, MIDlets may choose to only display the panel at certain times, e.g. when the editor is focussed. This is possible with setPanelMode(int). Furthermore, a panel can be positioned anywhere an the display via setPanelPosition(int, int). This interface also allows to query the size of the panel, so that applications can integrate it into the Canvas.

On touch-devices, the platform can make use of pointer-input to let the user interact with a TextEditor on a Canvas, without that the application knows about this. For example, if the user taps with his stylus or finger somewhere inside a visible and focussed TextEditor, the MIDlet might not receive any notification about this via the Canvas-methods pointerPressed, pointerDragged or pointerReleased. Instead, the platform could change the position of the cursor and generate the according event for the editors TextEditorListener. Or it may even just ignore this event completely. In general, an application should not expect to receive any pointer-events after a "press" inside a focussed TextEditor. Under certain circumstances however, for example as a response to the TextEditorListener.ACTION_TRAVERSE_OUT_SCROLL_UP or TextEditorListener.ACTION_TRAVERSE_OUT_SCROLL_DOWN event, an application can decide at any time to override this behaviour, and force the platform to deliver all subsequent pointer-events to the Canvas. This can be done with setTouchEnabled(boolean). Note that a TextEditor which has been touch-disabled this way will not be able to perform any interaction like cursor-positioning or scrolling via touch-input, until is has been enabled again.

Field Summary

static int	ACTION_PANEL_MOVED Event to indicate that the keypad/control-panel has been moved by the user
static int	PANEL_FIXED_POSITION Constant to enable the display of a keypad/control-panel.
static int	PANEL_FLOATING Constant to enable the display of a keypad/control-panel.
static int	PANEL_OFF Constant to disable the display of a keypad/control-panel

Method Summary

int	getPanelHeight() Gets the height of the panel
int	getPanelMode() Gets the current panel-mode
int	getPanelWidth() Gets the width of the panel
int	getPanelX() Gets the current x-position of the panel on the display
int	getPanelY() Gets the current y-position of the panel on the display
boolean	isTouchEnabled() Gets the current touch-enabled state
void	setCaret(int x, int y) Sets the caret as close as possible to a given x/y location.
void	setPanelMode(int mode) Controls the behaviour of the virtual keypad/control-panel, if the device provides one.
void	setPanelPosition(int x, int y) Sets the position of the panel on the display.
void	setTouchEnabled(boolean enabled) Specifies whether or not the editor will receive touch-events.

Field Detail

PANEL_OFF

static final int PANEL_OFF

Constant to disable the display of a keypad/control-panel

See Also:

Constant Field Values

PANEL_FIXED_POSITION

static final int PANEL_FIXED_POSITION

Constant to enable the display of a keypad/control-panel. In this mode the user cannot change the position of the panel, however the MIDlet can still do so via setPanelPosition(int, int)

See Also:

Constant Field Values

PANEL_FLOATING

static final int PANEL_FLOATING

Constant to enable the display of a keypad/control-panel. In this mode, the user can change the position of the panel of the display e.g. by dragging, if this is supported by the device. Changes to the position will generate the ACTION_PANEL_MOVED-event. The current panel-position is provided via getPanelX() and getPanelY()

See Also:

Constant Field Values

ACTION_PANEL_MOVED

static final int ACTION_PANEL_MOVED

Event to indicate that the keypad/control-panel has been moved by the user

See Also:

Constant Field Values

Method Detail

setPanelMode

void setPanelMode(int mode)

Controls the behaviour of the virtual keypad/control-panel, if the device provides one. This is a hint which may be disregarded if the device does not support a virtual keypad/control-panel.

Parameters:

mode - One of PANEL_OFF PANEL_FIXED_POSITION or PANEL_FLOATING

getPanelMode

int getPanelMode()

Gets the current panel-mode

Returns:

the mode, see setPanelMode(int)

setPanelPosition

void setPanelPosition(int x,
                      int y)

Sets the position of the panel on the display.

Parameters:

x - x-position of the keypad

y - y-position of the keypad

getPanelWidth

int getPanelWidth()

Gets the width of the panel

Returns:

the width

getPanelHeight

int getPanelHeight()

Gets the height of the panel

Returns:

the height

getPanelX

int getPanelX()

Gets the current x-position of the panel on the display

Returns:

the x-coordinate

getPanelY

int getPanelY()

Gets the current y-position of the panel on the display

Returns:

the y-coordinate

setTouchEnabled

void setTouchEnabled(boolean enabled)

Specifies whether or not the editor will receive touch-events. This is enabled by default. An editor with touch-event disabled won't be able to perform any touch-related functionality such as scrolling or positioning the cursor. It may however still be controlled via the virtual keypad/control-panel if that is enabled, or receive other input e.g. via physical keys

Parameters:

enabled - true to enabled touch-event, false to disable

isTouchEnabled

boolean isTouchEnabled()

Gets the current touch-enabled state

Returns:

true if the editor is touch-enabled, false otherwise

setCaret

void setCaret(int x,
              int y)

Sets the caret as close as possible to a given x/y location. This is a hint to the implementation that may be disregarded.

Parameters:

x - new x-coordinate for the caret, relative to the editors origin

y - new y-coordinate for the caret, relative to the editors origin