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

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.component.TextField
          extended by net.rim.device.api.ui.component.RichTextField
All Implemented Interfaces:
ITextInputStyle
Direct Known Subclasses:
ActiveRichTextField

public class RichTextField
extends 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. 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 RichTextField with a list of cookie objects corresponding to various regions, as determined by the offsets list. If you are using a cookies list, it is highly recommended to assign one element to each region, thus the list is recommended to have 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. For more information on formatting text in a RichTextField, see the BlackBerry Java Application developer guides at www.blackberry.com/go/docs/developers.


Field Summary
static int TEXT_ALIGN_HCENTER
          Deprecated. use TEXT_JUSTIFY_HCENTER instead.
static int TEXT_ALIGN_LEFT
          Deprecated. use TEXT_JUSTIFY_LEFT.
static int TEXT_ALIGN_RIGHT
          Deprecated. use TEXT_JUSTIFY_RIGHT instead.
static int TEXT_JUSTIFY_HCENTER
          Align contained text to the central vertical axis of this field.
static int TEXT_JUSTIFY_LEFT
          Align contained text to the left edge of this field.
static int TEXT_JUSTIFY_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.component.TextField
CONSUME_INPUT, DEFAULT_MAXCHARS, JUMP_FOCUS_AT_END, NO_COMPLEX_INPUT, NO_EDIT_MODE_INPUT, NO_LEARNING, NO_NEWLINE, NO_SWITCHING_INPUT
 
Fields inherited from class net.rim.device.api.ui.Field
ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL
 
Constructor Summary
RichTextField()
          Constructs a plain, empty RichTextField object.
RichTextField(String text)
          Constructs a plain RichTextField object.
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, int[] offsets, byte[] attributes, Font[] fonts, long style)
          Constructs a formatted RichTextField object in the specified style.
RichTextField(String text, long style)
          Constructs a plain RichTextField object in the specified style.
RichTextField(long style)
          Constructs a plain, empty RichTextField in the specified style.
 
Method Summary
 char charAt(int offset)
          Retrieves the character at the specified offset.
protected  byte[] getAttributes()
          Retrieves this field's attributes list.
protected  int[] getBackgroundColors()
          Retrieves this field's background color list.
 int getCursorPosition()
          Retrieves character offset for current cursor position in this field.
protected  Font[] getFonts()
          Retrieves this field's font list.
protected  int[] getForegroundColors()
          Retrieves this field's foreground color list.
protected  int[] getOffsets()
          Retrieves this field's offset list.
 int getPreferredHeight()
          Retrieves this field's preferred height.
 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, not including the label.
 String getText(int offset, int length)
          Retrieves a portion of this field's text.
 int getTextLength()
          Retrieves length of this field's text, not including the label.
 boolean isSelectable()
          Determines if this field supports selection of text.
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 paint(Graphics graphics)
          Redraws this field.
 void setCursorPosition(int offset)
          Places cursor on specific character within this field, at user request.
 void setFont(Font font)
          Sets the font for this field and updates the display if necessary.
 void setText(String text)
          Provides new text for this field to show.
 void setText(String text, int[] offsets, byte[] attributes, Font[] fonts)
          Provides new, formatted text for this field to show, with associated cookies.
 void setText(String text, int[] offsets, byte[] attributes, Font[] fonts, Object[] cookies)
          Provides new, formatted text for this field to show, with associated cookies.
 
Methods inherited from class net.rim.device.api.ui.component.TextField
backspace, backspace, backspace, clear, displayFieldFullMessage, drawFocus, drawText, fieldChangeNotify, getAccessibleContext, getDescription, getFilter, getFocusRect, getLabel, getLabelLength, getMaxSize, getPreferredWidth, getText, getTextAbstractString, getTrackpadScrollAmount, getTrackpadScrollLineSpeed, insert, insert, isPasteable, isSelecting, isSelectionCopyable, isSelectionDeleteable, isSymbolScreenAllowed, keyControl, keyStatus, makeContextMenu, moveFocus, navigationClick, navigationUnclick, onFocus, paste, select, selectionCopy, selectionDelete, setCursorPosition, setDescription, setFilter, setLabel, setMaxSize, setText, toString, touchEvent, update, wipe
 
Methods inherited from class net.rim.device.api.ui.Field
cursorClick, cursorUnclick, drawHighlightRegion, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getScreen, getStyle, getTextFillColor, getTextStrokeColor, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isLeftToRight, isMuddy, isScrollCopyable, isSelectionCutable, isSpellCheckable, isStyle, isVisible, keyDown, keyRepeat, keyUp, navigationMovement, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onUnfocus, onVisibilityChange, selectionCut, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEditable, setEnabled, setExtent, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, trackwheelClick, trackwheelUnclick, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface net.rim.device.api.im.ITextInputStyle
getPreferredInputLocale, getTextInputStyle, isEditable, isUnicodeInputAllowed, updateInputStyle
 



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.

See Also:
Constant Field Values

TEXT_ALIGN_HCENTER

public static final int TEXT_ALIGN_HCENTER
Deprecated. use TEXT_JUSTIFY_HCENTER instead.
Align contained text to the central vertical axis of this field. Retained for legacy code but has been replaced by TEXT_JUSTIFY_HCENTER.

