javax.microedition.lcdui
Class Text

java.lang.Object
  javax.microedition.lcdui.Text

public class Text
extends java.lang.Object

The Text class is used to layout and render text within a specific area. Text supports:

• Alignment of each line to left, center, right or locale default
• Justification of each line
• Bidirectional layout based on Unicode and locale
• Default font for all characters
• Per character Font to supersede default font for regions of characters
• Query of position and extent of each character
• Query of index of character at position
• Query of characters displayed
• Insert and delete of characters
• Spacing above and below lines
• Indentation
• Scrolling within bounding box
• Support for a caret
• Support for highlight region
• Support for setting the color of regions

The Text class encapsulates the text, its formatting attributes, and a rectangular area within which it is to be rendered. The text contents are laid out within the bounding box area accordingly, and the locations of specific characters can be queried.

The text can display a caret indicating a character. The caret, if present, MUST be drawn when the Text is drawn using the foreground Color. The application may set and reset the caret position before it draws the Text to achieve visual effects such as blinking the caret. The caret is only moved using the setCaret and moveCaret methods since the Text instance has no access to any input such as keys or pointer. The text can highlight a range of characters. The Text can set the font and color of regions of characters. The Text can set the background color for the region, by default the background is transparent.

The Text object MUST support directional text appropriate for all locales supported by the device. The Unicode 3.0 standard defines a standard nomenclature and algorithm for layout of bi-directional text. Strings passed to this Text are in logical order. The implementation of Text is responsible for displaying the characters in the appropriate direction for the locale and Unicode 3.0 encodings. The initial display direction can be set as Left-To-Right, Right-To-Left, or neutral. If neutral, the device or sequence of characters determines the initial direction. The alignment of text on each line can be set to left, right, centered, justified or default. The default alignment MUST match the default initial display direction. The alignment changes to the opposite (right or left) if the first strong directional character in the paragraph changes the initial text direction.

A Text object contains a sequence of text to be drawn within a bounding box. When drawn on a graphics context all of the characters fully visible or partially visible within the bounding box are drawn. Scrolling is supported with a scroll offset. The scroll offset shifts the text to be displayed up within the bounding box. The scroll offset affects all of the mappings from locations to characters within the text and vis-a-versa. The Text does not draw any indication of the scrolling offset or scrollbars; if needed by the application, it must draw them itself.

Implementation note: Modifying the attributes of a Text object may necessitate an update to the layout of the text. While implementations are not required to recompute the layout immediately, they MUST ensure that the layout is up to date prior to performing any operation that is dependent on the layout. For example, if the text and font are changed, the layout does not need to be updated immediately. However, if an attempt is made to render this Text or query the location of a character, the implementation must ensure that the layout is recomputed prior to processing these requests.

Since:

MIDP 3.0

See Also:

Graphics.drawText(javax.microedition.lcdui.Text, int, int)

Field Summary

static int	ALIGN_CENTER Center each line of text horizontally within this Text.
static int	ALIGN_DEFAULT Align each line using the default.
static int	ALIGN_JUSTIFY Justify the each line both left and right.
static int	ALIGN_LEFT Align each line of text to the left edge of this Text.
static int	ALIGN_RIGHT Align each line of text to the right edge of this Text.
static int	DIRECTION_LTR Initial Left-to-Right display order.
static int	DIRECTION_NEUTRAL Initial neutral display order.
static int	DIRECTION_RTL Initial Right-to-Left display order.

Constructor Summary

Text()
Creates a new Text object.

Text(java.lang.String contents, int width, int height)
Creates a new Text object with the contents of a String and the specified width and height.

Text(java.lang.String contents, int offset, int length, int width, int height)
Creates a new Text object with the specified substring, width and height.

Method Summary

