SHOW Framework

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

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--net.rim.device.api.ui.component.TextField
              |
              +--net.rim.device.api.ui.component.BasicEditField
                    |
                    +--net.rim.device.api.ui.component.EditField
                          |
                          +--net.rim.device.api.ui.component.AutoTextEditField
                                |
                                +--net.rim.device.api.ui.component.ActiveAutoTextEditField
All Implemented Interfaces:
CookieProvider, IComponent, InputMethodListener, InputMethodRequests, Runnable

public class ActiveAutoTextEditField
extends AutoTextEditField
implements CookieProvider, Runnable

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 thumbclicks on them.

To add new data types to the recognizer set:

  1. Extend a StringPattern and add it to the StringPatternRepository.
  2. Create an object describing the new data that implements the ActiveFieldCookie interface
  3. Create a Factory for this new object, add the factory to the RuntimeStore with an appropriate Long ID (GUID).
  4. When a string region matches your data set, fill out the appropriate fields inside the Match class. Set the Match.id field to the GUID of the factory.
  5. When the cursor is over the region matcing your data set as described above, the system will pass an ActiveFieldContext instance that contains the String region into your Factory. Use this String to initialize your object.

Since:
JDE 4.0.0
See Also:
CookieProvider, ActiveFieldCookie

Field Summary
   
Fields inherited from class net.rim.device.api.ui.component.BasicEditField
CONSUME_INPUT, DEFAULT_MAXCHARS, FILTER_DEFAULT, FILTER_EMAIL, FILTER_HEXADECIMAL, FILTER_INTEGER, FILTER_LOWERCASE, FILTER_NUMERIC, FILTER_PHONE, FILTER_PIN_ADDRESS, FILTER_REAL_NUMERIC, FILTER_UPPERCASE, FILTER_URL, JUMP_FOCUS_AT_END, NO_COMPLEX_INPUT, NO_LEARNING, NO_NEWLINE
 
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
  ActiveAutoTextEditField(String label, String initialValue)
          Constructs a new ActiveAutoTextEditField instance.
  ActiveAutoTextEditField(String label, String initialValue, int maxNumChars)
          Constructs a new, smaller ActiveAutoTextEditField instance.
  ActiveAutoTextEditField(String label, String initialValue, int maxNumChars, long style)
          Constructs a new, smaller ActiveAutoTextEditField instance, of a given style.
 
Method Summary
  protected  void drawFocus(Graphics graphics, boolean on)
          Draws the focus indicator for this field.
  protected  int drawText(Graphics graphics, int x, int y, int offset, int length)
          Draws a line of text to the screen.
 Category: Framework  Object getCookieWithFocus()
          Generates a cookie for the current region with focus.
 Category: Framework protected  int getRegion()
          Searches for region containing the current cursor position.
 Category: Framework protected  int getRegion(int curPos)
          Searches for region containing the specified cursor position.
 Category: Framework protected  String getRegionText(int region)
          Retrieves the text under the specified hyperlink 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.
   AbstractString getTextAbstractString()
          Retrieves this field's text "as is" including embedded graphics characters.
   int insert(String text, int context, boolean stripInvalid, boolean validateText)
          Inserts a string into this field, potentially stripping new lines and/or validating entered value.
  protected  boolean isSymbolScreenAllowed()
          Determines if this field supports use of the symbol screen.
  protected  boolean keyControl(char key, int status, int time)
          Handles control character generation events.
 Category: Framework protected  boolean keyDown(int keycode, int time)
          Handles symbol screen key sequences.
 Category: Framework protected  void makeContextMenu(ContextMenu contextMenu)
          Builds this field's context menu.
  protected  void onFocus(int direction)
          Invoked when focus passes to field (activated)
  protected  void paint(Graphics graphics)
          Redraws this field.
   boolean paste(Clipboard cb)
          Paste the contents of the provided clipboard into this field.
 Category: Framework protected  boolean regionHasCookie()
          Determines if the cursor is on top of a cookie region.
 Category: Framework protected  boolean regionHasCookie(int region)
          Determines if provided region has an associated cookie.
   void run()
          Implements Runnable interface.
   void scanForActiveRegions()
          Scans for active regions in this field.
  protected  int scrollHorizontally(int amount)
          Moves the cursor position horizontally.
  protected  int scrollVertically(int amount)
          Handles moving focus vertically within this field.
   void selectionCopy(Clipboard cb)
          Copies the current selection to the clipboard.
   void selectionDelete()
          Deletes active auto text, or deletes selection.
   void setText(String text)
          Sets the text value for this field.
  protected  void update(int delta)
          Invoked when characters have been inserted in or removed from this field.
 