See Also:
Constant Field Values

TEXT_ALIGN_RIGHT

public static final int TEXT_ALIGN_RIGHT
Deprecated. use TEXT_JUSTIFY_RIGHT instead.
Align contained text to the right edge of this field. Retained for legacy code but has been replaced by TEXT_JUSTIFY_RIGHT.

See Also:
Constant Field Values

TEXT_ALIGN_LEFT

public static final int TEXT_ALIGN_LEFT
Deprecated. use TEXT_JUSTIFY_LEFT.
Retained for legacy code but does not produce left-alignment. Use TEXT_JUSTIFY_LEFT instead.

See Also:
Constant Field Values

TEXT_JUSTIFY_HCENTER

public static final int TEXT_JUSTIFY_HCENTER
Align contained text to the central vertical axis of this field.

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

TEXT_JUSTIFY_RIGHT

public static final int TEXT_JUSTIFY_RIGHT
Align contained text to the right edge of this field.

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

TEXT_JUSTIFY_LEFT

public static final int TEXT_JUSTIFY_LEFT
Align contained text to the left edge of this field.

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0


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

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:

Overrides:
keyChar in class TextField
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.

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

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.

Overrides:
setText in class TextField
Parameters:
text - New text to show in this field.

setText

public void setText(String text,
                    int[] offsets,
                    byte[] attributes,
                    Font[] fonts)
Provides new, formatted text for this field to show, with associated cookies.

If you provide a null offsets parameter, this method will initialize offsets to treat the entire text as one region.

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, formatted text for this field to show, with associated cookies.

If you provide a null offsets parameter, this method will initialize offsets to treat the entire text as one region.

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).

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 a copy of the list of font formats used by this field (see class description).

Returns:
Array of fonts formats being used by the field.

getOffsets

protected int[] getOffsets()
Retrieves this field's offset list.

Use this method to retrieve a copy of 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 a copy of 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 a copy of 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:
BlackBerry API 4.0.0

getBackgroundColors

protected int[] getBackgroundColors()
Retrieves this field's background color list.

Use this method to retrieve a copy of 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:
BlackBerry API 4.0.0

getCursorPosition

public int getCursorPosition()
Description copied from class: TextField
Retrieves character offset for current cursor position in this field.

This method does not include the label as part of its accounting (that is, a returned offset of zero means that the cursor is currently sitting on the first character in this field's value).

Overrides:
getCursorPosition in class TextField
Returns:
Character position of current cursor position within this field's value.

getPreferredHeight

public int getPreferredHeight()
Description copied from class: TextField
Retrieves this field's preferred height.

Managers make use of this value during layout. Edit fields determine their preferred height based on the height of the font they're using to display their text contents.

Overrides:
getPreferredHeight in class TextField
Returns:
Preferred height for this field (height of current font).
Since:
BlackBerry API 4.2.1

getText

public String getText()
Description copied from class: TextField
Retrieves this field's text, not including the label.

Overrides:
getText in class TextField
Returns:
Text value contained in this field.

layout

protected void layout(int width,
                      int height)
Description copied from class: TextField
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 TextField
Parameters:
width - Horizontal space available.
height - Vertical space available.

paint

protected void paint(Graphics graphics)
Description copied from class: TextField
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 TextField
Parameters:
graphics - Graphics context for repainting this field.

setCursorPosition

public void setCursorPosition(int offset)
Description copied from class: TextField
Places cursor on specific character within this field, at user request.

This method does not include the label as part of its accounting (that is, an offset of zero represents the first character in this field's text value).

This method assumes the repositioning request was user-initiated.

Overrides:
setCursorPosition in class TextField
Parameters:
offset - Character position to receive the cursor, counting from the first character in this field's value.

getText

public String getText(int offset,
                      int length)
Description copied from class: TextField
Retrieves a portion of this field's text.

Provide a character offset and length to retrieve a substring of this field's contents.

Note: This method includes the label in the field's contents, so if you pass in an offset of zero, the first character returned is the first character of the label.

Note: Different system themes may modify the contents of the label.

Overrides:
getText in class TextField
Parameters:
offset - First character to return.
length - Number of characters to return; must be at least 1.
Returns:
Substring of this field's contents.

getTextLength

public int getTextLength()
Description copied from class: TextField
Retrieves length of this field's text, not including the label.

Overrides:
getTextLength in class TextField
Returns:
Number of characters in this field's text value.

isSelectable

public boolean isSelectable()
Description copied from class: TextField
Determines if this field supports selection of text.

This method returns true as long as this field contains at least one character.

Overrides:
isSelectable in class TextField
Returns:
True if this field supports the selection of text; otherwise, false.

charAt

public char charAt(int offset)
Description copied from class: TextField
Retrieves the character at the specified offset.

Index zero is the first character position after this field's label.

Overrides:
charAt in class TextField
Parameters:
offset - Index of the character to retrieve.
Returns:
Character at your specified offset.

setFont

public void setFont(Font font)
Description copied from class: TextField
Sets the font for this field and updates the display if necessary.

Overrides:
setFont in class TextField
Parameters:
font - New font for this field.
Since:
BlackBerry API 4.0.2





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal