com.nokia.mid.ui
Class TextEditor

java.lang.Object
  com.nokia.mid.ui.CanvasItem
      com.nokia.mid.ui.TextEditor

public class TextEditor
extends CanvasItem

A TextEditor is an editable text component that is used with a parent object; with Canvas or CustomItem. The TextEditor maybe set to and removed from Canvas through setParent() method.

The implementation presents the TextEditor with minimal decoration; only the caret is shown at the requested text insertion position. It is the responsibility of the application to draw any additional decoration like focus highlight, border or scroll bar. The animation of the caret, e.g. blinking, is handled by the TextEditor implementation.

TextEditor supports input constraints identically to TextField. In addition TextEditor has the same concept of actual contents and displayed contents as TextField.

TextEditor supports input modes identically to TextField.

The text may contain line breaks. The display of the text must break accordingly and the user must be able to enter line break characters.

The TextEditor provides necessary interaction for example for touch input (handwriting recognition) on touch screen devices and selection of additional characters. The input on touch devices requires additional windows of top of the editor window which depending on the implementation may obscure the parent completely.

Application can add a TextEditorListener to the TextEditor for example for keeping track of user navigation (caret movement) and other content changes such as text selection. The events are sent on all occasions that cause the the caret position to change (including but not limited to text typing by user, programmatic text insertion, navigation within the TextEditor content, and text deletion). The events must be sent to the application prior to they have effect on the editor - for example an event indicating caret movement must be available for the application before the implementation actually moves the caret in the editor.

When the TextEditor has focus all the key events that are not consumed by TextEditor with the current constraints or mapped to Commands by the implementation are sent to Canvas.

Touch pointer events are not delivered to parent object from the area of the visible TextEditor.

The implementation will scroll the TextEditor content automatically on user interaction and when the application calls setCaret or setSelection methods. For example if a user clicks down on the last visible row the TextEditor content is scrolled accordingly by one row. However the Java platform implementation does not draw any scroll bars, this is left to the application.

Since:

1.4

Constructor Summary

TextEditor()

Method Summary

static TextEditor	createTextEditor(int maxSize, int constraints, int width, int rows) Creates a new empty TextEditor with the given maximum size in characters, constraints and editor size as number of visible rows.
static TextEditor	createTextEditor(java.lang.String text, int maxSize, int constraints, int width, int height) Creates a new TextEditor object with the given initial contents, maximum size in characters, constraints and editor size in pixels.
void	delete(int offset, int length) Deletes characters from the TextEditor.
int	getBackgroundColor() Gets the background color and alpha of this TextEditor.
int	getCaretPosition() Gets the current position of the caret in the editor.
int	getConstraints() Gets the current input constraints of this TextEditor.
java.lang.String	getContent() Gets the string content in the TextEditor.
int	getContentHeight() Gets the whole content height in this TextEditor in pixels.
Font	getFont() Gets the font being used in rendering the text content in this TextEditor.
int	getForegroundColor() Gets the foreground color and alpha of this TextEditor
java.lang.String	getInitialInputMode() Returns the initial input mode set to the editor, or null if no initial input mode has been set.
int	getLineMarginHeight() Gets the line margin height in this TextEditor in pixels.
int	getMaxSize() Returns the maximum size (number of characters) that can be stored in this TextEditor.
java.lang.String	getSelection() Gets the currently selected content in the TextEditor.
int	getVisibleContentPosition() Gets the topmost pixel position of the topmost visible line in the editor.
int	getZPosition() Returns the Z-position, or the elevation, of the item.
boolean	hasFocus() Returns the focus state of TextEditor.
void	insert(java.lang.String text, int position) Inserts a string into the content of the TextEditor.
boolean	isMultiline() Returns the multiline state of the TextEditor.
void	setBackgroundColor(int color) Sets the background color and alpha of this TextEditor to the specified values.
void	setCaret(int index) Sets the index of the caret.
void	setConstraints(int constraints) Sets the input constraints of this TextEditor.
void	setContent(java.lang.String content) Sets the content of the TextEditor as a string.
void	setFocus(boolean focused) Sets this TextEditor focused or removes keyboard focus.
void	setFont(Font font) Sets the application preferred font for rendering the text content in this TextEditor.
void	setForegroundColor(int color) Sets the foreground color and alpha of this TextEditor to the specified values.
void	setHighlightBackgroundColor(int color) Sets the highlight background color.
void	setHighlightForegroundColor(int color) Sets the highlight foreground color.
void	setInitialInputMode(java.lang.String characterSubset) Sets a hint to the implementation as to the input mode that should be used when the user initiates editing of this TextEditor.
int	setMaxSize(int maxSize) Sets the maximum size (number of characters) that can be contained in this TextEditor.
void	setMultiline(boolean aMultiline) Sets the editor to be either multi-line (true) or single-line (false).
void	setParent(java.lang.Object parent) Set the parent object of this TextEditor.
void	setPosition(int x, int y) Sets the rendering position of this TextEditor.
void	setSelection(int index, int length) Sets a selection on a range of text in the TextEditor content.
void	setSize(int width, int height) Sets the size of this TextEditor in pixels.
void	setTextEditorListener(TextEditorListener listener) Sets a listener for content changes in this TextEditor, replacing any previous TextEditorListener.
void	setVisible(boolean visible) Sets the visibility value of TextEditor.
void	setZPosition(int z) Sets the Z-position, or the elevation, of the item.
int	size() Gets the number of characters that are currently stored in this TextEditor.

