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

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.PasswordEditField
All Implemented Interfaces:
ITextInputStyle

public class PasswordEditField
extends BasicEditField

An editable text field designed specifically to handle password input.

Behaviour
This field stores the password as plain text but draws it as a series of asterisks, one for each character cluster (group of characters treated as one after diacritics and ligatures have been handled).

This field does not have any automatic input replacement, so the typed text is exactly what is typed. AutoCaps, AutoText, AutoPeriod, and any other transformation are turned off. Also, holding a key and rolling the wheel is not allowed.

This field does not support copy or cut operations.

By default, this field supports all the available characters. You can restrict this by applying a TextFilter.


Field Summary
 
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
PasswordEditField()
          Constructs a new PasswordEditField instance.
PasswordEditField(String label, String initialValue)
          Constructs a PasswordEditField instance with label and initial value.
PasswordEditField(String label, String initialValue, int maxNumChars, long style)
          Constructs a smaller PasswordEditField object.
 
Method Summary
protected  boolean backspace()
          Deletes character to the left of the cursor, or deletes selection.
 int backspace(int count)
          Deletes specified number of characters to the left of the cursor.
protected  int backspace(int count, int context)
          Deletes specified number of characters to the left of the cursor, with indication of source of this action.
 char charAt(int offset)
          Retrieves the character at the specified offset.
 void clear(int context)
          Clears this field's contents.
protected  void displayFieldFullMessage()
          Displays a 'field full' message.
 int getCursorPosition()
          Retrieves character offset for current cursor position in this field.
 String getLabel()
          Retrieves this field's label.
 int getLabelLength()
          Retrieves the length of this field's label The length returned includes any additional character appended for layout purposes.
 int getMaxSize()
          Retrieves the maximum number of characters allowed for this field's value.
 int getPreferredHeight()
          Retrieves this field's preferred height.
 int getPreferredWidth()
          Retrieves this field's preferred width.
 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.
 void getText(int srcBegin, int srcEnd, char[] dst, int dstBegin)
          Retrieves this field's text.
 AbstractString getTextAbstractString()
          Retrieves read-only handle to the underlying buffer.
 int getTextLength()
          Retrieves length of this field's text, not including the label.
 int insert(String text)
          Inserts string programmatically into this field.
protected  int insert(String text, int context)
          Inserts string into this field.
 boolean isSelectionCopyable()
          Determines if this field supports copy operations.
protected  boolean isSymbolScreenAllowed()
          Determines if this field supports use of the symbol screen.
protected  boolean keyRepeat(int keycode, int time)
          Consumes key repeat events.
protected  void onUnfocus()
          Invoked when a field loses the focus.
 boolean paste(Clipboard cb)
          Pastes text scrap into this field.
 void selectionCopy(Clipboard cb)
          Does nothing.
 void selectionDelete()
          Deletes character to the right of the cursor, or deletes selection.
 void setCursorPosition(int offset)
          Places cursor on specific character within this field, at user request.
protected  void setCursorPosition(int offset, int context)
          Places cursor on specific character within this field.
 void setLabel(String newLabel)
          Sets this field's label.
 void setMaxSize(int maxSize)
          Sets maximum number of characters allowed for this field's value.
 void setText(String text)
          Sets the text value for this field.
protected  void setText(String text, int context)
          Sets the text value for this field, with indication of the source of this action.
protected  void update(int delta)
          Updates this edit field.
 void wipe()
          Overwrites this field's unused contents.
 
Methods inherited from class net.rim.device.api.ui.component.BasicEditField
drawFocus, getAccessibleContext, getFilter, keyChar, keyControl, keyDown, layout, makeContextMenu, moveFocus, moveFocus, paint, setFilter, setFont
 
Methods inherited from class net.rim.device.api.ui.component.TextField
drawText, fieldChangeNotify, getDescription, getFocusRect, getTrackpadScrollAmount, getTrackpadScrollLineSpeed, isPasteable, isSelectable, isSelecting, isSelectionDeleteable, keyStatus, navigationClick, navigationUnclick, onFocus, select, setDescription, toString, touchEvent
 
Methods inherited from class net.rim.device.api.ui.Field
cursorClick, cursorUnclick, 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, getTextFillColor, getTextStrokeColor, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isLeftToRight, isMuddy, isScrollCopyable, isSelectionCutable, isSpellCheckable, isStyle, isVisible, 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, setFont, 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

PasswordEditField

public PasswordEditField()
Constructs a new PasswordEditField instance.

This builds a new password edit field with no label and no initial contents.


