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:
ActiveRegionSupport.ActiveRegionFieldIf, CookieProvider, FieldLabelProvider, Formatter.TextRenderer, IComponent, InputMethodListener, InputMethodRequests, Runnable

public class ActiveAutoTextEditField
extends AutoTextEditField
implements CookieProvider, Runnable, ActiveRegionSupport.ActiveRegionFieldIf

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.AutoTextEditField
AUTOCAP_OFF, AUTOPERIOD_OFF, AUTOREPLACE_OFF
 
Fields inherited from class net.rim.device.api.ui.component.BasicEditField
FILTER_DEFAULT, FILTER_EMAIL, FILTER_FILENAME, FILTER_HEXADECIMAL, FILTER_INTEGER, FILTER_LOWERCASE, FILTER_NUMERIC, FILTER_PHONE, FILTER_PIN_ADDRESS, FILTER_REAL_NUMERIC, FILTER_UPPERCASE, FILTER_URL
 
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
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)
          Deprecated.  
 Category: Framework protected  void fieldChangeNotify(int context)
          Invoked for this field when a change event occurs.
 Category: Framework  Object getCookieWithFocus()
          Generates a cookie for the current region with focus.
   void getFocusRect(XYRect rect)
          Retrieves the extent of the focus region.
 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.
 Category: Framework protected  boolean invokeAction(int action)
          Check whether action is handled by the ActiveFieldCookie in focus
   boolean isSelectionCopyable()
          Determines if this field supports copy operations.
   boolean isSelectionDeleteable()
          Determines if this field supports cut operations.
  protected  boolean isSymbolScreenAllowed()
          Determines if this field supports use of the symbol screen.
  protected  boolean keyChar(char key, int status, int time)
          Traps key generation events.
  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.
  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.
 
Methods inherited from class net.rim.device.api.ui.component.AutoTextEditField
backspace, insert, keyRepeat, moveFocus, setText, update
 
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, getLabel, getLabelLength, getMaxSize, getPreferredHeight, getPreferredWidth, getText, getTextLength, insert, insert, layout, makeContextMenu, moveFocus, onUnfocus, setCursorPosition, setCursorPosition, setFilter, setFont, setLabel, setMaxSize, wipe
 
Methods inherited from class net.rim.device.api.ui.component.TextField
drawText, isPasteable, isSelectable, isSelecting, navigationClick, navigationUnclick, select, toString
 
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, keyStatus, keyUp, navigationMovement, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, 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
 

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 EditField#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

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

drawText

protected int drawText(Graphics graphics,
                       int x,
                       int y,
                       int offset,
                       int length)
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

fieldChangeNotify

protected void fieldChangeNotify(int context)
Description copied from class: TextField
Invoked for this field when a change event occurs.

Custom fields should call this function when their state changes.

The dirty state is cleared if the change was programmatic, and is set (dirtied) if the change was user driven.

Overrides:
fieldChangeNotify in class TextField
Since:
JDE 4.3.0
See Also:
Field.fieldChangeNotify(int)
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 focused 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.

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

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

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

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

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

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

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

isSelectionDeleteable

public boolean isSelectionDeleteable()
Determines if this field supports cut operations.

Overrides:
isSelectionDeleteable in class TextField
Returns:
True if this field supports cut; otherwise, false.
Since:
JDE 4.2.0

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

keyChar

protected boolean keyChar(char key,
                          int status,
                          int time)
Description copied from class: AutoTextEditField
Traps key generation events.

This field's manager invokes this event to handle all key generation events, except for the special symbol screen event (triggered with ALT+SPACE) which is handled by AutoTextEditField.keyDown(int, int).

This method consumes all key events, except in the following cases:

  • This field does not accept new lines (was built with TextField.NO_NEWLINE, and the ENTER key was pressed.
  • This field is not EDITABLE (exception: if in select mode, and the ENTER key was pressed).
  • The BACKSPACE key was pressed while the cursor was over the first character in the field.
  • The ESCAPE key was pressed.
  • This method attempted to insert a typed character into this field, and the insertion failed.
Overrides:
keyChar in class AutoTextEditField
Since:
JDE 4.2.1
See Also:
We need to track user events in order to know when to replace smileys later on

keyControl

protected boolean keyControl(char key,
                             int status,
                             int time)
Description copied from class: TextField
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.0

Following copied from class: TextField
Parameters:
key - Character generated.
status - Modifier key status. See KeypadListener.
time - Number of milliseconds since the device was turned on.
Returns:
True if this method consumed the event; otherwise, false.

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

onFocus

protected void onFocus(int direction)
Invoked when focus passes to field (activated)
Overrides:
onFocus in class 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.0

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

Following copied from class: TextField
Parameters:
graphics - Graphics context for repainting this field.

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

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

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

scanForActiveRegions

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

The scan is performed in the background.

Since:
JDE 4.0.0

scrollHorizontally

protected int scrollHorizontally(int amount)
Description copied from class: 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 TextField
Since:
JDE 4.0.0

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 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.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.
Returns:
True.
Since:
JDE 4.0.0

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

Following copied from class: TextField
See Also:
Field.isSelectionDeleteable(), Field.selectionCut(net.rim.device.api.system.Clipboard)

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