Methods inherited from class com.nokia.mid.ui.CanvasItem

getHeight, getParent, getPositionX, getPositionY, getWidth, isVisible

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TextEditor

public TextEditor()

Method Detail

createTextEditor

public static TextEditor createTextEditor(java.lang.String text,
                                          int maxSize,
                                          int constraints,
                                          int width,
                                          int height)

Creates a new TextEditor object with the given initial contents, maximum size in characters, constraints and editor size in pixels.

If the text parameter is null, the TextEditor is created empty.

The maxSize parameter must be greater than zero. An IllegalArgumentException is thrown if the length of the initial contents string exceeds maxSize. However, the implementation may assign a maximum size smaller than the application had requested. If this occurs, and if the length of the contents exceeds the newly assigned maximum size, the contents are truncated from the end in order to fit, and no exception is thrown.

Parameters:

text - the initial contents, or null if the TextEditor is to be created empty

maxSize - the maximum capacity in characters

constraints - see the input constraints in TextField

width - the width of the bounding box, in pixels

height - the height of the bounding box, in pixels

Returns:

Instance of TextEditor

Throws:

java.lang.IllegalArgumentException - if aMaxSize is zero or less

java.lang.IllegalArgumentException - if the value of the constraints parameter is invalid

java.lang.IllegalArgumentException - if aText is illegal for the specified constraints

java.lang.IllegalArgumentException - if the length of the string exceeds the requested maximum capacity

java.lang.IllegalArgumentException - if the width or height is less than one pixel

createTextEditor

public static TextEditor createTextEditor(int maxSize,
                                          int constraints,
                                          int width,
                                          int rows)

Creates a new empty TextEditor with the given maximum size in characters, constraints and editor size as number of visible rows.

The rows parameter indicates the requested number of visible rows in the editor. TextEditor then assigns the initial height for the editor based on the requested number of rows and width of the editor.

The maxSize parameter must be greater than zero. An IllegalArgumentException is thrown if the length of the initial contents string exceeds maxSize. However, the implementation may assign a maximum size smaller than the application had requested. If this occurs, and if the length of the contents exceeds the newly assigned maximum size, the contents are truncated from the end in order to fit, and no exception is thrown.

Parameters:

maxSize - the maximum capacity in characters

constraints - see the input constraints in TextField

width - the width of the bounding box, in pixels

rows - the requested number of visible rows in the editor

Returns:

Instance of TextEditor

Throws:

java.lang.IllegalArgumentException - if aMaxSize or aRows is zero or less

java.lang.IllegalArgumentException - if the value of the constraints parameter is invalid

java.lang.IllegalArgumentException - if the length of the string exceeds the requested maximum capacity

java.lang.IllegalArgumentException - if the width is less than one pixel

setFocus

public void setFocus(boolean focused)

Sets this TextEditor focused or removes keyboard focus. Calling setFocus(true) enables text editing from keys as the delivery of needed key events will be targeted to the TextEditor instead of the parent object (e.g. Canvas). Focus needs to be explicitly set to the TextEditor by application. When Canvas or CustomItem does not have any focused TextEditor all key and pointer events are delivered to normal key delivery methods of parent. Necessary key events are captured by TextEditor only when it has focus.

The setFocus affects to the parent key event delivery in following way: If all TextEditors are unfocused the key event delivery of parent works as if there are not any TextEditors in it, only when a focus is set via this method to a TextEditor the key event delivery is modified. The focused editor starts to capture the necessary key events and these key events are not delivered to parent. The set of key events captured depends on TextEditor implementation and device HW but in most implementations nearly all device keys are captured by the editor for text insertion, input mode changes and caret move functionalities. Especially applications should not assume to get key events from keys mapped to game actions as most probably the same keys are used to navigate the text caret within the editor. The keys that are used for Command launching in Canvas are available for applications on focused TextEditor and these keys either launch commands or send low-level key events as normally.

