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

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.component.ChoiceField
Direct Known Subclasses:
NumericChoiceField, ObjectChoiceField

public abstract class ChoiceField
extends Field

Base implementation of a choice field.

Behaviour
The field shows a label followed by the text of the currently selected choice. When this field has the focus, the text of the currently selected choice is shown inverted. By default, ChoiceField behaves as if the Field.USE_ALL_WIDTH style was set, with the label on the leading edge of the line and the choice on the trailing edge, separated by any available space. Setting the Field.FIELD_LEFT, Field.FIELD_RIGHT, or Field.FIELD_HCENTER style will cause the label and choice to be joined together with no space in between. If the choice field is created with the Field.EDITABLE style (it is by default), then the user may alter the currently selected choice when the field has the focus. The selection wraps around, so when the end of the list of choices is reached, selection is set to the other end.

Methods of selecting a choice
Pressing the space bar moves the selection to the next choice in the list.

You can use the trackwheel to change the selection by holding the ALT key down while rolling. If Ui.getIncreaseDirection() is -1, then ALT-rolling the trackwheel down should move through selections in an increasing manner. If Ui.getIncreaseDirection() is +1, the ALT-rolling the trackwheel up should move through selections in an increasing manner.

Character presses will jump to the first letter of the next item starting with the character, regardless of case.

Finally, the field adds a menu item added to change its selected value. When the use selects this menu item, a dialog appears allowing the user to employ the trackwheel to select a new value without holding the ALT key. Pressing ENTER or clicking dismisses this dialog and changes the choice. Pressing ESCAPE dismisses the dialog and cancels the change. Other keys will work as defined above.


Field Summary
static int CONTEXT_CHANGE_OPTION
          Context hint for the event being triggered from a change option dialog dismissal.
 
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
protected ChoiceField()
          Constructs a new ChoiceField instance.
protected ChoiceField(String label, int numChoices, int index)
          Constructs a new ChoiceField instance with provided label and number of choices, setting initially selected value.
protected ChoiceField(String label, int numChoices, int index, long style)
          Constructs a new ChoiceField instance and sets initially selected value.
protected ChoiceField(long style)
          Constructs a new choice field instance with provided style.
 
Method Summary
protected  void drawFocus(Graphics graphics, boolean on)
          Calls Field's drawFocus method to draw the standard focus caret, if needed.
 AccessibleContext getAccessibleContext()
          Returns accessible representation of the field for a screen reader.
abstract  Object getChoice(int index)
          Retrieves value for specified index.
 void getFocusRect(XYRect rect)
          Retrieves this field's current focus region.
protected  int getHeightOfChoices()
          Retrieves the maximum height in pixels required by any one of the choices in the field using the ChoiceField font.
 String getLabel()
          Retrieves this field's label.
 int getPreferredHeight()
          Retrieves this field's preferred height in pixels.
 int getPreferredWidth()
          Retrieves this field's preferred width.
 int getSelectedIndex()
          Retrieves index of the currently selected choice.
 int getSize()
          Retrieves number of choices in this field.
protected  int getWidthOfChoice(int index)
          Retrieves the width of a particular choice in pixels using the ChoiceField font.
protected  boolean invokeAction(int action)
          Invokes an action on this field.
protected  boolean keyChar(char key, int status, int time)
          Traps key events to seek to appropriate choice.
protected  boolean keyControl(char ch, int status, int time)
          Don't want left and right jumping, which is caused by automatically turning these into trackwheel events.
protected  boolean keyStatus(int keycode, int time)
          Handles key status events.
protected  void layout(int width, int height)
          Lays out this field's contents.
protected  void makeContextMenu(ContextMenu contextMenu)
          Builds this field's context menu.
protected  int moveFocus(int amount, int status, int time)
          Handles moving the focus within this field.
protected  void onUnfocus()
          Invoked when a field loses the focus.
protected  void paint(Graphics graphics)
          Redraws this field.
 void setEditable(boolean editable)
          Set the editable state of this field.
 void setLabel(String label)
          Sets the label string for this field.
protected  void setNumberOfChoices(int numChoices)
          Set the number of choices on the choice box
 void setSelectedIndex(int index)
          Sets the currently chosen value.