Methods inherited from class net.rim.device.api.ui.component.AutoTextEditField
backspace, insert, keyChar, keyRepeat, moveFocus, setText
 
Methods inherited from class net.rim.device.api.ui.component.EditField
isEnteringRollerCharacter
 
Methods inherited from class net.rim.device.api.ui.component.BasicEditField
backspace, backspace, charAt, clear, displayFieldFullMessage, getCursorPosition, getFilter, getFocusRect, getLabel, getLabelLength, getMaxSize, getPreferredHeight, getPreferredWidth, getText, getTextLength, insert, insert, isPasteable, isSelectable, isSelecting, isSelectionCopyable, isSelectionDeleteable, layout, moveFocus, onUnfocus, onVisibilityChange, select, setCursorPosition, setCursorPosition, setFilter, setFont, setLabel, setMaxSize, setPreLayoutInternal, toString, wipe
 
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, getScreen, getStyle, getTop, getWidth, invalidate, invalidate, isDirty, isEditable, isFocusable, isMuddy, isSelectionCutable, isStyle, isVisible, keyStatus, keyUp, onDisplay, onExposed, onMenuDismissed, onObscured, onUndisplay, selectionCut, 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
Constructor Detail

ActiveAutoTextEditField

public ActiveAutoTextEditField(String label,
                               String initialValue)
Constructs a new ActiveAutoTextEditField instance.

This method builds an editable autotext field that can hold up to BasicEditField.DEFAULT_MAXCHARS.

Parameters:
label - Label for this field.
initialValue - Initial text to show in the buffer.
Since:
JDE 4.0.0

ActiveAutoTextEditField

public ActiveAutoTextEditField(String label,
                               String initialValue,
                               int maxNumChars)
Constructs a new, smaller ActiveAutoTextEditField instance.

This method builds an editable autotext field that can hold a number of characters up to the amount you specify.

Parameters:
label - Label for this field.
initialValue - Initial text to show in the buffer.
maxNumChars - Maximum number of characters this field can hold.
Since:
JDE 4.0.0

ActiveAutoTextEditField

public ActiveAutoTextEditField(String label,
                               String initialValue,
                               int maxNumChars,
                               long style)
Constructs a new, smaller ActiveAutoTextEditField instance, of a given style.

This method builds an autotext field of a specified style, that can hold a number of characters up to the amount you specify.