Setting focus does not cause any visual focus indication by the implementation other than showing the caret. Any other change in the visual appearance of the editor in focused state is the responsibility of the application; this can be done for example by drawing a focus border around the TextEditor or by changing the background color or transparency of the editor.

If this TextEditor has already been focused earlier and the editor contents has not changed after previous unfocusing, then after calling setFocus again the caret position should be retained.

If there already is another focused TextEditor on the Canvas, the focus is first removed from that TextEditor before setting this TextEditor focused.

Calling setFocus(false) disables key based text editing and returns the delivery of key events and pointer events to the underlying Canvas.

Parameters:

focused - keyboard focus of the TextEditor

Throws:

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

See Also:

hasFocus()

hasFocus

public boolean hasFocus()

Returns the focus state of TextEditor.

Returns:

the focus state of the editor

See Also:

setFocus(boolean focused)

setParent

public void setParent(java.lang.Object parent)

Set the parent object of this TextEditor.

Typically the parent object would be Canvas. Setting the parameter to null removes the association to the parent. If setParent(null) is called for a TextEditor yet not having any parent or setParent(parent) is called with the same parent, the call is silently ignored.

Overrides:

setParent in class CanvasItem

Parameters:

parent - the parent object

Throws:

java.lang.IllegalArgumentException - if parent is not a valid object with which a TextEditor can be associated, or if CanvasItem is already set to another another parent

setSize

public void setSize(int width,
                    int height)

Sets the size of this TextEditor in pixels.

Overrides:

setSize in class CanvasItem

Parameters:

width - width in pixels

height - height in pixels

Throws:

java.lang.IllegalArgumentException - if the width or height is less than one pixel

setPosition

public void setPosition(int x,
                        int y)

Sets the rendering position of this TextEditor. The anchor point given is relative to the upper left corner of the parent, Canvas.

The TextEditor may be placed fully off or partially of the visible area of the parent, Canvas, by the setPosition method; in this case the TextEditor is just partly visible.

Overrides:

setPosition in class CanvasItem

Parameters:

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

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

Throws:

java.lang.IllegalStateException - if a valid parent object has not been set.

See Also:

setParent(java.lang.Object parent)

setVisible

public void setVisible(boolean visible)

Sets the visibility value of TextEditor. Initially TextEditor is not visible so it must be explicitly set to visible in order it to appear on UI.

Setting visibility to true shows the editor with its content, but without the caret. If the editor does not have any visible content and does not have any background color set then this method effectively does not cause any visual change in the display. If the editor is already visible calling setVisible(true) does nothing.

Setting the visibility to false hides the editor and its content. If the TextEditor has focus then the focus is removed. If the editor is already hidden calling setVisible(false) does nothing.

Overrides:

setVisible in class CanvasItem

Parameters:

visible - visibility of the TextEditor

Throws:

java.lang.IllegalStateException - if a valid parent object has not been set.

See Also:

setParent(java.lang.Object parent)

setZPosition

public void setZPosition(int z)

Sets the Z-position, or the elevation, of the item.

The elevation decides the stacking order of neighboring items. An item of high Z-position will be drawn on top of an item with a lower Z-position if they share the same parent item.

The z-position is unique for each item meaning that changing a Z-position of an item may change the Z-position of the items that share the same parent item. The Z-position does not affect the item's size in any way.

When items are added with CanvasItem.setParent(java.lang.Object) they will get a Z-position that is increased by 1 from the item that is the top most item at that time.

Overrides:

setZPosition in class CanvasItem

Parameters:

z - the Z-position of the item.

Throws:

java.lang.IllegalArgumentException - If z < 0

java.lang.IllegalStateException - if a valid parent object has not been set.

See Also:

getZPosition(), setParent(java.lang.Object parent)

getZPosition

public int getZPosition()

Returns the Z-position, or the elevation, of the item. The Z-position decides the stacking order of neighboring items.

Overrides:

getZPosition in class CanvasItem

Returns:

the Z-position of the item.

Throws:

java.lang.IllegalStateException - if a valid parent object has not been set.

See Also:

setZPosition(int), setParent(java.lang.Object parent)

getLineMarginHeight

public int getLineMarginHeight()

Gets the line margin height in this TextEditor in pixels.

Gets the possible line margin height that editor has in addition to the normal font height (Font getHeight()). The returned value is 0 if the editor does not have any additional line margins to the text height returned from getHeight() of Font set to the editor.

