javax.microedition.lcdui
Class TextEditor

java.lang.Object
  javax.microedition.lcdui.CanvasItem
      javax.microedition.lcdui.TextEditor

public class TextEditor
extends CanvasItem

A TextEditor is an editable text component that is drawn on a parent object; in LCDUI Canvas or CustomItem (including IdleItem). TextEditor inherits from CanvasItem. The TextEditor may be set to Canvas through setParent(canvas) method and removed through method call setParent(null). The TextEditor must be presented so that the Canvas painting happens independently regardless of the TextEditor editing or focus. If multiple TextEditors are added on the same instance of Canvas or CustomItem and their positions overlap, the initial z-order is the same as the adding order of the TextEditors; i.e. the first added TextEditor is the lowest in the stack. For usability applications should avoid adding overlapping TextEditors.

The implementation should initially present the TextEditor with minimal decoration; only the caret should be shown at the requested text insertion position. It is then 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 Java platform implementation.

TextEditor supports input constraints identically to TextField. See input constraints section in the TextField for the definition of these constants. In addition TextEditor has the same concept of actual contents and displayed contents as TextField; these are described in the same input constraints section.

TextEditor supports input modes identically to TextField. See input modes section in the TextField for the definition of these constants.

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 implementation should provide necessary interaction for example for pen input (handwriting recognition) on touch screen devices and selection of additional characters. It should be noted that the implementation provided visuals, e.g. character input panels, may require additional windows on top of the text editor and may obscure both the editor and its parent partly or completely.

Application can add a TextEditorChangeListener 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 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 after they have effect on the editor - for example an event indicating caret movement must be available for the application after 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.

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

Since:

3.0

See Also:

CanvasItem, Canvas, CustomItem

Constructor Summary

TextEditor(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.

Method Summary

void	delete(int offset, int length) Deletes characters from the TextEditor.
int	getBackgroundColor() Gets the current 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.
int	getContentHeight() Gets the whole content height in this TextEditor in pixels.
boolean	getFocus() Gets the current focus state of the TextEditor.
Font	getFont() Gets the font being used in rendering the text content in this TextEditor.
int	getForegroundColor() Gets the current foreground color and alpha of this TextEditor.
int	getHighlightColor() Gets the current highlight color for this TextEditor.
int	getLineMarginHeight() Gets the possible line margin height that this editor has in addition to the normal font height as returned by Font.getHeight().
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.
java.lang.String	getString() Gets a string representing the current content in the TextEditor.
boolean	getVisible() Gets the visibility value of the TextEditor.
int	getVisibleContentPosition() Gets the topmost pixel y-position of the topmost visible line in the editor.
void	insert(java.lang.String text, int position) Inserts a string into the content of the TextEditor.
void	setBackgroundColor(int alpha, int red, int green, int blue) Sets the background color and alpha of this TextEditor to the specified values.
void	setCaretPosition(int index) Sets the index of the caret.
void	setConstraints(int constraints) Sets the input constraints of this TextEditor.
void	setFocus(boolean focused) Sets this TextEditor focused or removes focus.
void	setFont(Font font) Sets the application preferred font for rendering the text content in this TextEditor.
void	setForegroundColor(int alpha, int red, int green, int blue) Sets the foreground color and alpha of this TextEditor to the specified values.
void	setHighlightColor(int alpha, int red, int green, int blue) Sets the highlight color for this TextEditor to the specified values.
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; i.e.
int	setMaxSize(int maxSize) Sets the maximum size (number of characters) that can be contained in this TextEditor.
void	setSelection(int index, int length) Sets a selection on a range of text in the TextEditor content.
void	setString(java.lang.String text) Sets the content of the TextEditor as a string.
void	setTextEditorListener(TextEditorChangeListener listener) Sets a listener for content changes in this TextEditor, replacing any previous TextEditorChangeListener.
void	setVisible(boolean visible) Sets the visibility value of the TextEditor.
int	size() Gets the number of characters that are currently stored in this TextEditor.

Methods inherited from class javax.microedition.lcdui.CanvasItem

getHeight, getParent, getPositionX, getPositionY, getWidth, getZPosition, setParent, setPositionX, setPositionY, setSize, setZPosition

Methods inherited from class java.lang.Object

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

Constructor Detail

TextEditor

public TextEditor(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 the maximum size of the editor. 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 as returned by getMaxSize, 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

Throws:

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

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

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

java.lang.IllegalArgumentException - if the length of the string exceeds the maximum size of the editor as returned by getMaxSize

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

Method Detail

setFocus

public void setFocus(boolean focused)

Sets this TextEditor focused or removes 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). On touch screen devices a on-screen keyboard should be shown to enable text editing. Focus needs to be explicitly set to the TextEditor by application. Only in touch enabled devices user may tap to the editor which will result editor to gain also the focus automatically. If Canvas or CustomItem does not have any focused TextEditor, all key and pointer events are delivered to normal key delivery methods of the parent. Necessary key events are captured by TextEditor only when it has focus.

The setFocus method affects to the parent key event delivery in following way: If all TextEditors are unfocused the key event delivery of the parent functions as if there were no 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 the Java platform implementation and device hardware, but in most implementations nearly all device keys are captured by the editor for text insertion, input mode changes and caret move functionalities. 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 parent (e.g. Canvas).

Parameters:

focused - true to set focus, false to remove focus

Throws:

java.lang.IllegalStateException - If the TextEditor is not added to a parent with setParent

java.lang.IllegalStateException - If the TextEditor is not in visible state as returned by getVisible

getFocus

public boolean getFocus()

Gets the current focus state of the TextEditor.

Returns:

true if the TextEditor has focus, false otherwise

Throws:

java.lang.IllegalStateException - If the TextEditor is not added to a parent with setParent

getLineMarginHeight

public int getLineMarginHeight()

Gets the possible line margin height that this editor has in addition to the normal font height as returned by Font.getHeight(). The returned value is in pixels, and the returned value is 0 (zero) 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, 0 if none

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.

Returns:

the height of the whole content in the editor in pixels

setCaretPosition

public void setCaretPosition(int index)

Sets the index of the caret. The caret can be used to indicate a position in the text and MUST be visible when the TextEditor is in focus. If characters are inserted, the caret index is increased by the number of characters inserted at indexes before or equal to the caret index. If characters are deleted, the caret index is decreased by the number of characters deleted from indexes before or equal to the caret index.

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 current position the content should be scrolled so that the caret is on the top most visible row. If the caret is set below the current position the content should be scrolled so that the caret is on the lowest visible row.

Parameters:

index - an integer between 0 and size(), inclusive, indicating where in the text to place the caret (0 being immediately before the first character and size() being immediately after the last)

Throws:

java.lang.IndexOutOfBoundsException - if index is not in the range 0 to size(), inclusive

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 y-position of the topmost visible line in the editor. The returned y coordinate value must be relative to the whole content height, not just the visible part.

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

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.

The font change should be applied to the already visible editor and content as soon as possible. If setting the font changes for example the line wrapping of the already visible content, the implementation should maintain the caret visible.

Parameters:

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

setBackgroundColor

public void setBackgroundColor(int alpha,
                               int red,
                               int green,
                               int blue)

Sets the background color and alpha of this TextEditor to the specified values. The set values apply also to any other related implementation provided input visuals; for example to the implementation provided additional character table or handwriting recognition panel.

Parameters:

alpha - the alpha component of the color being set within range 0-255

red - the red component of the color being set within range 0-255

green - the green component of the color being set within range 0-255

blue - the blue component of the color being set within range 0-255

Throws:

java.lang.IllegalArgumentException - if any of the parameters is outside the range of 0-255

setForegroundColor

public void setForegroundColor(int alpha,
                               int red,
                               int green,
                               int blue)

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.

Parameters:

alpha - the alpha component of the color being set within range 0-255

red - the red component of the color being set within range 0-255

green - the green component of the color being set within range 0-255

blue - the blue component of the color being set within range 0-255

Throws:

java.lang.IllegalArgumentException - if any of the parameters is outside the range of 0-255

setHighlightColor

public void setHighlightColor(int alpha,
                              int red,
                              int green,
                              int blue)

Sets the highlight color for this TextEditor to the specified values. The highlight areas, e.g. a selection on a range of text, in the editor must be drawn with this color.

Parameters:

alpha - the alpha component of the color being set within range 0-255

red - the red component of the color being set within range 0-255

green - the green component of the color being set within range 0-255

blue - the blue component of the color being set within range 0-255

Throws:

java.lang.IllegalArgumentException - if any of the parameters is outside the range of 0-255

getBackgroundColor

public int getBackgroundColor()

Gets the current background color and alpha of this TextEditor.

Returns:

the current color and alpha value encoded using the 32-bit ARGB format

getForegroundColor

public int getForegroundColor()

Gets the current foreground color and alpha of this TextEditor.

Returns:

the current color and alpha value encoded using the 32-bit ARGB format

getHighlightColor

public int getHighlightColor()

Gets the current highlight color for this TextEditor.

Returns:

the current color and alpha value encoded using the 32-bit ARGB format

setString

public void setString(java.lang.String text)

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

Parameters:

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

Throws:

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

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

getString

public java.lang.String getString()

Gets a string representing the current content in the TextEditor.

Returns:

the current content of the editor

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 as returned by getMaxSize.

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 of the editor as returned by getMaxSize

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. The implementation may have assigned a smaller maximum size than requested by application with setMaxSize or in the constructor.

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. The implementation may assign a smaller maximum size than requested.

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; i.e. when the TextEditor becomes focused. 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

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.

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 have been set with setSelection method or by user interaction.

Returns:

the currently selected content, null if no selection has been set

setTextEditorListener

public void setTextEditorListener(TextEditorChangeListener listener)

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

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

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

Parameters:

listener - the new listener, or null

setVisible

public void setVisible(boolean visible)

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

Setting visibility to true shows the editor with its content, but without the caret (calling setFocus(true) shows 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 - true to set visible, false to set invisible

getVisible

public boolean getVisible()

Gets the visibility value of the TextEditor. The visibility value is the value set in setVisible method. If setVisible has not been called, this method will return false.

Returns:

Returns the visibility value of the TextEditor

Throws:

java.lang.IllegalStateException - If the TextEditor is not added to a parent with setParent