com.nokia.mid.ui
Interface S60TextEditor

public interface S60TextEditor

S60 platform specific extensions to TextEditor. These methods are only available in S60 Java Runtime.

TextEditor does not support DSA over its area. Playing video or using camera over TextEditor area can lead to artifacts on screen.

Editing state indicators

By default, the implementation uses platform specific indicators for the TextEditor. Typically these indicators are shown in the status pane and the visibility is related to the focus of the associated TextEditor. When the associated editor is focused, the platform displays the editing state indicators for the user and when focus is lost from the editor the indicators are hidden.

The application can also choose to control the input indicators if needed. In this case, the visibility and position needs to be controlled separately when focusing the associated editor. It should be noted that if no indicators are shown to the user, the usability maybe diminished especially with complex input methods.

When using custom indicator position, the background color of the indicator area is equal to the associated TextEditor's background color.

Touch input methods

The application has a possibility to control the touch input methods with this class. It is possible to set the disabled touch input modes and the preferred touch mode if needed. It must be noted that supported touch input modes depend on the used device thus some of the touch modes cannot be set as preferred or enabled.

Since:

1.4

See Also:

TextEditor

Field Summary

static int	ACTION_VIRTUAL_KEYBOARD_CLOSE Indicates that the touch screen virtual keyboard is closed.
static int	ACTION_VIRTUAL_KEYBOARD_OPEN Indicates that the touch screen virtual keyboard is opened.
static int	TOUCH_INPUT_ALL_AVAILABLE Indicates that all input methods are available.
static int	TOUCH_INPUT_FSC Full screen handwriting recognition
static int	TOUCH_INPUT_FSQ Full screen QWERTY keyboard
static int	TOUCH_INPUT_HWR Handwriting recognition
static int	TOUCH_INPUT_ITUT Alphanumeric keyboard with ITU-T input
static int	TOUCH_INPUT_MINI_ITUT Mini ITU-T for Japanese devices
static int	TOUCH_INPUT_VKB Virtual QWERTY keyboard

Method Summary

int	getDisabledTouchInputModes() By default all supported touch input modes are available.
int[]	getIndicatorSize() Gets the size of the area needed for drawing the input indicators.
int	getPreferredTouchMode() Gets the preferred touch input mode.
boolean	isTouchEnabled() Gets the current touch-enabled state
void	setCaretXY(int x, int y) Sets the caret in the Editor at x, y location.
void	setDefaultIndicators() Resets the implementation provided input indicators to their default position.
void	setDisabledTouchInputModes(int touchInputModes) Disables one or multiple touch input modes from use.
void	setIndicatorLocation(int x, int y) If the default indicator location is not used then sets the drawing location for input indicators relative to the TextEditor's parent.
void	setIndicatorVisibility(boolean visible) By default indicators visibility is set to true and they are made visible when the associated TextEditor is focused.
void	setPreferredTouchMode(int touchInputModes) Set the preferred touch input mode overriding the device default preferred mode.
void	setTouchEnabled(boolean enabled) Specifies whether or not the editor will receive touch-events.

Field Detail

TOUCH_INPUT_ALL_AVAILABLE

public static final int TOUCH_INPUT_ALL_AVAILABLE

Indicates that all input methods are available.

Can be used in setDisabledTouchInputModes(int).

See Also:

Constant Field Values

TOUCH_INPUT_HWR

public static final int TOUCH_INPUT_HWR

Handwriting recognition

See Also:

Constant Field Values

TOUCH_INPUT_VKB

public static final int TOUCH_INPUT_VKB

Virtual QWERTY keyboard

See Also:

Constant Field Values

TOUCH_INPUT_FSQ

public static final int TOUCH_INPUT_FSQ

Full screen QWERTY keyboard

See Also:

Constant Field Values

TOUCH_INPUT_ITUT

public static final int TOUCH_INPUT_ITUT

Alphanumeric keyboard with ITU-T input

See Also:

Constant Field Values

TOUCH_INPUT_FSC

public static final int TOUCH_INPUT_FSC

Full screen handwriting recognition

See Also:

Constant Field Values

TOUCH_INPUT_MINI_ITUT

public static final int TOUCH_INPUT_MINI_ITUT

Mini ITU-T for Japanese devices

See Also:

Constant Field Values

ACTION_VIRTUAL_KEYBOARD_OPEN

public static final int ACTION_VIRTUAL_KEYBOARD_OPEN

Indicates that the touch screen virtual keyboard is opened.

See Also:

Constant Field Values

ACTION_VIRTUAL_KEYBOARD_CLOSE

public static final int ACTION_VIRTUAL_KEYBOARD_CLOSE

Indicates that the touch screen virtual keyboard is closed.

See Also:

Constant Field Values

Method Detail

setIndicatorLocation

public void setIndicatorLocation(int x,
                                 int y)