Parameters:
label - Label for this field.
initialValue - Initial text to show in the buffer.
maxNumChars - Maximum number of characters this field can hold.
style - Styles to apply to this field (for an editable field, specify the style Field.EDITABLE.
Since:
JDE 4.0.0
Method Detail

makeContextMenu

protected void makeContextMenu(ContextMenu contextMenu)
Builds this field's context menu.

Field.getContextMenu() invokes this method to construct this field's context menu, and populates it with items for cutting, copying, pasting if appropriate (that is, if the field is EDITABLE).

Overrides:
makeContextMenu in class BasicEditField
Parameters:
contextMenu - Context menu to build.
Since:
JDE 4.0.2
See Also:
ContextMenu
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 symbol screen key sequences.

This method traps application key presses, and if the appropriate active field data is application invokeable, the appropriate verb is invoked, and the key event consumed.

Overrides:
keyDown in class AutoTextEditField
Parameters:
keycode - Character generated by the event.
time - Number of milliseconds since the device was turned on.
Returns:
True if the key event was consumed; otherwise, false.
Since:
JDE 4.0.2
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

getCookieWithFocus

public Object getCookieWithFocus()
Generates a cookie for the current region with focus.
Returns:
Coookie for focussed 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.

setText

public void setText(String text)
Sets the text value for this field.

This method updates the text contents of this field with new text information. This must be re-parsed against the original patterns array to determine whether the active regions have changed.

Overrides:
setText in class BasicEditField
Parameters:
text - New string value for this field; if null, this method clears the field.
Throws:
IllegalArgumentException - If the text cannot be entered into an edit field.
Since:
JDE 4.0.2

regionHasCookie

protected boolean regionHasCookie()
Determines if the cursor is on top of a cookie region.
Returns:
True if the cursor is on a cookie region; 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

protected boolean regionHasCookie(int region)
Determines if provided region has an associated cookie.
Returns:
True if the cursor is on a cookie region; otherwise, false.
Since:
JDE 4.0.2
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

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 and the current cookie regions.

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 BasicEditField
Parameters:
graphics - Graphics context for drawing the focus.
on - This parameter is ignored; the focus is always set at the location at which it is drawn.
Since:
JDE 4.0.2

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 net.rim.device.api.ui.component.TextField
Parameters:
cb - Clipboard to contain copied text.
Returns:
True.
Since:
JDE 4.0.2

selectionDelete

public void selectionDelete()
Deletes active auto text, or deletes selection.

If selection is made and includes portion of the active auto text, then AutoTextEditField.selectionDelete() is executed for default behaviour.

Overrides:
selectionDelete in class AutoTextEditField
Since:
JDE 4.0.2

scrollHorizontally

protected int scrollHorizontally(int amount)
Description copied from class: net.rim.device.api.ui.component.TextField
Moves the cursor position horizontally.

This method scrolls the cursor position within this field horizontally. If the cursor reaches the last character on a line, it wraps to the first character on the following line. If the cursor reaches the first character on a line, it wraps to the last character on the previous line.

If the cursor reaches either the first character or last character in this field, it will not wrap around the entire field.

The sign of the amount parameter indicates the direction in which to scroll; the parameter's value indicates the number of character positions to scroll.

Overrides:
scrollHorizontally in class net.rim.device.api.ui.component.TextField
Since:
JDE 4.0.2

scrollVertically

protected int scrollVertically(int amount)
Handles moving focus vertically within this field.

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

Overrides:
scrollVertically in class net.rim.device.api.ui.component.TextField
Parameters:
amount - Number of positions to move, positive means down, negative up.
Returns:
Remaining scroll amount not used up, with the same sign.
Since:
JDE 4.0.2

getRegion

protected int getRegion()
Searches for region containing the current cursor position.
Returns:
Region index, or -1 if cursor is not in a 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.

getRegion

protected int getRegion(int curPos)
Searches for region containing the specified cursor position.
Parameters:
curPos - Offset into text string (including label text).
Returns:
Region index, or -1 if cursor position is not in a region.
Since:
JDE 4.0.2
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

getRegionText

protected String getRegionText(int region)
Retrieves the text under the specified hyperlink region.
Parameters:
region - Hyperlink region to examine.
Returns:
Text from specified region.
Since:
JDE 4.0.2
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

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.

This method first verifies that the stored default font is still correct, then invokes the parent's paint method to repaint the field.

Overrides:
paint in class BasicEditField
Parameters:
graphics - Graphics context for repainting this field.
Since:
JDE 4.0.2

drawText

protected int drawText(Graphics graphics,
                       int x,
                       int y,
                       int offset,
                       int length)
Draws a line of text to the screen.

Called by the paint method to draw lines.

Overrides:
drawText in class BasicEditField
Parameters:
x - X position at which to draw.
y - Y position at which to draw.
offset - First character to draw.
length - Number of characters to draw.
Returns:
Actual block width of text drawn.
Since:
JDE 4.0.2

onFocus

protected void onFocus(int direction)
Invoked when focus passes to field (activated)
Overrides:
onFocus in class net.rim.device.api.ui.component.TextField
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 trackwheel roll).
Since:
JDE 4.0.2

