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

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
              extended by net.rim.device.api.ui.component.ActiveRichTextField
All Implemented Interfaces:
ITextInputStyle, CookieProvider

public class ActiveRichTextField
extends RichTextField
implements CookieProvider

Field that uses a supplied set of string patterns to scan through a simple text string and pick out "active" regions.

These active regions are highlighted with underlining and will supply additional menu verbs if the user clicks on them.

Since:
BlackBerry API 4.0.0

Field Summary
protected static long INVALID_COOKIE_ID
          Placeholder to flag invalid cookie regions.
static int SCANFLAG_DISABLE_ALL_THREADING
          Disable all threading when scanning.
static int SCANFLAG_THREAD_ON_CREATE
          Enable threads on creation.
protected  long[] _cookieID
          Array of cookie types, one for each region.
 
Fields inherited from class net.rim.device.api.ui.component.RichTextField
TEXT_ALIGN_HCENTER, TEXT_ALIGN_LEFT, TEXT_ALIGN_RIGHT, USE_TEXT_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
ActiveRichTextField(String text)
          Creates a new ActiveRichTextField instance from provided string after scanning for active "links".
ActiveRichTextField(String text, int[] offsets, byte[] attributes, Font[] fonts, int[] foregroundColors, int[] backgroundColors, long style)
          Creates a new ActiveRichTextField instance from provided formatted string and style flags after scanning for active "links".
ActiveRichTextField(String text, long style)
          Creates a new ActiveRichTextField instance from provided string and style flags after scanning for active "links".
 
Method Summary
protected  void drawFocus(Graphics graphics, boolean on)
          Draws the focus indicator for this field.
protected  int drawText(Graphics graphics, String text, int offset, int len, int x, int y, int flags, int width)
          Deprecated.  
protected  void executeBackgroundScan()
          Executes the string pattern scan on a background thread.
protected  Object getContextMenuContext()
          Retrieves the context object to be passed to CookieProviderUtilities.getFocusVerbs(net.rim.device.api.ui.component.CookieProvider, java.lang.Object, net.rim.device.apps.api.framework.verb.Verb[]) to fetch the context menu verbs.
 Object getCookieWithFocus()
          Retrieves the cookie for the region currently with the focus.
 void getFocusRect(XYRect rect)
          Retrieves the extent of the focus region.
protected  Manager getMainScreenManager()
          Deprecated. Meaningless method accidentally exposed.
 Object getRegionCookie()
          Retrieves the cookie for the region under the current cursor position.
 Object getRegionCookie(int region)
          Generates a cookie for the specified region.
static int getScanFlags()
          Retrieves flags that govern scanning functionality.
 String getText(int offset, int length)
          Retrieves text string from this field.
 boolean isSelectionCopyable()
          Determines if this field supports copy operations.
protected  boolean keyDown(int keycode, int time)
          Handles key down events.
 boolean regionHasCookie()
          Determines if the cursor is on a cookie object.
 boolean regionHasCookie(int region)
          Determine if provided region has an associated cookie.
protected  int scrollVertically(int amount)
          Moves the cursor position vertically.
 void selectionCopy(Clipboard cb)
          Copies the current selection to the clipboard.
 void setAttributes(int[] colorForeground, int[] colorBackground)
          Sets new color attributes for this field.
static void setScanFlags(int flags)
          Sets flags that govern scanning functionality.
 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, int[] foregroundColors, int[] backgroundColors)
          Provides new, formatted and colored text for this field to show, with associated cookies.
 
Methods inherited from class net.rim.device.api.ui.component.RichTextField
charAt, getAttributes, getBackgroundColors, getCursorPosition, getFonts, getForegroundColors, getOffsets, getPreferredHeight, getRegion, getRegionFont, getRegionFont, getRegionText, getRegionText, getText, getTextLength, isSelectable, keyChar, layout, moveFocus, paint, setCursorPosition, setFont, setText
 
Methods inherited from class net.rim.device.api.ui.component.TextField
backspace, backspace, backspace, clear, displayFieldFullMessage, drawText, fieldChangeNotify, getAccessibleContext, getFilter, getLabel, getLabelLength, getMaxSize, getPreferredWidth, getText, getTextAbstractString, insert, insert, isPasteable, isSelecting, isSelectionDeleteable, isSymbolScreenAllowed, keyControl, makeContextMenu, moveFocus, navigationClick, navigationUnclick, onFocus, paste, select, selectionDelete, setCursorPosition, setFilter, setLabel, setMaxSize, setText, toString, touchEvent, update, wipe
 
Methods inherited from class net.rim.device.api.ui.Field
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, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isMuddy, isScrollCopyable, isSelectionCutable, isSpellCheckable, isStyle, isVisible, keyRepeat, keyStatus, 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, 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

SCANFLAG_DISABLE_ALL_THREADING

public static final int SCANFLAG_DISABLE_ALL_THREADING
Disable all threading when scanning.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

SCANFLAG_THREAD_ON_CREATE

public static final int SCANFLAG_THREAD_ON_CREATE
Enable threads on creation.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

_cookieID

protected long[] _cookieID
Array of cookie types, one for each region.

Since:
BlackBerry API 4.0.0

INVALID_COOKIE_ID

protected static final long INVALID_COOKIE_ID
Placeholder to flag invalid cookie regions.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0


Constructor Detail

ActiveRichTextField

public ActiveRichTextField(String text)
Creates a new ActiveRichTextField instance from provided string after scanning for active "links".

Parameters:
text - String to scan and display.
Since:
BlackBerry API 4.0.0

ActiveRichTextField

public ActiveRichTextField(String text,
                           long style)
Creates a new ActiveRichTextField instance from provided string and style flags after scanning for active "links".

Parameters:
text - String to scan and display.
style - Style flags for this field.
Since:
BlackBerry API 4.0.0

ActiveRichTextField

public ActiveRichTextField(String text,
                           int[] offsets,
                           byte[] attributes,
                           Font[] fonts,
                           int[] foregroundColors,
                           int[] backgroundColors,
                           long style)
Creates a new ActiveRichTextField instance from provided formatted string and style flags after scanning for active "links".

Parameters:
text - String to scan and display.
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.
foregroundColors - List of foreground colors for this field.
backgroundColors - List of background colors for this field.
style - Style flags for this field.
Since:
BlackBerry API 4.0.0


Method Detail

executeBackgroundScan

protected void executeBackgroundScan()
Executes the string pattern scan on a background thread.

Since:
BlackBerry API 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 field.

This method also highlights current cookie regions as appropriate.

Overrides:
drawFocus in class TextField
Parameters:
graphics - Graphics context for drawing the focus.
on - If true, focus is over an active region, and entire active text gets highlighted and then cursor superimposed over that; otherwise focus painting happens as normal.
Since:
BlackBerry API 4.0.0

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 TextField
Parameters:
rect - To contain the focus extent for this field, in local coordinates.
Since:
BlackBerry API 4.2.0

getContextMenuContext

protected Object getContextMenuContext()
Retrieves the context object to be passed to CookieProviderUtilities.getFocusVerbs(net.rim.device.api.ui.component.CookieProvider, java.lang.Object, net.rim.device.apps.api.framework.verb.Verb[]) to fetch the context menu verbs.

Returns:
Null; sub-classes should override this to provide more specific functionality.
Since:
BlackBerry API 4.0.0

getRegionCookie

public Object getRegionCookie()
Retrieves the cookie for the region under the current cursor position.

Overrides:
getRegionCookie in class RichTextField
Returns:
Cookie for the region under the cursor, or null if no associated cookie.
Since:
BlackBerry API 4.0.0

getCookieWithFocus

public Object getCookieWithFocus()
Retrieves the cookie for the region currently with the focus.

Specified by:
getCookieWithFocus in interface CookieProvider
Returns:
Cookie for the currently focused region, or null if no associated cookie.
Since:
BlackBerry API 4.0.0

getMainScreenManager

protected Manager getMainScreenManager()
Deprecated. Meaningless method accidentally exposed.

Returns null.

Since:
BlackBerry API 4.0.0

getRegionCookie

public Object getRegionCookie(int region)
Generates a cookie for the specified region.

Overrides:
getRegionCookie in class RichTextField
Parameters:
region - Region for which to generate a cookie.
Returns:
Cookie for provided region, or null if no cookie exists for the region.
Since:
BlackBerry API 4.0.0

