net.rim.device.api.ui.component
Class RichTextField

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--net.rim.device.api.ui.component.TextField
              |
              +--net.rim.device.api.ui.component.RichTextField

All Implemented Interfaces:

IComponent, InputMethodListener

Direct Known Subclasses:

ActiveRichTextField

public class RichTextField

extends net.rim.device.api.ui.component.TextField

Read-only field that supports richly formatted text.

Behaviour
A readonly text field for showing text in a variety of fonts and formatting.

When building a rich text field that contains formatted text, you specify a list of offsets. These offsets define the boundaries of the various formatting regions for the field's text. The first offset position in the list marks the beginning of the field's text (thus is zero), and the last offset position in the list marks the end of the field's text (this is equal to the field's text length).

The field also has an attribute list, corresponding to the regions described in the offset list. (The attribute list thus has one less element in it than the offset list.) Each element's value in the attribute list is an index into the fonts list.

The fonts list contains the various formatting styles used by the field's contained text (and thus will have no more elements than the attribute list, and most likely less). Any font element with a null value that's used by the attribute list simply indicates that the field should draw the text region using the default font.

You can also build a rich text field with a list of cookie objects corresponding to the offset list. As with the attribute list, each element in the cookie list is associated with one formatting region, and thus the list has one less element than the offset list.

You can use the Field.NON_FOCUSABLE style to build a rich text field that cannot accept the focus.

Field Summary