update

protected void update(int delta)
Invoked when characters have been inserted in or removed from this field.
Overrides:
update in class AutoTextEditField
Parameters:
delta - Number of characters by which this field has changed, negative (meaning characters have been added) or positive (characters removed).
Since:
JDE 4.0.2

scanForActiveRegions

public void scanForActiveRegions()
Scans for active regions in this field.

The scan is performed in the background.

Since:
JDE 4.0.0

run

public void run()
Implements Runnable interface.

Background threads invoke this method to scan for active regions.

Since:
JDE 4.0.0
See Also:
Thread.run()

keyControl

protected boolean keyControl(char key,
                             int status,
                             int time)
Description copied from class: BasicEditField
Handles control character generation events.

This field's manager invokes this method to send this field a control character event.

Overrides:
keyControl in class BasicEditField
Since:
JDE 4.0.2

isSymbolScreenAllowed

protected boolean isSymbolScreenAllowed()
Determines if this field supports use of the symbol screen.
Overrides:
isSymbolScreenAllowed in class BasicEditField
Returns:
True if this field supports use of the symbol screen.
Since:
JDE 4.0.0

getText

public String getText()
Retrieves this field's text, not including the label.
Overrides:
getText in class BasicEditField
Returns:
Text value contained in this field.
Since:
JDE 4.0.0

getTextAbstractString

public AbstractString getTextAbstractString()
Retrieves this field's text "as is" including embedded graphics characters.
Overrides:
getTextAbstractString in class BasicEditField
Returns:
This field's text including embedded symbols.
Since:
JDE 4.0.0

getText

public String getText(int offset,
                      int length)
Retrieves a portion of this field's text.
Overrides:
getText in class BasicEditField
Parameters:
offset - First character of this field's text to retrieve.
length - Number of characters to retrieve.
Returns:
Actual text retrieved from this field.
Since:
JDE 4.0.2

paste

public boolean paste(Clipboard cb)
Paste the contents of the provided clipboard into this field.

If this field is Field.EDITABLE, this method pastes the contents of the provided clipboard after the current cursor position.

This method attempts to insert as many characters as it can into this field. If this field's capacity is reached before all characters are pasted, then only those that fit are pasted.

If this field currently has some text selected, this method replaces that selection with the contents of the provided clipboard.

Overrides:
paste in class BasicEditField
Parameters:
cb - Clipboard containing text to paste into this field.
Returns:
True if this field is editable; otherwise, false.
Since:
JDE 4.0.2

insert

public int insert(String text,
                  int context,
                  boolean stripInvalid,
                  boolean validateText)
Inserts a string into this field, potentially stripping new lines and/or validating entered value.

This method attempts to insert your specified string at the current cursor position. If this method (even partially) succeeds with the insertion, then it moves the cursor to just after the last character successfully inserted.

If this field's capacity is reached before all characters are inserted, then only those that fit are inserted.

Overrides:
insert in class AutoTextEditField
Parameters:
text - String to insert; if null, nothing happens.
context - Information describing the origin of the change.
stripInvalid - True if this method should strip out invalid characters from the provided text; otherwise, fail if invalid characters exist in the provided text.
validateText - True if this method should validate the provided text before attempting to insert it; otherwise, this method won't attempt to validate your provided text.
Returns:
Actual number of characters successfully inserted.
Since:
JDE 4.0.2


Copyright 1999-2004 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.