getScanFlags

public static int getScanFlags()
Retrieves flags that govern scanning functionality.

Returns:
Current scanning flags set.
Since:
BlackBerry API 4.0.0

keyDown

protected boolean keyDown(int keycode,
                          int time)
Handles key down events. If Keypad.KEY_APPLICATION is pressed while the cursor is over an active region, this method dispatches to the appropriate application key verb for that region. If Keypad.KEY_ENTER is pressed while the cursor is over an active region, this method dispatches to the default menu item verb for that region; otherwise, this method hands the event up to the parent.

Overrides:
keyDown in class Field
Parameters:
keycode - Code of key pressed.
time - Number of milliseconds since the device was turned on.
Returns:
True if event consumed; otherwise, false.
Since:
BlackBerry API 4.0.0

regionHasCookie

public boolean regionHasCookie()
Determines if the cursor is on a cookie object.

Returns:
True if cursor is currently over a region with a cookie; otherwise, false.
Since:
BlackBerry API 4.0.0

regionHasCookie

public boolean regionHasCookie(int region)
Determine if provided region has an associated cookie.

Parameters:
region - Region to test.
Returns:
True if provided region has an associated cookie; otherwise, false.
Since:
BlackBerry API 4.0.0

scrollVertically

protected int scrollVertically(int amount)
Moves the cursor position vertically.

This method moves the cursor position up and down lines within this field. If the cursor reaches the first line, or last line, in this field, it will not wrap around the entire field.

Just before the first vertical scroll, this method remembers the distance of the cursor from the left edge of the field (in pixels). When it scrolls, it places the cursor over the character on the new line that is as close as possible to the offset it remembers from its original position.

If there is another cookie within a line either way of the current position, this method jumps so that the current position is on top of the new cookie.

Overrides:
scrollVertically in class TextField
Parameters:
amount - Amount by which to scroll (positive means down, negative up).
Returns:
Any unused scroll amount.
Since:
BlackBerry API 4.0.0

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 TextField
Parameters:
cb - Clipboard to contain copied text.
Since:
BlackBerry API 4.0.0

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 TextField
Returns:
True if this field currently has a selection.
Since:
BlackBerry API 6.0.0

setScanFlags

public static void setScanFlags(int flags)
Sets flags that govern scanning functionality.

Parameters:
flags - New mask of scanning flags set/unset.
Since:
BlackBerry API 4.0.0

setText

public void setText(String text)
Provides new text for this field to show.

Overrides:
setText in class RichTextField
Parameters:
text - New text to show in this field; this text is re-parsed against the original patterns array to determine whether the active regions have changed.
Since:
BlackBerry API 4.0.0

setText

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

Overrides:
setText in class RichTextField
Parameters:
text - New text to show in this field; this text is re-parsed against the original patterns array to determine whether the active regions have changed.
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.
Since:
BlackBerry API 4.0.0

setText

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

Parameters:
text - New text to show in this field; this text is re-parsed against the original patterns array to determine whether the active regions have changed.
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.
foregroundColors - List of foreground colors for this field.
backgroundColors - List of background colors for this field.
Since:
BlackBerry API 4.0.0

setAttributes

public void setAttributes(int[] colorForeground,
                          int[] colorBackground)
Sets new color attributes for this field.

Overrides:
setAttributes in class RichTextField
Parameters:
colorForeground - New foreground color attributes.
colorBackground - New background color attributes.
Since:
BlackBerry API 4.0.0

getText

public String getText(int offset,
                      int length)
Retrieves text string from this field.

If smileys exist in this field, this method first "decodes" them, and then returns the result.

Overrides:
getText in class RichTextField
Parameters:
offset - First character in field to retrieve.
length - Number of characters to retrieve.
Returns:
Substring of this field's contents.
Since:
BlackBerry API 4.0.0

drawText

protected int drawText(Graphics graphics,
                       String text,
                       int offset,
                       int len,
                       int x,
                       int y,
                       int flags,
                       int width)
Deprecated. 

Does nothing - this method is not called by framework anymore. Use TextField.drawText with DrawTextParam if you really need to override this method.

Since:
BlackBerry API 4.0.0





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.