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


Copyright © 2012 Nokia Corporation. All rights reserved.

Nokia is registered trademark of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Oracle Corporation. Other product and company names mentioned herein may be trademarks or trade names of their respective owners. This document is confidential information of Nokia Corporation.

Disclaimer
The information in this document is provided "as is," with no warranties whatsoever, including any warranty of merchantability, fitness for any particular purpose, or any warranty otherwise arising out of any proposal, specification, or sample. Furthermore, information provided in this document is preliminary, and may be changed substantially prior to final release.

Nokia Corporation disclaims all liability, including liability for infringement of any proprietary rights, relating to this document and implementation of any information presented in this document.

Nokia Corporation retains the right to make changes to this document at any time, without notice.

License
Subject to above disclaimer, a license is hereby granted to use this documentation solely under existing Limited License Agreement and non-disclosure agreement between the companies for the agreed application development for Series 40 Nokia phones. No other licenses e.g. to any intellectual property rights are granted herein. Any use of the screen shots of this documentation, including any icons thereof, is subject to Nokia's prior written approval.