Returns:

the line margin height in pixels

See Also:

setParent(java.lang.Object parent)

getContentHeight

public int getContentHeight()

Gets the whole content height in this TextEditor in pixels.

The returned value must include the height of the whole content in the editor, not just the height of the visible content.

Note that the method returns 0, if the editor has no parent.

Returns:

the height of the whole content in the editor in pixels

See Also:

setParent(java.lang.Object parent)

setCaret

public void setCaret(int index)

Sets the index of the caret. The caret can be used to indicate a position in the text.

The Java platform implementation must scroll the content of the TextEditor automatically so that the caret is within the visible area. If the caret is set above the visible area the content should be scrolled so that the caret is on the top most visible row. If the caret is set below the visible area the content should be scrolled so that the caret is on the lowest visible row.

Parameters:

index - the character index before which to place the caret

Throws:

java.lang.StringIndexOutOfBoundsException - if index does not specify a valid range within the content of the TextEditor

getCaretPosition

public int getCaretPosition()

Gets the current position of the caret in the editor.

Returns:

the current caret position, 0 if at the beginning

getVisibleContentPosition

public int getVisibleContentPosition()

Gets the topmost pixel position of the topmost visible line in the editor.

The returned y coordinate value is relative to the whole content height, not just the visible part.

This method can be used by the application together with the getContentHeight, height of the font, getLineMarginHeight, and getCaretPosition methods in drawing custom visual cues like a scroll bar or other content sensitive pop-ups.

Note that the method returns 0, if the editor has no parent.

Returns:

the topmost pixel position of the visible content.

getFont

public Font getFont()

Gets the font being used in rendering the text content in this TextEditor.

Returns:

the font being used in this TextEditor

setFont

public void setFont(Font font)

Sets the application preferred font for rendering the text content in this TextEditor. Setting the font is a hint to the implementation, and the implementation may disregard the requested font.

The font parameter must be a valid Font object or null. If the font parameter is null, the implementation must use its default font to render the text content.

Parameters:

font - the application preferred font to be used in this TextEditor

getBackgroundColor

public int getBackgroundColor()

Gets the background color and alpha of this TextEditor.

Returns:

the background color

getForegroundColor

public int getForegroundColor()

Gets the foreground color and alpha of this TextEditor

Returns:

the foreground color

setBackgroundColor

public void setBackgroundColor(int color)

Sets the background color and alpha of this TextEditor to the specified values. The default background color for editor is fully transparent white.

Parameters:

color - the color

setForegroundColor

public void setForegroundColor(int color)

Sets the foreground color and alpha of this TextEditor to the specified values. The content, e.g. text, in the editor must be drawn with this color. The default foreground color is fully opaque black.

Parameters:

color - the color

setHighlightBackgroundColor

public void setHighlightBackgroundColor(int color)

Sets the highlight background color. This impacts text background color for the selected text. The text in a current selection range will be rendered using given color value. The default highlight background color is fully opaque black. This method is not supported on S40 platform.

Parameters:

color - the color

setHighlightForegroundColor

public void setHighlightForegroundColor(int color)

Sets the highlight foreground color. This impacts text color for the selected text. The text in a current selection range will be rendered using given color value. The default highlight foreground color is fully opaque white. This method is not supported on S40 platform.

Parameters:

color - the color

setContent

public void setContent(java.lang.String content)

Sets the content of the TextEditor as a string. The set string replaces any previous content in the editor.

Parameters:

content - the new content of the TextEditor as string, null empties the TextEditor

Throws:

java.lang.IllegalArgumentException - if aContent is illegal for the current input constraints

java.lang.IllegalArgumentException - if the given text would exceed the current maximum capacity of the editor

getContent

public java.lang.String getContent()

Gets the string content in the TextEditor.

Returns:

The editor current content

insert

public void insert(java.lang.String text,
                   int position)

Inserts a string into the content of the TextEditor.

The string is inserted just prior to the character indicated by the position parameter, where zero specifies the first character of the content in the TextEditor. If position is less than or equal to zero, the insertion occurs at the beginning of the content. If position is greater than or equal to the current size of the content, the insertion occurs immediately after the end of the content.

The current size of the contents is increased by the number of inserted characters. The resulting string must fit within the current maximum capacity.

Parameters:

text - the String to be inserted

position - the position at which insertion is to occur

Throws:

java.lang.IllegalArgumentException - if the resulting content would be illegal for the current input constraints

java.lang.IllegalArgumentException - if the insertion would exceed the current maximum capacity

java.lang.NullPointerException - if text is null

delete

public void delete(int offset,
                   int length)

Deletes characters from the TextEditor.

The offset and length parameters must specify a valid range of characters within the contents of the TextEditor. The offset parameter must be within the range [0..(size())], inclusive. The length parameter must be a non-negative integer such that (offset + length) <= size().

Parameters:

offset - the beginning of the region to be deleted

length - the number of characters to be deleted

Throws:

java.lang.IllegalArgumentException - if the resulting contents would be illegal for the current input constraints

java.lang.StringIndexOutOfBoundsException - if offset and length do not specify a valid range within the content of the TextEditor

getMaxSize

public int getMaxSize()

Returns the maximum size (number of characters) that can be stored in this TextEditor.

Returns:

the maximum size in characters

setMaxSize

public int setMaxSize(int maxSize)

Sets the maximum size (number of characters) that can be contained in this TextEditor. If the current content of the TextEditor is larger than the new maxSize, the content is truncated to fit.

Parameters:

maxSize - the new maximum size

Returns:

assigned maximum capacity - may be smaller than requested.

Throws:

java.lang.IllegalArgumentException - if maxSize is zero or less.

java.lang.IllegalArgumentException - if the contents after truncation would be illegal for the current input constraints

size

public int size()

Gets the number of characters that are currently stored in this TextEditor.

Returns:

the number of characters

setConstraints

public void setConstraints(int constraints)

Sets the input constraints of this TextEditor. If the current content of this TextEditor do not match the new constraints, the content is set to empty.

Parameters:

constraints - see input constraints

Throws:

java.lang.IllegalArgumentException - if the value of the constraints parameter is invalid

getConstraints

public int getConstraints()

Gets the current input constraints of this TextEditor.

Returns:

the current constraints value (see input constraints)

setInitialInputMode

public void setInitialInputMode(java.lang.String characterSubset)

Sets a hint to the implementation as to the input mode that should be used when the user initiates editing of this TextEditor. The characterSubset parameter names a subset of Unicode characters that is used by the implementation to choose an initial input mode. If null is passed, the implementation should choose a default input mode.

See Input Modes for a full explanation of input modes.

Parameters:

characterSubset - a string naming a Unicode character subset, or null

getInitialInputMode

public java.lang.String getInitialInputMode()

Returns the initial input mode set to the editor, or null if no initial input mode has been set.

Returns:

the initial input mode as a String, or null if no initial input mode is set.

See Also:

setInitialInputMode(String characterSubset )

setSelection

public void setSelection(int index,
                         int length)

Sets a selection on a range of text in the TextEditor content. The implementation should highlight the selection visually. A selection may be set with this method or by user interaction. If there already is a selection set, it is replaced by this new selection.

The caret must be automatically set directly after the set selection. The Java platform implementation must scroll the content of the TextEditor automatically so that the caret is within the visible area and as much as possible of the selection is visible in the TextEditor.

Parameters:

index - the index of the first character to be selected.

length - the length of the selection in characters, 0 length clears the selection.

Throws:

java.lang.StringIndexOutOfBoundsException - if index and length do not specify a valid range within the content of the TextEditor

getSelection

public java.lang.String getSelection()

Gets the currently selected content in the TextEditor. A selection may be set with setSelection method or by user interaction. If selection is not set non-null empty string is returned.

Returns:

the currently selected content

setTextEditorListener

public void setTextEditorListener(TextEditorListener listener)

Sets a listener for content changes in this TextEditor, replacing any previous TextEditorListener.

A null reference is allowed and has the effect of removing any existing TextEditorListener from this TextEditor.

Callbacks to the TextEditorListener may throw exceptions, but they must be ignored.

Parameters:

listener - the new listener, or null

isMultiline

public boolean isMultiline()

Returns the multiline state of the TextEditor.

Returns:

the multiline state

setMultiline

public void setMultiline(boolean aMultiline)

Sets the editor to be either multi-line (true) or single-line (false). TextEditor is by default single-line editor, which meeans that user is not possible to insert line breaks to the editor. A possible Enter (or similar) key event should be passed in this case to the parent object as a normal key event for client to handle it as appropriately. A single-line editor will have horizontal scrolling of text if it is possible to enter text that does not fit to the editor. This may happen if maximum size is large enough for the width of the editor. In multi-line editor user is able to insert line breaks but also word wrapping is enabled automatically on word boundaries.

Parameters:

aMultiline - true if multi-line editor, false if single-line editor

Throws:

java.lang.IllegalStateException - if a valid parent object has not been set.