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

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

public class ActiveAutoTextEditField
extends AutoTextEditField
implements CookieProvider, Runnable

Field that uses a supplied set of string patterns to pick out 'active' regions.

These active regions are underlined and supply context menu items if the user clicks 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 matching 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.

See Also:
CookieProvider, ActiveFieldCookie
Since:
BlackBerry API 4.0.0

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, 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
ActiveAutoTextEditField(String label, String initialValue)
          Constructs a new ActiveAutoTextEditField instance.
ActiveAutoTextEditField(String label, String initialValue, int maxNumChars)
          Constructs a smaller, editable ActiveAutoTextEditField instance that can hold a specified maximum number of characters.
ActiveAutoTextEditField(String label, String initialValue, int maxNumChars, long style)
          Constructs a new, smaller ActiveAutoTextEditField instance, of a given style that can hold a specified maximum number of characters.
 
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.  
protected  void fieldChangeNotify(int context)
          Invoked for this field when a change event occurs.
 Object getCookieWithFocus()
          Generates a cookie for the current region with focus.
 void getFocusRect(XYRect rect)
          Retrieves the extent of the focus region.
protected  int getRegion()
          Searches for region containing the current cursor position.
protected  int getRegion(int curPos)
          Searches for region containing the specified cursor position.
protected  String getRegionText(int region)
          Retrieves the text under the specified hyperlink region.
 String getText()
          Returns the text value contained in this field.
 String getText(int offset, int length)
          Returns a substring of text contained in this field.
 AbstractString getTextAbstractString()
          Returns 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.
 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.
protected  void onFocus(int direction)
          Invoked when focus passes to field (i.e. when the field is activated).
protected  void paint(Graphics graphics)
          Redraws this field.
 boolean paste(Clipboard cb)
          Paste the contents of the provided clipboard into this field.
protected  boolean regionHasCookie()
          Determines if the cursor is on top of a cookie region.
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  boolean touchEvent(TouchEvent message)
          Traps touch input events.
 
Methods inherited from class net.rim.device.api.ui.component.AutoTextEditField
backspace, insert, keyDown, 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, getAccessibleContext, 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, 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, keyStatus, keyUp, navigationMovement, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, 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
 



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

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

ActiveAutoTextEditField

public ActiveAutoTextEditField(String label,
                               String initialValue,
                               int maxNumChars)
Constructs a smaller, editable ActiveAutoTextEditField instance that can hold a specified maximum number of characters.

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

ActiveAutoTextEditField

public ActiveAutoTextEditField(String label,
                               String initialValue,
                               int maxNumChars,
                               long style)
Constructs a new, smaller ActiveAutoTextEditField instance, of a given style that can hold a specified maximum number of characters.

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:
BlackBerry API 4.0.0


Method Detail

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:

Overrides:
keyChar in class AutoTextEditField
Parameters:
key - Character generated by the event.
status - Modifier key status.
time - Number of milliseconds since the device was turned on.
Returns:
True if the event was consumed; otherwise, false.
See Also:
We need to track user events in order to know when to replace smileys later on
Since:
BlackBerry API 4.2.1

touchEvent

protected boolean touchEvent(TouchEvent message)
Traps touch input events.

Overrides:
touchEvent in class TextField
Parameters:
message - TouchEvent object containing various input parameters including the event type and touch coordinates.
Returns:
True if the event was consumed; otherwise, false.
Throws:
IllegalArgumentException - If message is null.
Since:
BlackBerry API 6.0.0

getCookieWithFocus

public Object getCookieWithFocus()
Generates a cookie for the current region with focus.

Specified by:
getCookieWithFocus in interface CookieProvider
Returns:
Cookie for focused region.
Since:
BlackBerry API 4.0.0

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:
BlackBerry API 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 top of a cookie region; otherwise, false.
Since:
BlackBerry API 4.0.0

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

If more than one charater in this field is selected, 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:
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 - The focus extent for this field, in local coordinates.
Since:
BlackBerry API 4.2.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

selectionDelete

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

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

Overrides:
selectionDelete in class AutoTextEditField
See Also:
TextField.isSelectionDeleteable(), Field.selectionCut(net.rim.device.api.system.Clipboard)
Since:
BlackBerry API 4.0.2

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 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:
BlackBerry API 4.2.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
Parameters:
amount - Number of characters by which to scroll (positive means visually right, negative visually left).
Returns:
Any unused scroll amount.
Since:
BlackBerry API 4.0.0

scrollVertically

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

If there is another cookie within a line on either side 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:
BlackBerry API 4.0.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:
BlackBerry API 4.0.0

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:
BlackBerry API 4.0.0

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:
BlackBerry API 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
Parameters:
graphics - Graphics context for repainting this field.
Since:
BlackBerry API 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:
BlackBerry API 4.0.0

onFocus

protected void onFocus(int direction)
Invoked when focus passes to field (i.e. when the field is 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 a trackwheel roll).
Since:
BlackBerry API 4.0.0

scanForActiveRegions

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

The scan is performed in the background.

Since:
BlackBerry API 4.0.0

run

public void run()
Implements Runnable interface.

Background threads invoke this method to scan for active regions.

Specified by:
run in interface Runnable
See Also:
Thread.run()
Since:
BlackBerry API 4.0.0

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

getText

public String getText()
Returns the text value contained in this field.

Overrides:
getText in class BasicEditField
Returns:
Text value contained in this field.
Since:
BlackBerry API 4.0.0

getTextAbstractString

public AbstractString getTextAbstractString()
Returns this field's text "as is" including embedded graphics characters.

Overrides:
getTextAbstractString in class BasicEditField
Returns:
This field's text including embedded symbols.
Since:
BlackBerry API 4.0.0

getText

public String getText(int offset,
                      int length)
Returns a substring of text contained in this field.

Overrides:
getText in class BasicEditField
Parameters:
offset - First character of this field's text to return.
length - Number of characters to return.
Returns:
The specified substring of text contained in this field.
Since:
BlackBerry API 4.0.0

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:
BlackBerry API 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:
BlackBerry API 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
Parameters:
context - Information specifying the origin of the change.
See Also:
Field.fieldChangeNotify(int)
Since:
BlackBerry API 4.3.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.