PasswordEditField

public PasswordEditField(String label,
                         String initialValue)
Constructs a PasswordEditField instance with label and initial value.

This method builds an editable password field that can hold up to TextField.DEFAULT_MAXCHARS characters.

Note that your provided text does not itself show up in the created field; this method shows a string of asterisks of the same length to the user.

Parameters:
label - Label for this field.
initialValue - Initial password value for this field.

PasswordEditField

public PasswordEditField(String label,
                         String initialValue,
                         int maxNumChars,
                         long style)
Constructs a smaller PasswordEditField object.

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

Note that your provided text does not itself show up in the created field; this method shows a string of asterisks of the same length to the user.

Parameters:
label - Label for this field.
initialValue - Initial password value for this field.
maxNumChars - Maximum number of characters this field can hold.
style - Style for this field: this value will be combined with the EDITABLE and NO_NEWLINE styles.


Method Detail

isSelectionCopyable

public final boolean isSelectionCopyable()
Determines if this field supports copy operations.

Overrides:
isSelectionCopyable in class TextField
Returns:
False; password edit fields do not support copy operations.

keyRepeat

protected boolean keyRepeat(int keycode,
                            int time)
Consumes key repeat events.

This method consumes all key repeat events, which aren't appropriate for password fields except the speakerphone key when trackball is supported or media keys.

Overrides:
keyRepeat in class Field
Parameters:
keycode - Key being repeated (ignored).
time - Number of milliseconds since the device was turned on.
Returns:
True (this method always consumes key repeat events) unless key is speakerphone key and trackball is supported, or a media key.

selectionCopy

public final void selectionCopy(Clipboard cb)
Does nothing.

This type of field does not support copy operations.

Overrides:
selectionCopy in class TextField
Parameters:
cb - Clipboard object.

onUnfocus

protected void onUnfocus()
Description copied from class: BasicEditField
Invoked when a field loses the focus.

The method will not be invoked if this field does not already have the focus.

By default, this method clears the muddy bit and removes selection. If your custom field requires special handling upon losing the focus, you must override this method. Don't forget to call super.onUnFocus() though or the muddy bit won't get cleared.

Overrides:
onUnfocus in class BasicEditField
Since:
BlackBerry API 4.2.1

backspace

protected boolean backspace()
Description copied from class: TextField
Deletes character to the left of the cursor, or deletes selection.

If some characters are currently selected, this method deletes the selection as if it were a single character.

If no characters are selected, this method deletes the character immediately to the left of the cursor. If the cursor is currently on the first character in the field, this method does nothing.

Overrides:
backspace in class BasicEditField
Returns:
True if this method successfully removed a character or selection; otherwise, false.
Since:
BlackBerry API 4.2.1

backspace

public int backspace(int count)
Description copied from class: TextField
Deletes specified number of characters to the left of the cursor.

This method ignores the current selection and deletes a number of characters to the left of the current cursor position. If this method runs into the beginning of this field's editable value, it deletes as many characters as possible.

Overrides:
backspace in class BasicEditField
Parameters:
count - Number of characters to delete.
Returns:
Number of characters actually deleted.
Since:
BlackBerry API 4.2.1

backspace

protected int backspace(int count,
                        int context)
Description copied from class: TextField
Deletes specified number of characters to the left of the cursor, with indication of source of this action.

This method ignores the current selection and deletes a number of characters to the left of the current cursor position. If this method runs into the beginning of this field's editable value, it deletes as many characters as possible.

You can specify whether this method was invoked programmatically, or as an event prompted by the user.

Overrides:
backspace in class BasicEditField
Parameters:
count - Number of characters to delete.
context - Information specifying the origin of the change.
Returns:
Number of characters actually deleted.
Since:
BlackBerry API 4.2.1

charAt

public char charAt(int offset)
Description copied from class: TextField
Retrieves the character at the specified offset.

Index zero is the first character position after this field's label.

Overrides:
charAt in class BasicEditField
Parameters:
offset - Index of the character to retrieve.
Returns:
Character at your specified offset.
Since:
BlackBerry API 4.2.1

clear

public void clear(int context)
Description copied from class: TextField
Clears this field's contents.

Override this method if you want the default text to be non empty when the field is cleared. For example, a URLEditField might call setText("http://", context).

Overrides:
clear in class BasicEditField
Parameters:
context - Context ID for this action.
Since:
BlackBerry API 4.2.1

wipe

public void wipe()
Description copied from class: TextField
Overwrites this field's unused contents.

Overrides:
wipe in class BasicEditField
Since:
BlackBerry API 4.2.1

selectionDelete

public void selectionDelete()
Description copied from class: TextField
Deletes character to the right of the cursor, or deletes selection.

If some characters are currently selected, this method deletes the selection as if they were a single character.

If no characters are selected, this method deletes the character immediately to the right of the cursor. If the cursor is currently on the last character in the field, this method does nothing.

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

displayFieldFullMessage

protected void displayFieldFullMessage()
Description copied from class: TextField
Displays a 'field full' message.

Overrides:
displayFieldFullMessage in class BasicEditField
Since:
BlackBerry API 4.2.1

getLabel

public String getLabel()
Description copied from class: TextField
Retrieves this field's label.

Overrides:
getLabel in class BasicEditField
Returns:
This field's label, or null if this field has no label.
Since:
BlackBerry API 4.2.1

getLabelLength

public int getLabelLength()
Description copied from class: TextField
Retrieves the length of this field's label

The length returned includes any additional character appended for layout purposes. Therefore the value may not be the same as #getLabel().length()

Overrides:
getLabelLength in class BasicEditField
Returns:
Length of this field's label string and any additional layout character.
Since:
BlackBerry API 4.2.1

getMaxSize

public int getMaxSize()
Description copied from class: TextField
Retrieves the maximum number of characters allowed for this field's value.

This method does not include this field's label as part of its accounting.

Overrides:
getMaxSize in class BasicEditField
Returns:
Maximum number of characters allowed in this edit field.
Since:
BlackBerry API 4.2.1

getPreferredHeight

public int getPreferredHeight()
Description copied from class: TextField
Retrieves this field's preferred height.

Managers make use of this value during layout. Edit fields determine their preferred height based on the height of the font they're using to display their text contents.

Overrides:
getPreferredHeight in class BasicEditField
Returns:
Preferred height for this field (height of current font).
Since:
BlackBerry API 4.2.1

getPreferredWidth

public int getPreferredWidth()
Description copied from class: TextField
Retrieves this field's preferred width.

Managers make use of this value during layout. All editable fields to be as wide as possible. Non editable fields to be layed out with as little space as possible.

Overrides:
getPreferredWidth in class BasicEditField
Returns:
Preferred width for this field.
Since:
BlackBerry API 4.2.1

getText

public String getText()
Description copied from class: TextField
Retrieves this field's text, not including the label.

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

getText

public String getText(int offset,
                      int length)
Description copied from class: TextField
Retrieves a portion of this field's text.

Provide a character offset and length to retrieve a substring of this field's contents.

Note: This method includes the label in the field's contents, so if you pass in an offset of zero, the first character returned is the first character of the label.

Note: Different system themes may modify the contents of the label.

Overrides:
getText in class BasicEditField
Parameters:
offset - First character to return.
length - Number of characters to return; must be at least 1.
Returns:
Substring of this field's contents.
Since:
BlackBerry API 4.2.1

getText

public void getText(int srcBegin,
                    int srcEnd,
                    char[] dst,
                    int dstBegin)
Description copied from class: TextField
Retrieves this field's text.

Note: This method adjusts for the label in the field's contents, so the srcBegin and srcEnd parameters describe the field's actual contents.

Overrides:
getText in class BasicEditField
Parameters:
srcBegin - First character in source to retrieve.
srcEnd - Last character in source to retrieve; must be greater than srcBegin.
dst - Character buffer to contain retrieved text.
dstBegin - Offset into buffer to receive the first retrieved character.
Since:
BlackBerry API 4.2.1

getTextAbstractString

public AbstractString getTextAbstractString()
Description copied from class: TextField
Retrieves read-only handle to the underlying buffer.

Note: The underlying buffer can be modified by this field if methods such as TextField.insert(java.lang.String) or TextField.selectionDelete() are invoked.

Overrides:
getTextAbstractString in class BasicEditField
Returns:
Underlying buffer for this field.
Since:
BlackBerry API 4.2.1

getTextLength

public int getTextLength()
Description copied from class: TextField
Retrieves length of this field's text, not including the label.

Overrides:
getTextLength in class BasicEditField
Returns:
Number of characters in this field's text value.
Since:
BlackBerry API 4.2.1

insert

public int insert(String text)
Description copied from class: TextField
Inserts string programmatically into this field.

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

If the maximum size of the field is exceeded while inserting the string, as many characters as possible are inserted.

Note: use this method for programmatic changes to this field; be default, this method simply invokes insert(yourString, FieldChangeListener.PROGRAMMATIC).

Overrides:
insert in class BasicEditField
Parameters:
text - String to insert.
Returns:
Number of characters successfully inserted.
Since:
BlackBerry API 4.2.1

insert

protected int insert(String text,
                     int context)
Description copied from class: TextField
Inserts string into this field.

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

If the maximum size of the field is exceeded while inserting the string, as many characters as possible are inserted.

Overrides:
insert in class BasicEditField
Parameters:
text - String to insert.
context - Information specifying the origin of the change. false indicates user-initiated insertion.
Returns:
Number of characters successfully inserted.
Since:
BlackBerry API 4.2.1

isSymbolScreenAllowed

protected boolean isSymbolScreenAllowed()
Description copied from class: TextField
Determines if this field supports use of the symbol screen.

Use this method to determine if this field supports the symbol screen (all edit fields do by default). The user can press ALT+SPACE to show the symbol screen.

Subclasses may override this method to return different values depending on if they want the symbol screen to be allowed.

The implementation in this class unconditionally returns true.

Overrides:
isSymbolScreenAllowed in class BasicEditField
Returns:
true if this field supports the symbol screen; false if it does not.
Since:
BlackBerry API 4.2.1

setLabel

public void setLabel(String newLabel)
Description copied from class: TextField
Sets this field's label.

Overrides:
setLabel in class BasicEditField
Parameters:
newLabel - New label for this field.
Since:
BlackBerry API 4.2.1

update

protected void update(int delta)
Description copied from class: TextField
Updates this edit field.

This field invokes this method when text is inserted or deleted so this field can update itself.

Overrides:
update in class BasicEditField
Parameters:
delta - Number of characters by which the field has changed, negative or positive (negative means that characters have been deleted).

setMaxSize

public void setMaxSize(int maxSize)
Description copied from class: TextField
Sets maximum number of characters allowed for this field's value.

If this field currently holds more than your provided number, this method truncates this field's contents to fit.

This method does not include the label in its accounting.

Overrides:
setMaxSize in class BasicEditField
Parameters:
maxSize - New maximum number of characters for this edit field's value.
Since:
BlackBerry API 4.2.1

setCursorPosition

public void setCursorPosition(int offset)
Description copied from class: TextField
Places cursor on specific character within this field, at user request.

This method does not include the label as part of its accounting (that is, an offset of zero represents the first character in this field's text value).

This method assumes the repositioning request was user-initiated.

Overrides:
setCursorPosition in class BasicEditField
Parameters:
offset - Character position to receive the cursor, counting from the first character in this field's value.
Since:
BlackBerry API 4.2.1

setCursorPosition

protected void setCursorPosition(int offset,
                                 int context)
Description copied from class: TextField
Places cursor on specific character within this field.

This method does not include the label as part of its accounting (that is, an offset of zero represents the first character in this field's text value).

Overrides:
setCursorPosition in class BasicEditField
Parameters:
offset - Character position to receive the cursor, counting from the first character in this field's value.
context - Information specifying the origin of the change.
Since:
BlackBerry API 4.2.1

getCursorPosition

public int getCursorPosition()
Description copied from class: TextField
Retrieves character offset for current cursor position in this field.

This method does not include the label as part of its accounting (that is, a returned offset of zero means that the cursor is currently sitting on the first character in this field's value).

Overrides:
getCursorPosition in class BasicEditField
Returns:
Character position of current cursor position within this field's value.
Since:
BlackBerry API 4.2.1

paste

public boolean paste(Clipboard cb)
Description copied from class: TextField
Pastes text scrap into this field.

If this field is EDITABLE, this method pastes the scrap currently on the 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 the selection with the scrap from the clipboard.

Overrides:
paste in class BasicEditField
Parameters:
cb - Clipboard object holding the text scrap.
Returns:
True if this field is editable and paste operation was successful; otherwise, false.
Since:
BlackBerry API 4.2.1

setText

public void setText(String text)
             throws IllegalArgumentException
Description copied from class: TextField
Sets the text value for this field. The current text in the field is REPLACED by text.

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

setText

protected void setText(String text,
                       int context)
                throws IllegalArgumentException
Description copied from class: TextField
Sets the text value for this field, with indication of the source of this action.

Overrides:
setText in class BasicEditField
Parameters:
text - New string value for this field; if null, this method clears the field.
context - Information specifying the origin of the change.
Throws:
IllegalArgumentException - If the text cannot be entered into an edit field.
Since:
BlackBerry API 4.2.1





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal