SHOW Framework
 

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

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--net.rim.device.api.ui.component.TextField
              |
              +--net.rim.device.api.ui.component.RichTextField
                    |
                    +--net.rim.device.api.ui.component.ActiveRichTextField
All Implemented Interfaces:
ActiveRegionSupport.ActiveRegionFieldIf, CookieProvider, FieldLabelProvider, Formatter.TextRenderer, IComponent, InputMethodListener, InputMethodRequests

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:
JDE 4.0.0

Field Summary
protected  long[] _cookieID
          Array of cookie types, one for each region.
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.
 
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, 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, 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 net.rim.device.apps.api.ui.CookieProviderUtilities#getFocusVerbs 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.
 Category: Framework  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.
 Category: Framework protected  boolean invokeAction(int action)
          Check whether action is handled by the ActiveFieldCookie in focus
 Category: Framework 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 colour 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 coloured 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, 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, update, wipe
 
Methods inherited from class net.rim.device.api.ui.Field
drawHighlightRegion, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, isDataValid, isDirty, isEditable, isFocus, isFocusable, isMuddy, isSelectionCutable, isSpellCheckable, isStyle, isVisible, keyRepeat, keyStatus, keyUp, navigationMovement, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onUnfocus, onVisibilityChange, selectionCut, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setMuddy, setNonSpellCheckable, setPosition, setVisualState, trackwheelClick, trackwheelUnclick, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

_cookieID

protected long[] _cookieID
Array of cookie types, one for each region.
Since:
JDE 4.0.0

INVALID_COOKIE_ID

protected static final long INVALID_COOKIE_ID
Placeholder to flag invalid cookie regions.
Since:
JDE 4.0.0

SCANFLAG_DISABLE_ALL_THREADING

public static final int SCANFLAG_DISABLE_ALL_THREADING
Disable all threading when scanning.
Since:
JDE 4.0.0

SCANFLAG_THREAD_ON_CREATE

public static final int SCANFLAG_THREAD_ON_CREATE
Enable threads on creation.
Since:
JDE 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:
JDE 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:
JDE 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:
JDE 4.0.0
Method Detail

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 indictor. 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:
JDE 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:
JDE 4.0.0

executeBackgroundScan

protected void executeBackgroundScan()
Executes the string pattern scan on a background thread
Since:
JDE 4.0.0

getContextMenuContext

protected Object getContextMenuContext()
Retrieves the context object to be passed to net.rim.device.apps.api.ui.CookieProviderUtilities#getFocusVerbs to fetch the context menu verbs.
Returns:
Null; sub-classes should override this to provide more specific functionality.
Since:
JDE 4.0.0

getCookieWithFocus

public Object getCookieWithFocus()
Retrieves the cookie for the region currently with the focus.
Returns:
Cookie for the currently focused region, or null if no associated cookie.
Since:
JDE 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:
JDE 4.2.0

getMainScreenManager

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

Returns null.
Since:
JDE 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:
JDE 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:
JDE 4.0.0
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

getScanFlags

public static int getScanFlags()
Retrieves flags that govern scanning functionality.
Returns:
Current scanning flags set.
Since:
JDE 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.
Since:
JDE 4.0.0

invokeAction

protected boolean invokeAction(int action)
Check whether action is handled by the ActiveFieldCookie in focus
Overrides:
invokeAction in class Field
Since:
JDE 4.6.0

Following copied from class: Field
Parameters:
action - the action to be performed on this field.
Returns:
true if the action was consumed; false if the action was not consumed.
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

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:
JDE 4.0.0
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

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:
JDE 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:
JDE 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:
JDE 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:
JDE 4.0.0

setAttributes

public void setAttributes(int[] colorForeground,
                          int[] colorBackground)
Sets new colour attributes for this field.
Overrides:
setAttributes in class RichTextField
Parameters:
colorForeground - New foreground colour attributes.
colorBackground - New background colour attributes.
Since:
JDE 4.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:
JDE 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:
JDE 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:
JDE 4.0.0

setText

public void setText(String text,
                    int[] offsets,
                    byte[] attributes,
                    Font[] fonts,
                    int[] foregroundColors,
                    int[] backgroundColors)
Provides new, formatted and coloured 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:
JDE 4.0.0



Copyright 1999-2009 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.