|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.ui.Field
net.rim.device.api.ui.component.TextField
net.rim.device.api.ui.component.RichTextField
public class RichTextField
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
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.component.TextField |
---|
CONSUME_INPUT, DEFAULT_MAXCHARS, JUMP_FOCUS_AT_END, NO_COMPLEX_INPUT, NO_EDIT_MODE_INPUT, NO_LEARNING, NO_NEWLINE, NO_SWITCHING_INPUT |
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, getFilter, getFocusRect, getLabel, getLabelLength, getMaxSize, getPreferredWidth, getText, getTextAbstractString, insert, insert, isPasteable, isSelecting, isSelectionCopyable, isSelectionDeleteable, isSymbolScreenAllowed, keyControl, makeContextMenu, moveFocus, navigationClick, navigationUnclick, onFocus, paste, select, selectionCopy, selectionDelete, setCursorPosition, setFilter, setLabel, setMaxSize, setText, toString, touchEvent, update, wipe |
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 |
---|
public static final int TEXT_ALIGN_LEFT
public static final int USE_TEXT_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.
public static final int TEXT_ALIGN_HCENTER
public static final int TEXT_ALIGN_RIGHT
Constructor Detail |
---|
public RichTextField()
public RichTextField(long style)
style
- Style for this field; set to
Field.NON_FOCUSABLE
if the field should not have focus.public RichTextField(String text)
text
- Initial text to show in this field.public RichTextField(String text, long style)
If you want to build a field that does not accept the focus, specify
the Field.NON_FOCUSABLE
style.
text
- Initial text to show in this field.style
- Style for this field.public RichTextField(String text, int[] offsets, byte[] attributes, Font[] fonts, long 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.
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.
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).public RichTextField(String text, int[] offsets, byte[] attributes, Font[] fonts, Object[] cookies, long 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.
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.
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 |
---|
protected boolean keyChar(char key, int status, int time)
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:
keyChar
in class TextField
key
- Character generated by the event.status
- Modifier key status.time
- Number of milliseconds since the device was turned on.
public int moveFocus(int amount, int status, int time)
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.
moveFocus
in class TextField
amount
- Number of positions to move, positive means down, negative
up.status
- Modifier key statustime
- Number of milliseconds since the device was turned on.
public void setText(String text)
Notice that calling this method wipes any text formatting this field previously had.
setText
in class TextField
text
- New text to show in this field.public void setText(String text, int[] offsets, byte[] attributes, Font[] fonts)
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.
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.
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).public void setText(String text, int[] offsets, byte[] attributes, Font[] fonts, Object[] 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.
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.
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).public int getRegion(int offset)
offset
- Character position for which to determine containing
formatting region.
public Object getRegionCookie()
public Object getRegionCookie(int region)
region
- Index of the formatting region within this field's offset
list (see class description).
public String getRegionText()
public String getRegionText(int region)
region
- Index of the formatting region within this field's offset
list (see class description).
public Font getRegionFont()
public Font getRegionFont(int region)
region
- Index of the formatting region within this field's offset
list (see class description).
protected Font[] getFonts()
Use this method to retrieve a copy of the list of font formats used by this field (see class description).
protected int[] getOffsets()
Use this method to retrieve a copy of the list of offsets that define this field's formatting regions (see class description).
protected byte[] getAttributes()
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).
protected int[] getForegroundColors()
Use this method to retrieve a copy of this field's foreground color list
protected int[] getBackgroundColors()
Use this method to retrieve a copy of this field's background color list
public int getCursorPosition()
TextField
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).
getCursorPosition
in class TextField
public int getPreferredHeight()
TextField
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.
getPreferredHeight
in class TextField
public String getText()
TextField
getText
in class TextField
protected void layout(int width, int height)
TextField
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.
layout
in class TextField
width
- Horizontal space available.height
- Vertical space available.protected void paint(Graphics graphics)
TextField
This field's manager invokes this method during the repainting process to instruct this field to repaint itself.
paint
in class TextField
graphics
- Graphics context for repainting this field.public void setCursorPosition(int offset)
TextField
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.
setCursorPosition
in class TextField
offset
- Character position to receive the cursor, counting from the
first character in this field's value.public String getText(int offset, int length)
TextField
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.
getText
in class TextField
offset
- First character to return.length
- Number of characters to return; must be at least 1.
public int getTextLength()
TextField
getTextLength
in class TextField
public boolean isSelectable()
TextField
This method returns true as long as this field contains at least one character.
isSelectable
in class TextField
public char charAt(int offset)
TextField
Index zero is the first character position after this field's label.
charAt
in class TextField
offset
- Index of the character to retrieve.
public void setFont(Font font)
TextField
setFont
in class TextField
font
- New font for this field.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.