static long	JUMP_FOCUS_AT_END Enables jump-to-end of field behaviour.
static long	NO_COMPLEX_INPUT Suggests complex input (e.g.
static long	NO_LEARNING Suggests auto learning feature disable for current text component.
static int	TEXT_ALIGN_HCENTER Align contained text to the central vertical axis of this field.
static int	TEXT_ALIGN_LEFT Align contained text to the left edge of this field.
static int	TEXT_ALIGN_RIGHT Align contained text to the right edge of this field.
static int	USE_TEXT_WIDTH This field is economical with width.

Fields inherited from class net.rim.device.api.ui.Field

EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, READONLY, USE_ALL_HEIGHT, USE_ALL_WIDTH

Constructor Summary

RichTextField()
Constructs a plain, empty RichTextField object.

RichTextField(long style)
Constructs a plain, empty RichTextField in the specified style.

RichTextField(String text)
Constructs a plain RichTextField object.

RichTextField(String text, int[] offsets, byte[] attributes, Font[] fonts, long style)
Constructs a formatted RichTextField object in the specified style.

RichTextField(String text, int[] offsets, byte[] attributes, Font[] fonts, Object[] cookies, long style)
Constructs a formatted RichTextField object in the specified style, and with corresponding cookies.

RichTextField(String text, long style)
Constructs a plain RichTextField object in the specified style.

Method Summary

char	charAt(int offset) Retrieves a specific contained character from this field.
protected void	drawFocus(Graphics graphics, boolean on) Draws the focus indicator for this field.
protected byte[]	getAttributes() Retrieves this field's attributes list.
protected int[]	getBackgroundColors() Retrieves this field's background color list.
int	getCursorPosition() Retrieves index of current cursor position.
void	getFocusRect(XYRect rect) Retrieves the extent of the focus region.
protected Font[]	getFonts() Retrieves this field's font list.
protected int[]	getForegroundColors() Retrieves this field's foreground color list.
protected int	getLabelLength() Retrieves the length of this field's label.
protected int[]	getOffsets() Retrieves this field's offset list.
int	getRegion(int offset) Retrieves the formatting region index containing specified character position.
Object	getRegionCookie() Retrieves the cookie for the formatting region containing the current offset.
Object	getRegionCookie(int region) Retrieves the cookie for a specified formatting region.
Font	getRegionFont() Retrieves font format used in the formatting region containing the current offset.
Font	getRegionFont(int region) Retrieves font format used in a specified region.
String	getRegionText() Retrieves raw text in the formatting region containing the current offset.
String	getRegionText(int region) Retrieves raw text in a specified formatting region.
String	getText() Retrieves this field's text.
String	getText(int offset, int length) Retrieves a substring of this field's contained text.
int	getTextLength() Retrieves the number of characters in this field's contained text.
boolean	isPasteable() Determines if this field supports paste operations.
boolean	isSelectable() Determines if this field supports selection.
boolean	isSelecting() Determines if this field is currently selecting text.
boolean	isSelectionCopyable() Determines if this field supports copy operations.
boolean	isSelectionDeleteable() Determines if this field supports cut operations.
protected boolean	keyChar(char key, int status, int time) Traps character generation events.
protected void	layout(int width, int height) Lays out this field's contents.
int	moveFocus(int amount, int status, int time) Handles moving focus within this field.
protected void	moveFocus(int x, int y, int status, int time) Handles moving the focus to an exact position within this field.
protected void	onFocus(int direction) Positions cursor when this field first receives the focus.
protected void	paint(Graphics graphics) Redraws this field.
void	select(boolean toggle) Sets or unsets selection mode.
void	selectionCopy(Clipboard cb) Copies the current selection to the clipboard.
void	setCursorPosition(int offset) Places cursor on specific character within this field, at user request.
protected void	setCursorPosition(int offset, int context) Sets the cursor position to the specified offset.
void	setFont(Font font) Sets the font used by this field if only one in the list of fonts (see class description).
void	setText(String text) Provides new text for this field to show.
void	setText(String text, int[] offsets, byte[] attributes, Font[] fonts) Provides new, foramtted text for this field to show, with associated cookies.
void	setText(String text, int[] offsets, byte[] attributes, Font[] fonts, Object[] cookies) Provides new, foramtted text for this field to show, with associated cookies.
String	toString() Retrieves this field's text in a string.

Methods inherited from class net.rim.device.api.ui.Field

drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getChangeListener, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getWidth, invalidate, invalidate, isDirty, isEditable, isFocusable, isMuddy, isSelectionCutable, isStyle, isVisible, keyControl, keyDown, keyRepeat, keyStatus, keyUp, makeContextMenu, onDisplay, onExposed, onMenuDismissed, onObscured, onUndisplay, onUnfocus, onVisibilityChange, paste, selectionCut, selectionDelete, setChangeListener, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setMuddy, setPosition, trackwheelClick, trackwheelUnclick, updateLayout

Methods inherited from class java.lang.Object

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

Field Detail

USE_TEXT_WIDTH

public static final int USE_TEXT_WIDTH

This field is economical with width.

Fields built with this style render themselves either in their specified width, or the length of the longest line of contained text, whichever is the smaller value.

TEXT_ALIGN_LEFT

public static final int TEXT_ALIGN_LEFT

Align contained text to the left edge of this field.

TEXT_ALIGN_RIGHT

public static final int TEXT_ALIGN_RIGHT

Align contained text to the right edge of this field.

TEXT_ALIGN_HCENTER

public static final int TEXT_ALIGN_HCENTER

Align contained text to the central vertical axis of this field.

NO_COMPLEX_INPUT

public static final long NO_COMPLEX_INPUT

Suggests complex input (e.g. Chinese ) disable for current text component. Depending on Input method/Conversion Engine implementation this can be ignored or respected. This is exposed to third parties in BasicEditField.

Since:

JDE 4.0.2

NO_LEARNING

public static final long NO_LEARNING

Suggests auto learning feature disable for current text component. Depending on Input method/Conversion Engine implementation this can be ignored or respected. This is exposed to third parties in BasicEditField.

Since:

JDE 4.0.2

JUMP_FOCUS_AT_END

public static final long JUMP_FOCUS_AT_END

Enables jump-to-end of field behaviour.

In fields built with this style, when rolling down out of this field the cursor first jumps to the end of the field, rather than exiting the field. Normally, focus leaves on a roll down if the cursor is already at the last character of the field.

Constructor Detail

RichTextField

public RichTextField()

Constructs a plain, empty RichTextField object.

RichTextField

public RichTextField(long style)

Constructs a plain, empty RichTextField in the specified style.

Parameters:

style - Style for this field; set to Field.NON_FOCUSABLE if the field should not have focus.

RichTextField

public RichTextField(String text)

Constructs a plain RichTextField object.

Parameters:

text - Initial text to show in this field.

RichTextField

public RichTextField(String text,
                     long style)

Constructs a plain RichTextField object in the specified style.

If you want to build a field that does not accept the focus, specify the Field.NON_FOCUSABLE style.

Parameters:

text - Initial text to show in this field.

style - Style for this field.

RichTextField

public RichTextField(String text,
                     int[] offsets,
                     byte[] attributes,
                     Font[] fonts,
                     long style)

Constructs a formatted RichTextField object in the specified style.

See the class description for field behaviour regarding formatting.

If you want to build a field that does not accept the focus, specify the Field.NON_FOCUSABLE style.

Parameters:

text - Text to show in this field.

offsets - List of character offsets that mark formatting changes.

attributes - List that associates this field's formatting regions with the font formats used.

fonts - List of fonts formats for this field.

style - Styles for this field.

Throws:

IllegalArgumentException - If one of the parameters is invalid (for instance an offsets array with the final position not equal to the length of the text, or an attributes array that is not one less in length than the offsets array).

RichTextField

public RichTextField(String text,
                     int[] offsets,
                     byte[] attributes,
                     Font[] fonts,
                     Object[] cookies,
                     long style)

Constructs a formatted RichTextField object in the specified style, and with corresponding cookies.

See the class description for field behaviour regarding formatting.

If you want to build a field that does not accept the focus, specify the Field.NON_FOCUSABLE style.

Parameters:

text - Text to show in this field.

offsets - List of character offsets that mark formatting changes.

attributes - List that associates this field's formatting regions with the font formats used.

fonts - List of fonts formats for this field.

cookies - List of object cookies corresponding to the offset list.

style - Styles for this field.

Throws:

IllegalArgumentException - If one of the parameters is invalid (for instance an offsets array with the final position not equal to the length of the text, or an attributes array that is not one less in length than the offsets array).

Method Detail

getCursorPosition

public int getCursorPosition()

Retrieves index of current cursor position.

Overrides:

getCursorPosition in class net.rim.device.api.ui.component.TextField

Returns:

Character index of current cursor position, counting from the first character in this field's buffer.

getText

public String getText()

Retrieves this field's text.

Overrides:

getText in class net.rim.device.api.ui.component.TextField

Returns:

The text contained in this field.

keyChar

protected boolean keyChar(char key,
                          int status,
                          int time)

Traps character generation events.

This method, invoked by this field's manager, handles key generation events. This method does not consume the key event, except in the following cases:

• The field supports copy operations, in which case those key operations are handled.
• The field has no current selection (or does not support selection), and the SPACE key was pressed, this method prompts this field to scroll downwards.

Overrides:

keyChar in class Field

Parameters:

key - Character generated by the event.

status - Modifier key status.

time - Number of milliseconds since the device was turned on.

Returns:

True if the event was consumed; otherwise, false.

layout

protected void layout(int width,
                      int height)

Lays out this field's contents.

This field's manager invokes this method during the layout process to instruct this field to arrange its contents, given an amount of available space.

Overrides:

layout in class Field

Parameters:

width - Horizontal space available.

height - Vertical space available.

moveFocus

public int moveFocus(int amount,
                     int status,
                     int time)

Handles moving focus within this field.

This field's manager invokes this method to prompt this field to handle a focus move event. If the event is an ALT-roll, then the focus move happens horizontally (character by character); otherwise, the focus movement happens vertically (line by line).

If this field has an empty text buffer, then this method returns the entire scroll amount. Otherwise, it just returns any scroll amount not used when the focus leaves the field.

Overrides:

moveFocus in class net.rim.device.api.ui.component.TextField

Parameters:

amount - Number of positions to move, positive means down, negative up.

status - Modifier key status

time - Number of milliseconds since the device was turned on.

Returns:

Remaining scroll amount not used up, with the same sign.

paint

protected void paint(Graphics graphics)

Redraws this field.

This field's manager invokes this method during the repainting process to instruct this field to repaint itself.

Overrides:

paint in class Field

Parameters:

graphics - Graphics context for repainting this field.

setText

public void setText(String text)

Provides new text for this field to show.

Notice that calling this method wipes any text formatting this field previously had.

Parameters:

text - New text to show in this field.

setText

public void setText(String text,
                    int[] offsets,
                    byte[] attributes,
                    Font[] fonts)

Provides new, foramtted text for this field to show, with associated cookies.

If you provide a null offsets parameter, then this method assumes your text is not formatted, and so ignores the attributes and fonts parameters.

See the class description for information on field formatting.

Parameters:

text - New text to show in this field.

offsets - List of character offsets that mark formatting changes.

attributes - List that associates this field's formatting regions with the font formats used.

fonts - List of fonts formats for the new text.

Throws:

IllegalArgumentException - If one of the parameters is invalid (for instance an offsets array with the final position not equal to the length of the text, or an attributes array that is not one less in length than the offsets array).

setText

public void setText(String text,
                    int[] offsets,
                    byte[] attributes,
                    Font[] fonts,
                    Object[] cookies)

Provides new, foramtted text for this field to show, with associated cookies.

If you provide a null offsets parameter, then this method assumes your text is not formatted, and so ignores the attributes, fonts, and cookies parameters.

See the class description for information on field formatting.

Parameters:

text - New text to show in this field.

offsets - List of character offsets that mark formatting changes.

attributes - List that associates this field's formatting regions with the font formats used.

fonts - List of fonts formats for the new text.

cookies - List of cookie objects for the new text.

Throws:

IllegalArgumentException - If one of the parameters is invalid (for instance an offsets array with the final position not equal to the length of the text, or an attributes array that is not one less in length than the offsets array).

setCursorPosition

public void setCursorPosition(int offset)

Places cursor on specific character within this field, at user request.

Overrides:

setCursorPosition in class net.rim.device.api.ui.component.TextField

Parameters:

offset - Character index to receive the cursor, counting from the first character in this field's buffer.

getText

public String getText(int offset,
                      int length)

Retrieves a substring of this field's contained text.

Overrides:

getText in class net.rim.device.api.ui.component.TextField

Parameters:

offset - First character in the substring to retrieve.

length - Number of characters in the substring to retrieve.

Returns:

Specified substring.

Throws:

IndexOutOfBoundsException - If the offset is negative, or the length is larger than the total text length, or if the offset is greater than the length.

getTextLength

public int getTextLength()

Retrieves the number of characters in this field's contained text.

Overrides:

getTextLength in class net.rim.device.api.ui.component.TextField

Returns:

Number of characters contained in this field.

isSelectable

public boolean isSelectable()

Determines if this field supports selection.

If this field was built with Field.NON_FOCUSABLE or if this field currently has no characters, then this method returns false; otherwise it returns true.

Overrides:

isSelectable in class net.rim.device.api.ui.component.TextField

Returns:

True if this field supports selection; otherwise, false.

charAt

public char charAt(int offset)

Retrieves a specific contained character from this field.

Overrides:

charAt in class net.rim.device.api.ui.component.TextField

Parameters:

offset - Position of specified character within this field. The first character in the field has an offset of 0.

Returns:

Character at specified offset.

Throws:

IndexOutOfBoundsException - If the offset argument is negative or larger than the length of this field's contained text.

getRegion

public int getRegion(int offset)

Retrieves the formatting region index containing specified character position.

Parameters:

offset - Character position for which to determine containing formatting region.

Returns:

Index of the formatting region within this field's offset list (see class description) containing specified character position.

getRegionCookie

public Object getRegionCookie()

Retrieves the cookie for the formatting region containing the current offset.

Returns:

Cookie associated with the formatting region containing the current offset, or null if no cookie set for that region.

getRegionCookie

public Object getRegionCookie(int region)

Retrieves the cookie for a specified formatting region.

Parameters:

region - Index of the formatting region within this field's offset list (see class description).

Returns:

Cookie associated with the specified formatting region, or null if no cookie set for that region.

getRegionText

public String getRegionText()

Retrieves raw text in the formatting region containing the current offset.

Returns:

Unformatted (raw) text in the formatting region containing the current offset.

getRegionText

public String getRegionText(int region)

Retrieves raw text in a specified formatting region.

Parameters:

region - Index of the formatting region within this field's offset list (see class description).

Returns:

Unformatted (raw) text in the specified formatting region.

getRegionFont

public Font getRegionFont()

Retrieves font format used in the formatting region containing the current offset.

Returns:

Font object used to format the formatting region containing the current offset.

getRegionFont

public Font getRegionFont(int region)

Retrieves font format used in a specified region.

Parameters:

region - Index of the formatting region within this field's offset list (see class description).

Returns:

Font object used to format the specified formatting region.

getFonts

protected Font[] getFonts()

Retrieves this field's font list.

Use this method to retrieve the list of font formats used by this field (see class description).

Returns:

Array of fonts formats being used by the field.

setFont

public void setFont(Font font)

Sets the font used by this field if only one in the list of fonts (see class description).

Overrides:

setFont in class Field

Parameters:

font - to be set in the field.

Since:

JDE 4.0.2

getOffsets

protected int[] getOffsets()

Retrieves this field's offset list.

Use this method to retrieve the list of offsets that define this field's formatting regions (see class description).

Returns:

Array of offsets defining this field's formatting regions.

getAttributes

protected byte[] getAttributes()

Retrieves this field's attributes list.

Use this method to retrieve this field's attribute list (the list that matches the regions described in the offsets list with the formats described in the fonts list--see class description).

Returns:

Array of attributes that link this field's formatting regions with the formats used in those regions.

getForegroundColors

protected int[] getForegroundColors()

Retrieves this field's foreground color list.

Use this method to retrieve this field's foreground color list

Returns:

Array of colors that link this field's formatting regions with the foreground colors used in those regions.

Since:

JDE 4.0.0

getBackgroundColors

protected int[] getBackgroundColors()

Retrieves this field's background color list.

Use this method to retrieve this field's background color list

Returns:

Array of colors that link this field's formatting regions with the background colors used in those regions.

Since:

JDE 4.0.0

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)

Draws the focus indicator for this field.

This field's manager invokes this method after painting the field, in order to overpaint the focus indicator. By default, this method simply inverts the pixels in the focus's extent.

Note that if currently selecting more than one character in this field, then the focus region occupies the entire extent of the selected text.

Overrides:

drawFocus in class Field

Parameters:

graphics - Graphics context for drawing the focus.

on - This parameter is ignored -- the focus is aways set at the location at which it is drawn.

getFocusRect

public void getFocusRect(XYRect rect)

Retrieves the extent of the focus region.

The framework invokes this method to retrieve this field's current focus region.

Overrides:

getFocusRect in class Field

Parameters:

rect - To contain the focus extent for this field, in local coordinates.

getLabelLength

protected int getLabelLength()

Retrieves the length of this field's label.

By default, this method returns 0; extending classes that support field labels should override this method.

Returns:

Number of characters in this field's label.

isSelecting

public final boolean isSelecting()

Determines if this field is currently selecting text.

Overrides:

isSelecting in class Field

Returns:

True if this field currently is in select mode (i.e. rolling the trackwheel expands or contracts the extent of the currently selected text).

isSelectionCopyable

public boolean isSelectionCopyable()

Determines if this field supports copy operations.

This method returns true if there is currently a selection (fields that can select text always have a selection, even if it's zero characters in size).

Overrides:

isSelectionCopyable in class Field

Returns:

True if this field currently has a selection.

isSelectionDeleteable

public boolean isSelectionDeleteable()

Determines if this field supports cut operations.

Overrides:

isSelectionDeleteable in class Field

Returns:

True if this field supports cut; otherwise, false.

isPasteable

public boolean isPasteable()

Determines if this field supports paste operations.

Overrides:

isPasteable in class Field

Returns:

True if this field is Field.EDITABLE; otherwise, false.

moveFocus

protected void moveFocus(int x,
                         int y,
                         int status,
                         int time)

Handles moving the focus to an exact position within this field.

This field's manager invokes this method when moving the focus to an exact position within this field, and only when this field already has the focus.

Overrides:

moveFocus in class Field

Parameters:

x - Distance from left edge of this field for new focus position.

y - Distance from top edge of this field for new focus position.

status - Modifier key status.

time - Number of milliseconds since the device was turned on.

onFocus

protected void onFocus(int direction)

Positions cursor when this field first receives the focus.

Text fields exhibit special behaviour for onFocus.

If no cursor position was currently set... If the focus entered this field from the "top", then this method places the initial cursor at the first character in this field's value.

If the focus entered this field from the "bottom", then this method places the initial cursor on the last character in this field's value.

If the focus event indicated no direction, this method does nothing.

If the cursor position was already set... If the cursor position was preivously set externally (ie through a call to TextField.setCursorPosition(int), then the cursor is rendered at the set position. However, this state is erased once the control gains focus.

Overrides:

onFocus in class Field

Parameters:

direction - Direction of cursor movement; greater than zero means it came from above this field, less than zero means it came from below this field, zero means focus is being set to the field directly (that is, not by means of a trackwhell roll).

select

public void select(boolean toggle)

Sets or unsets selection mode.

Invoking this method to false sets the current selection to zero characters, and turns off the behaviour of increasing the selection with cursor movement. There's always a current selection, since that's the key indicator we use to prove this field is supports selection.

Overrides:

select in class Field

Parameters:

toggle - True to turn on selecting mode; false to turn it off.

selectionCopy

public void selectionCopy(Clipboard cb)

Copies the current selection to the clipboard.

Note that this method always succeeds, even if zero characters are copied onto the clipboard. If at least one character exists in the selection to copy, then this method overwrites the clipboard's previous contents.

Overrides:

selectionCopy in class Field

Parameters:

cb - Clipboard to contain copied text.

setCursorPosition

protected void setCursorPosition(int offset,
                                 int context)

Sets the cursor position to the specified offset.

Parameters:

offset - Offset from the beginning of the text to set the cursor position.

context - Information specifying the origin of the change.

toString

public String toString()

Retrieves this field's text in a string.

Overrides:

toString in class Object

Returns:

String containing this field's text.