void	delete(int index, int length) Deletes the range of characters in the text.
int	getAlignment() Gets the alignment for this Text object.
int	getBackgroundColor() Gets the color used to fill the background of the Text.
int	getCaret() Gets the index of the caret.
void	getCharExtent(int index, int[] extent) Gets the extent within this Text where the specified character is located.
int	getCharIndex(int x, int y) Gets the index of the character nearest the location within the bounding box.
Font	getFont() Gets the default Font for this Text object.
Font	getFont(int index) Gets the Font in use for the character at index.
int	getForegroundColor() Gets the color used to draw any character that does not have a per character color.
int	getForegroundColor(int index) Gets the color used to draw the character at index.
int	getHeight() Gets the height of this Text.
int	getHighlightIndex() Gets the highlight index.
int	getHighlightLength() Gets the highlight length.
int	getIndent() Gets the horizontal first line indent used at the beginning of each paragraph.
int	getInitialDirection() Gets the initial display direction.
int	getRequiredHeight() Gets the height, in pixels, needed to fully render the text given its current width, font, and contents.
int	getRequiredLineCount() Gets the number of lines needed to fully render this Text.
int	getScrollOffset() Gets the scroll offset for the text.
int	getSpaceAbove() Gets the space above each line of text.
int	getSpaceBelow() Gets the space below each line of text.
java.lang.String	getText(int index, int length) Gets a substring from this Text.
int	getTextLength() Gets the length of the Text in characters.
int	getWidth() Gets the width of this Text.
void	insert(int index, java.lang.String contents) Inserts the contents into this Text object at the index.
int	lastRenderedIndex() Gets the index of the last character that fits within the bounding box.
void	moveCaret(int nlines) Move caret forward or backward by one line in the display The getCharExtent method is use to find the bounding box of the character identified getCaret.
void	setAlignment(int alignment) Sets the alignment for this Text object.
void	setBackgroundColor(int color) Sets the color used to fill the background of the Text.
void	setCaret(int index) Sets the index of the caret.
void	setFont(Font font) Sets the default Font for this Text object.
void	setFont(Font font, int index, int length) Sets the per character Font for a subrange of this Text object.
void	setForegroundColor(int color) Sets the color used to draw characters that do not have a per character foreground color.
void	setForegroundColor(int color, int index, int length) Sets the color used to draw length characters starting at index.
void	setHeight(int height) Sets the height of this Text.
void	setHighlight(int index, int length) Sets the highlight on a range in the text.
void	setIndent(int indent) Sets the horizontal first line indent used at the beginning of each paragraph.
void	setInitialDirection(int direction) Sets the initial display direction for Text.
void	setScrollOffset(int offset) Sets the scroll offset of the text.
void	setSpaceAbove(int spaceAbove) Sets the line spacing above each line.
void	setSpaceBelow(int spaceBelow) Sets the line space below each line.
void	setWidth(int width) Sets the width of this Text.
boolean	textFits() Checks if the contents can be fully rendered within the current bounds of this Text.

Methods inherited from class java.lang.Object

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

Field Detail

ALIGN_LEFT

public static final int ALIGN_LEFT

Align each line of text to the left edge of this Text.

Since:

MIDP 3.0

See Also:

Constant Field Values

ALIGN_CENTER

public static final int ALIGN_CENTER

Center each line of text horizontally within this Text.

Since:

MIDP 3.0

See Also:

Constant Field Values

ALIGN_RIGHT

public static final int ALIGN_RIGHT

Align each line of text to the right edge of this Text.

Since:

MIDP 3.0

See Also:

Constant Field Values

ALIGN_JUSTIFY

public static final int ALIGN_JUSTIFY

Justify the each line both left and right.

Since:

MIDP 3.0

See Also:

Constant Field Values

ALIGN_DEFAULT

public static final int ALIGN_DEFAULT

Align each line using the default.

Since:

MIDP 3.0

See Also:

Constant Field Values

DIRECTION_LTR

public static final int DIRECTION_LTR

Initial Left-to-Right display order.

Since:

MIDP 3.0

See Also:

Constant Field Values

DIRECTION_RTL

public static final int DIRECTION_RTL

Initial Right-to-Left display order.

Since:

MIDP 3.0

See Also:

Constant Field Values

DIRECTION_NEUTRAL

public static final int DIRECTION_NEUTRAL

Initial neutral display order.

Since:

MIDP 3.0

See Also:

Constant Field Values

Constructor Detail

Text

public Text()

Creates a new Text object. The contents are empty and the width and height are zero.

Since:

MIDP 3.0

Text

public Text(java.lang.String contents,
            int width,
            int height)

Creates a new Text object with the contents of a String and the specified width and height.

Parameters:

contents - the String that is to be used as the contents of this Text

width - the width of the bounding box, in pixels.

height - the height of the bounding box, in pixels.

Throws:

java.lang.IllegalArgumentException - if the width or height are less than 0.

java.lang.NullPointerException - if contents is null.

Since:

MIDP 3.0

Text

public Text(java.lang.String contents,
            int offset,
            int length,
            int width,
            int height)

Creates a new Text object with the specified substring, width and height.

Parameters:

contents - String containing the characters to be used as the contents of this Text object.

offset - offset within the contents of the first new character.

length - the number of characters to insert from the contents.

width - the width of the bounding box, in pixels.

height - the height of the bounding box, in pixels.

Throws:

java.lang.IndexOutOfBoundsException - if offset and length do not specify a valid range within contents.

java.lang.IllegalArgumentException - if the length, width or height are less than 0.

java.lang.NullPointerException - if contents is null.

Since:

MIDP 3.0

Method Detail

delete

public void delete(int index,
                   int length)

Deletes the range of characters in the text.

Parameters:

index - the index of the first character to delete.

length - the length of string to delete.

Throws:

java.lang.IndexOutOfBoundsException - if index and length do not specify a valid range within this Text.

Since:

MIDP 3.0

insert

public void insert(int index,
                   java.lang.String contents)

Inserts the contents into this Text object at the index.

Parameters:

index - the index where the new contents are to be inserted.

contents - The String to be used as the contents.

Throws:

java.lang.IndexOutOfBoundsException - if index is out of range for this Text.

Since:

MIDP 3.0

getText

public java.lang.String getText(int index,
                                int length)

Gets a substring from this Text.

Parameters:

index - the index of the first character to return.

length - the length of the substring to return.

Returns:

the String containing the characters from index including length characters.

Throws:

java.lang.IndexOutOfBoundsException - if index and length do not specify a valid range within this Text.

Since:

MIDP 3.0

setWidth

public void setWidth(int width)

Sets the width of this Text.

Parameters:

width - width in pixels.

Throws:

java.lang.IllegalArgumentException - if width is less than zero.

Since:

MIDP 3.0

See Also:

getWidth()

getWidth

public int getWidth()

Gets the width of this Text.

Returns:

width in pixels.

Since:

MIDP 3.0

See Also:

setWidth(int)

setHeight

public void setHeight(int height)

Sets the height of this Text.

Parameters:

height - height in pixels.

Throws:

java.lang.IllegalArgumentException - if height is less than zero.

Since:

MIDP 3.0

See Also:

getHeight()

getHeight

public int getHeight()

Gets the height of this Text.

Returns:

height in pixels.

Since:

MIDP 3.0

See Also:

setHeight(int)

getRequiredHeight

public int getRequiredHeight()

Gets the height, in pixels, needed to fully render the text given its current width, font, and contents.

Returns:

the height needed to render the contents of this Text.

Since:

MIDP 3.0

getTextLength

public int getTextLength()

Gets the length of the Text in characters.

Returns:

the number of characters

Since:

MIDP 3.0

getRequiredLineCount

public int getRequiredLineCount()

Gets the number of lines needed to fully render this Text.

Returns:

the number of lines

Since:

MIDP 3.0

textFits

public boolean textFits()

Checks if the contents can be fully rendered within the current bounds of this Text.

Returns:

true if the contents fit inside the bounds of this Text; otherwise false.

Since:

MIDP 3.0

lastRenderedIndex

public int lastRenderedIndex()

Gets the index of the last character that fits within the bounding box.

Returns:

the index of the last character that fits within the bounding box.

Since:

MIDP 3.0

getCharExtent

public void getCharExtent(int index,
                          int[] extent)

Gets the extent within this Text where the specified character is located. The location is relative to the upper left corner of the bounding box and refers to the top left edge of the character's glyph. The width and height are the width and height of the character.

Parameters:

index - the index of the character.

extent - an array to be filled with the extent of the character; extent[0] = x; extent[1] = y; extent[2] = width; extent[3] = height.

Throws:

java.lang.IndexOutOfBoundsException - if index is out of range for this Text.

java.lang.IllegalArgumentException - if extent has fewer than 4 elements.

java.lang.NullPointerException - if extent is null.

Since:

MIDP 3.0

setFont

public void setFont(Font font)

Sets the default Font for this Text object. Per character fonts of regions can be set with setFont(Font, int, int). The Font and per character fonts are used to determine the metrics of each character for the purposes of laying out the text and also used to render the text. By default, the default Font is set to the system default font, as returned by Font.getDefaultFont().

Parameters:

font - the Font to be used for this Text object.

Throws:

java.lang.NullPointerException - if font is null.

Since:

MIDP 3.0

See Also:

getFont()

getFont

public Font getFont()

Gets the default Font for this Text object. Per character fonts of regions can be retrieved with getFont(int). The Font is used to determine the metrics of each character for the purposes of laying out the text within the bounding box. By default, the Font is set to the system default font, as returned by Font.getDefaultFont().

Returns:

the default Font being used for this Text object.

Since:

MIDP 3.0

See Also:

setFont(Font)

setFont

public void setFont(Font font,
                    int index,
                    int length)

Sets the per character Font for a subrange of this Text object. The Font is used to determine the metrics of length characters starting at index for the purposes of laying out the text and it is also used to render the text. Any font previously set on each of the characters in the range is removed and replaced by the new font. Calling this method with a nullvalue will reset the per character font so the default Text will be used.

Parameters:

font - the Font to be used for this subrange of characters; null to revert to the default font.

index - the first character to use the font.

length - the number of characters in the subrange.

Throws:

java.lang.IndexOutOfBoundsException - if index and length do not specify a valid range within this Text.

Since:

MIDP 3.0

See Also:

getFont(int)

getFont

public Font getFont(int index)

Gets the Font in use for the character at index. The Font is used to determine the metrics of each character for the purposes of laying out the text within the bounding box. The Font is also used to render the text.

Parameters:

index - the index of the character for which to query the font.

Returns:

the Font being used for this Text object; nullis returned if the character does not have an per character font.

Throws:

java.lang.IndexOutOfBoundsException - if index is out of range for this Text.

Since:

MIDP 3.0

See Also:

setFont(javax.microedition.lcdui.Font, int, int)

setForegroundColor

public void setForegroundColor(int color,
                               int index,
                               int length)

Sets the color used to draw length characters starting at index. The per character color is removed if the color value is zero.

Parameters:

color - the ARGB color to use; zero to remove the color from each character in the range.

index - the first character to use the color.

length - the number of characters to use the color; must not be less than zero.

Throws:

java.lang.IndexOutOfBoundsException - if index and length do not specify a valid range within this Text.

Since:

MIDP 3.0

See Also:

getForegroundColor(int)

getForegroundColor

public int getForegroundColor(int index)

Gets the color used to draw the character at index.

Parameters:

index - the index to query for its ARGB color.

Returns:

the ARGB color of the character at index.

Throws:

java.lang.IndexOutOfBoundsException - if index is out of range for this Text.

Since:

MIDP 3.0

See Also:

setForegroundColor(int, int, int)

setForegroundColor

public void setForegroundColor(int color)

Sets the color used to draw characters that do not have a per character foreground color.

Parameters:

color - the ARGB color to use.

Since:

MIDP 3.0

See Also:

getForegroundColor(), setForegroundColor(int, int, int), getForegroundColor(int)

getForegroundColor

public int getForegroundColor()

Gets the color used to draw any character that does not have a per character color. Until set with setForeGroundColor(color), the value is set to the foreground color provided by Display.getColor(Display.COLOR_FOREGROUND).

Returns:

the ARGB color used to draw characters without a per character color.

Since:

MIDP 3.0

See Also:

setForegroundColor(int), setForegroundColor(int, int, int), getForegroundColor(int)

setBackgroundColor

public void setBackgroundColor(int color)

Sets the color used to fill the background of the Text. If the color is fully transparent and then it has no effect.

Parameters:

color - the ARGB color to use for the background.

Since:

MIDP 3.0

See Also:

getBackgroundColor()

getBackgroundColor

public int getBackgroundColor()

Gets the color used to fill the background of the Text.

Returns:

the ARGB color of the background color.

Since:

MIDP 3.0

See Also:

setBackgroundColor(int)

setAlignment

public void setAlignment(int alignment)

Sets the alignment for this Text object. MUST be one of ALIGN_LEFT, ALIGN_CENTER, ALIGN_RIGHT, ALIGN_JUSTIFY, or ALIGN_DEFAULT.

Parameters:

alignment - the alignment mode to be used for laying out and rendering this Text.

Throws:

java.lang.IllegalArgumentException - if the value is not one of the listed values.

Since:

MIDP 3.0

See Also:

getAlignment()

getAlignment

public int getAlignment()

Gets the alignment for this Text object.

Returns:

the alignment mode for this Text object; one of ALIGN_LEFT, ALIGN_CENTER, ALIGN_RIGHT, ALIGN_JUSTIFY, or ALIGN_DEFAULT.

Since:

MIDP 3.0

See Also:

setAlignment(int)

setIndent

public void setIndent(int indent)

Sets the horizontal first line indent used at the beginning of each paragraph.

Parameters:

indent - the indent to be used, in pixels.

Throws:

java.lang.IllegalArgumentException - if indent is less than 0.

Since:

MIDP 3.0

See Also:

getIndent()

getIndent

public int getIndent()

Gets the horizontal first line indent used at the beginning of each paragraph.

Returns:

the indent in pixels.

Since:

MIDP 3.0

See Also:

setIndent(int)

getSpaceAbove

public int getSpaceAbove()

Gets the space above each line of text.

Returns:

the number of pixels of additional space above each line; may be negative to tighten up the spacing.

Since:

MIDP 3.0

See Also:

setSpaceAbove(int), getSpaceBelow()

setSpaceAbove

public void setSpaceAbove(int spaceAbove)

Sets the line spacing above each line.

Parameters:

spaceAbove - the number of pixels to add above each line; may be negative to tighten up the spacing.

Since:

MIDP 3.0

See Also:

getSpaceAbove(), getSpaceBelow()

getSpaceBelow

public int getSpaceBelow()

Gets the space below each line of text.

Returns:

the number of pixels of additional space below each line; may be negative to tighten up the spacing.

Since:

MIDP 3.0

See Also:

setSpaceBelow(int), getSpaceAbove()

setSpaceBelow

public void setSpaceBelow(int spaceBelow)

Sets the line space below each line.

Parameters:

spaceBelow - the number of pixels to add below each line; may be negative to tighten up the spacing.

Since:

MIDP 3.0

See Also:

getSpaceAbove(), getSpaceBelow()

setCaret

public void setCaret(int index)

Sets the index of the caret. The caret can be used to indicate a character in the text. When set the caret is associated with the character at the index. If characters are inserted at indexes less than or equal to the caret, the caret is increased by the length of the inserted range. If characters at indexes less than or equal are deleted, the caret is decreased by the length of the deleted range except if the character the caret is associated with is deleted, the caret is then associated with the index after the last character deleted.

Parameters:

index - the character index before which to place the caret; -1 if the caret is not to be displayed.

Throws:

java.lang.IndexOutOfBoundsException - if index is out of range for this Text and not -1.

Since:

MIDP 3.0

See Also:

getCaret(), insert(int, java.lang.String), delete(int, int)

getCaret

public int getCaret()

Gets the index of the caret.

Returns:

the index of the caret; -1 if the caret is not displayed.

Since:

MIDP 3.0

See Also:

setCaret(int)

moveCaret

public void moveCaret(int nlines)

Move caret forward or backward by one line in the display The getCharExtent method is use to find the bounding box of the character identified getCaret. The vertical position is offset by the height of the line. The horizontal position maintained. The new caret position is set using the getCharIndex method with this new vertical offset.

Parameters:

nlines - the number of lines to move; +1 to move forward; -1 to move backward; zero to stay in place.

Throws:

java.lang.IllegalArgumentException - if lines is less than -1 or greater than 1.

See Also:

getCharIndex(int, int)

getCharIndex

public int getCharIndex(int x,
                        int y)

Gets the index of the character nearest the location within the bounding box.

Parameters:

x - the x offset.

y - the y offset.

Returns:

the index of the character nearest the location; -1 if there is no character near the location.

Since:

MIDP 3.0

setHighlight

public void setHighlight(int index,
                         int length)

Sets the highlight on a range in the text.

Parameters:

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

length - the length in characters to be highlighted.

Throws:

java.lang.IndexOutOfBoundsException - if index and length do not specify a valid range within this Text.

Since:

MIDP 3.0

See Also:

getHighlightIndex(), getHighlightLength()

getHighlightIndex

public int getHighlightIndex()

Gets the highlight index.

Returns:

the first character highlighted; -1 if none.

Since:

MIDP 3.0

See Also:

getHighlightLength()

getHighlightLength

public int getHighlightLength()

Gets the highlight length.

Returns:

the length of the highlight; zero if none.

Since:

MIDP 3.0

See Also:

setHeight(int)

setInitialDirection

public void setInitialDirection(int direction)

Sets the initial display direction for Text.

Parameters:

direction - the display direction; MUST be one of DIRECTION_LTR, DIRECTION_RTL, or DIRECTION_NEUTRAL.

Throws:

java.lang.IllegalArgumentException - if direction is invalid value.

Since:

MIDP 3.0

See Also:

getInitialDirection()

getInitialDirection

public int getInitialDirection()

Gets the initial display direction.

Returns:

the initial display direction; one of DIRECTION_LTR, DIRECTION_RTL, or DIRECTION_NEUTRAL.

Since:

MIDP 3.0

See Also:

setInitialDirection(int)

setScrollOffset

public void setScrollOffset(int offset)

Sets the scroll offset of the text. The text displayed in the bounding box is moved up by the amount of the offset. All computations between character indexes and positions within the bounding box are affected by the scroll offset.

Parameters:

offset - the scroll offset, in pixels.

Throws:

java.lang.IllegalArgumentException - if offset is less than zero.

Since:

MIDP 3.0

See Also:

getScrollOffset()

getScrollOffset

public int getScrollOffset()

Gets the scroll offset for the text.

Returns:

the scroll offset, in pixels.

Since:

MIDP 3.0

See Also:

setScrollOffset(int)