If the default indicator location is not used then sets the drawing location for input indicators relative to the TextEditor's parent.

The anchor point given is relative to the upper left corner of the Canvas. The location may be outside the TextEditor boundaries. The z-order of the indicators is the same as TextEditor textual content. If indicators and the editor content overlap indicators are rendered on top of the editor content.

The application should first query the size of the input indicators with getIndicatorSize() method to determine that the indicators will not be clipped outside the available display area when drawn to the requested location.

If there are no indicators present, the usability of complex device specific input methods may be compromised.

Parameters:

x - the x coordinate of the anchor point, in pixels.

y - the y coordinate of the anchor point, in pixels.

setDefaultIndicators

public void setDefaultIndicators()

Resets the implementation provided input indicators to their default position.

This position may be outside the area of parent in case the default position is in status area. In this case if the status area is missing (full screen mode Canvas) the default position is inside the parent area e.g. on top of the editor. When default position is in use the TextEditor automatically positions the indicators relative to the TextEditor even when TextEditor location is changed. However, client is responsible of making sure indicators are visible inside the parent area positioning TextEditor so that indicators fit to the visible area e.g. on top of the TextEditor. Positioning TextEditor directly on top of Canvas may mean that indicators in the default position are not visible.

Throws:

java.lang.IllegalStateException - If the TextEditor is not added to Canvas

setIndicatorVisibility

public void setIndicatorVisibility(boolean visible)

By default indicators visibility is set to true and they are made visible when the associated TextEditor is focused.

If the application controls the position of the indicators, those can be explicitly made not visible by calling setIndicatorVisibility(false). Indicators are never visible if TextEditor itself is not visible so having indicator visibility set to true does not make them visible unless editor itself is set visible.

Parameters:

visible - controls indicator visibility state

See Also:

setIndicatorLocation(int, int), setDefaultIndicators()

getIndicatorSize

public int[] getIndicatorSize()

Gets the size of the area needed for drawing the input indicators.

The returned array contains two integers for width (array index 0) and height (array index 1) of the indicator graphics. Size (0,0) is returned if the device UI does not use any input indicators in the text editors or if the indicators are curretly positioned outside parent area e.g. in status area. This happens if setIndicatorLocation(int x, int y) has not been ever called for the editor, or if setDefaultIndicators() has been called.

Returns:

the width and height of area needed for drawing input indicators

See Also:

setDefaultIndicators()

setDisabledTouchInputModes

public void setDisabledTouchInputModes(int touchInputModes)

Disables one or multiple touch input modes from use.

User is not able to switch to the disable touch input modes. Multiple touch input modes may be combined together in touchInputMode parameter using bitwise or operator. The method does not have any impact if called in non-touch device. A device may not support all touch input modes specified. Specifying not supported input modes is silently ignored.

The possible values are defined in the class with TOUCH_INPUT_* starting constant values.

Parameters:

touchInputModes - bitwise or combined list of disabled touch input modes

Throws:

java.lang.IllegalArgumentException - if the given input modes are not valid.

See Also:

setPreferredTouchMode(int), getDisabledTouchInputModes()

getDisabledTouchInputModes

public int getDisabledTouchInputModes()

By default all supported touch input modes are available. Returns the disabled touch input modes set with setDisabledTouchInputModes(int).

Note that the disabled touch input modes may be device specific so this method may return some modes as disabled by default.

Note that if the device does not support touch input this method returns all modes.

Returns:

The disabled touch input modes.

See Also:

setDisabledTouchInputModes(int), setPreferredTouchMode(int)

setPreferredTouchMode

public void setPreferredTouchMode(int touchInputModes)

Set the preferred touch input mode overriding the device default preferred mode. User may still change the touch input mode from touch input window to all available modes.

The possible values are defined in the class with TOUCH_INPUT_* starting constant values.

Note that if the device does not support touch input this method has no effect.

Parameters:

touchInputModes - a touch input mode to be set as preferred one.

Throws:

java.lang.IllegalArgumentException - if the input mode is not valid or if it contains multiple input modes as bit mask.

See Also:

setDisabledTouchInputModes(int), getPreferredTouchMode()

getPreferredTouchMode

public int getPreferredTouchMode()

Gets the preferred touch input mode.

Note that if the device does not support touch input this method returns 0

Returns:

The preferred touch input mode.

See Also:

setPreferredTouchMode(int), setDisabledTouchInputModes(int)

setCaretXY

public void setCaretXY(int x,
                       int y)

Sets the caret in the Editor at x, y location.

Parameters:

x - The x coordinate of the wanted caret position.

y - The y coordinate of the wanted caret position.

setTouchEnabled

public 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

public boolean isTouchEnabled()

Gets the current touch-enabled state

Returns:

true if the ditor is touch-enabled, false otherwise.