protected  void setSelectedIndex(int index, int context)
          Sets the currently chosen value.
 void setSelectedIndex(Object object)
          Selects first value that matches an object.
protected  void setSize(int size)
          Sets the number of choices in this field.
 String toString()
          Returns a string representation of the object.
protected  boolean touchEvent(TouchEvent message)
          Traps touch input events.
protected  boolean trackwheelClick(int status, int time)
          Handles trackwheel click events.
protected  boolean trackwheelUnclick(int status, int time)
          Indicates a trackwheel release event.
 
Methods inherited from class net.rim.device.api.ui.Field
cursorClick, cursorUnclick, drawHighlightRegion, fieldChangeNotify, 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, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isLeftToRight, isMuddy, isPasteable, isScrollCopyable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyDown, keyRepeat, keyUp, moveFocus, navigationClick, navigationMovement, navigationUnclick, onDisplay, onExposed, onFocus, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEnabled, setExtent, setFocus, setFocusListener, setFont, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 



Field Detail

CONTEXT_CHANGE_OPTION

public static final int CONTEXT_CHANGE_OPTION
Context hint for the event being triggered from a change option dialog dismissal. This value is sent to the FieldChangeListener on a fieldChanged event if the user changed an option using touch screen, trackpad or by pressing a key.

See Also:
Constant Field Values


Constructor Detail

ChoiceField

protected ChoiceField()
Constructs a new ChoiceField instance.


ChoiceField

protected ChoiceField(long style)
Constructs a new choice field instance with provided style.

Parameters:
style - Field style for this field: can be a combination of any generic field style, Field.FOCUSABLE and Field.NON_FOCUSABLE.

ChoiceField

protected ChoiceField(String label,
                      int numChoices,
                      int index)
Constructs a new ChoiceField instance with provided label and number of choices, setting initially selected value.

Parameters:
label - Label for this field.
numChoices - Number of choices; if zero, then the index parameter is set to zero regardless of its value.
index - Index of the initially selected value.

ChoiceField

protected ChoiceField(String label,
                      int numChoices,
                      int index,
                      long style)
Constructs a new ChoiceField instance and sets initially selected value.

Parameters:
label - Label for this field.
numChoices - Number of choices; if zero, then the index parameter is set to zero regardless of its value.
index - Index of the initially selected value.
style - Field style for this field: can be a combination of any generic field style, Field.FOCUSABLE and Field.NON_FOCUSABLE.


Method Detail

getChoice

public abstract Object getChoice(int index)
                          throws IllegalArgumentException
Retrieves value for specified index.

Subclasses must implement this method to provide this functionality.

Parameters:
index - Index of choice for which to retrieve value.
Returns:
Choice value at specified index.
Throws:
IllegalArgumentException - If index is out of bounds.

toString

public String toString()
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Overrides:
toString in class Object
Returns:
a string representation of the object.
Since:
BlackBerry API 4.2.0

getFocusRect

public void getFocusRect(XYRect rect)
Retrieves this field's current focus region.

This method sets the focus region to the width of the selectable portion of this field (the part of the field containing the selectable value, not the label).

Overrides:
getFocusRect in class Field
Parameters:
rect - To contain the local coordinates of the focus rect.

getLabel

public String getLabel()
Retrieves this field's label.

Returns:
Label string for this field.

getPreferredWidth

public int getPreferredWidth()
Retrieves this field's preferred width. See Field.getPreferredWidth() for more information.

This field's manager invokes this method to assist in its layout.

Overrides:
getPreferredWidth in class Field
Returns:
Preferred width (in pixels) of this field.

getPreferredHeight

public int getPreferredHeight()
Retrieves this field's preferred height in pixels. See Field.getPreferredHeight() for more information.

Overrides:
getPreferredHeight in class Field
Returns:
Preferred height for this field.
Since:
BlackBerry API 4.0.0

getSelectedIndex

public int getSelectedIndex()
Retrieves index of the currently selected choice.

For an empty ChoiceField, returns -1.

Returns:
Index of current choice.

getSize

public int getSize()
Retrieves number of choices in this field.

Returns:
The number of choice values in this field's list.

getWidthOfChoice

protected int getWidthOfChoice(int index)
Retrieves the width of a particular choice in pixels using the ChoiceField font. Calls ChoiceField.getWidthOfChoice(int, Font) with the ChoiceField font.

Parameters:
index - Index of the choice whose width should be returned.
Returns:
Width of the choice at the specified index in pixels with the ChoiceField font.
Since:
BlackBerry API 4.0.0

getHeightOfChoices

protected int getHeightOfChoices()
Retrieves the maximum height in pixels required by any one of the choices in the field using the ChoiceField font. Calls #getHeightOfChoice(Font) with the ChoiceField font.

Since:
BlackBerry API 4.0.0

invokeAction

protected boolean invokeAction(int action)
Invokes an action on this field. The only action that is recognized by this method is Field.ACTION_INVOKE, which opens this field to have its value changed by the user.

If action is not a recognized action then this method does nothing and returns false, indicating that the action was not consumed.

Note that if this field is not editable (ie. Field.isEditable() returns false) then the action will not be consumed.

Overrides:
invokeAction in class Field
Parameters:
action - the action to be performed on this field.
Returns:
true if the action was consumed or false if the action was not consumed.
Since:
BlackBerry API 4.2.0

keyChar

protected boolean keyChar(char key,
                          int status,
                          int time)
Traps key events to seek to appropriate choice.

This method handles and consumes a key generation event, only if this field is EDITABLE; otherwise, it does nothing and does not consume the event.

If the key generated was a SPACE character, this method moves the selection to the next choice in the list. If the previous selection was the last in the list, the selection wraps around to the first value in the list.

If the key generated was a letter key, this method moves the selection to the first subsequent value that begins with the generated letter. If there are no matches before the end of the list, the search wraps around. If there are no matches anywhere in the list, the selection does not move (but this method still consumes the key event).

If the selection does move, this field is invalidated to force a repaint.

Overrides:
keyChar in class Field
Parameters:
key - Character generated by the event.
status - State of the modifier keys (this parameter is ignored).
time - Number of milliseconds since the device was turned on.
Returns:
True if this event was consumed; otherwise, false.

keyControl

protected boolean keyControl(char ch,
                             int status,
                             int time)
Don't want left and right jumping, which is caused by automatically turning these into trackwheel events.

Overrides:
keyControl in class Field
Parameters:
ch - The character generated.
status - The modifier key status. See KeypadListener.
time - The number of milliseconds since the device was turned on.
Returns:
true if this method consumed the event, false otherwise.
Since:
BlackBerry API 6.0.0

keyStatus

protected boolean keyStatus(int keycode,
                            int time)
Handles key status events.

Overrides:
keyStatus in class Field
Parameters:
keycode - Code of status key.
time - Number of milliseconds since the device was turned on.
Returns:
True if event was consumed; otherwise false.
Since:
BlackBerry API 3.6.0

touchEvent

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

This method handles touch input events. DOWN events cause this ChoiceField to enter a focused state, which is in fact handled at the Manager level. CLICK and UNCLICK events occurring out of bounds are consumed and ignored.

Overrides:
touchEvent in class Field
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

trackwheelClick

protected boolean trackwheelClick(int status,
                                  int time)
Handles trackwheel click events.

The system invokes this method when passing on a trackwheel click event. This method is transparent, and the event is not consumed.

Overrides:
trackwheelClick in class Field
Parameters:
status - State of the modifier keys.
time - Number of milliseconds since the device was turned on.
Returns:
true if the click was consumed, otherwise false.
Since:
BlackBerry API 5.0.0

trackwheelUnclick

protected boolean trackwheelUnclick(int status,
                                    int time)
Indicates a trackwheel release event.

The system invokes this method when passing on a trackwheel release event.

Overrides:
trackwheelUnclick in class Field
Parameters:
status - Bitfield of values defined by Keypad.
time - Number of milliseconds since the device was turned on.
Returns:
true if the unclick was consumed, otherwise false.
Since:
BlackBerry API 5.0.0

layout

protected void layout(int width,
                      int height)
Lays out this field's contents.

This field's manager invokes this method during the layout process to instruct this field to arrange its contents, given an amount of available space.

Specified by:
layout in class Field
Parameters:
width - Amount of available horizontal space.
height - Amount of available vertical space.

makeContextMenu

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

Field.getContextMenu() invokes this method to construct this field's context menu.

If UiInternal.getShouldShowChangeOptionMenuItem() returns true and this field is Field.EDITABLE, this method builds this field's context menu adding a menu item for changing this field's value.

Overrides:
makeContextMenu in class Field
Parameters:
contextMenu - The context menu to build.
See Also:
ContextMenu

moveFocus

protected int moveFocus(int amount,
                        int status,
                        int time)
Description copied from class: Field
Handles moving the focus within this field.

This method is called by the framework only when the field already has focus.

By default, this method returns the amount parameter provided to it. Custom fields must override this method to handle focus movement events. This method also clears this field's muddy state.

Prior to invoking this method, the framework invokes Field.focusRemove(). After invoking this method, the framework invokes Field.focusAdd(boolean).

Overrides:
moveFocus in class Field
Parameters:
amount - The number of positions to move. Positive values mean down, negative values mean up.
status - The modifier key status applied when the trackwheel roll occurred (combination of applicable modifier keycode values from KeypadListener).
time - The number of milliseconds since the device was turned on.
Returns:
The remaining scroll amount not used up, with the same sign.

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 must set the active font ChoiceField.useChoiceBoxFont(boolean).

Specified by:
paint in class Field
Parameters:
graphics - Graphics context for repainting this field.

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)
Calls Field's drawFocus method to draw the standard focus caret, if needed.

getShouldDrawChoiceBox() should be overridden to return false in ChoiceField subclasses used as the popup (like ChangeOptionChoiceField).

If we are going to draw the choice box, do nothing, as its focus is drawn by paint.

Overrides:
drawFocus in class Field
Parameters:
graphics - The graphics context for drawing the focus.
on - If true the focus should be set, if false the focus should not be set.
Since:
BlackBerry API 6.0.0

setLabel

public void setLabel(String label)
Sets the label string for this field.

Parameters:
label - Label string for this field.

setSize

protected void setSize(int size)
Sets the number of choices in this field.

Invoking this method resets the number of choices in this field. It also resets the index of the initially chosen value to 0 (the first item in the list).

Parameters:
size - Number of choices for this field.
See Also:
ChoiceField.setSelectedIndex(int)

setNumberOfChoices

protected void setNumberOfChoices(int numChoices)
Set the number of choices on the choice box

Parameters:
numChoices - the number of choices
Since:
BlackBerry API 6.0.0

setSelectedIndex

public void setSelectedIndex(int index)
Sets the currently chosen value.

Parameters:
index - Index of the selected value.
Throws:
IllegalArgumentException - If index parameter is out of bounds.

setSelectedIndex

protected void setSelectedIndex(int index,
                                int context)
Sets the currently chosen value.

Parameters:
index - Index of the selected value.
context - Information specifying the origin of the change.
Throws:
IllegalArgumentException - If index parameter is out of bounds.
See Also:
FieldChangeListener

setSelectedIndex

public void setSelectedIndex(Object object)
Selects first value that matches an object.

Provide this method with an object, and it sets the selection on the first value in this field's list (starting from the first item) that matches this object (using Object.equals(java.lang.Object)). If a match is not found, this method does not alter the current the selection.

Parameters:
object - Object to seek for.
Throws:
NullPointerException - If object parameter is null.

setEditable

public void setEditable(boolean editable)
Set the editable state of this field.

This method lets you change the style of this field by either adding, or removing, the Field.EDITABLE style.

Overrides:
setEditable in class Field
Parameters:
editable - If True, make this field editable; otherwise, make this field non-editable.
Since:
BlackBerry API 6.0.0

onUnfocus

protected void onUnfocus()
Invoked when a field loses the focus.

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

Overrides:
onUnfocus in class Field
Since:
BlackBerry API 5.0.0

getAccessibleContext

public AccessibleContext getAccessibleContext()
Returns accessible representation of the field for a screen reader.

Overrides:
getAccessibleContext in class Field
Returns:
AccessibleContext instance
Since:
BlackBerry API 4.6.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