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

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.component.ChoiceField
          extended by net.rim.device.api.ui.component.ObjectChoiceField

public class ObjectChoiceField
extends ChoiceField

Choice field that supports a list of object choices.

This class assumes that the contained object values can all provide string representations of themselves to display in the list of choices (by invocation of ChoiceField.toString()). We assume that this method of generating displayable choices is inexpensive (that is, not new object creations).

Behaviour
A choice field that takes an array of Objects (for example, Strings).


Field Summary
 
Fields inherited from class net.rim.device.api.ui.component.ChoiceField
CONTEXT_CHANGE_OPTION
 
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
ObjectChoiceField()
          Constructs a new, empty ObjectChoiceField instance.
ObjectChoiceField(String label, Object[] choices)
          Constructs a new ObjectChoiceField instance.
ObjectChoiceField(String label, Object[] choices, int initialIndex)
          Constructs a new ObjectChoiceField instance and sets initially selected index.
ObjectChoiceField(String label, Object[] choices, int initialIndex, long style)
          Constructs a new ObjectChoiceField instance of provided style and sets initially selected index.
ObjectChoiceField(String label, Object[] choices, Object initialObject)
          Constructs a new object choice field and sets initially selected object.
 
Method Summary
 Object getChoice(int index)
          Retrieves object by index.
 void setChoices(Object[] choices)
          Provides a new list of choices for this field.
 
Methods inherited from class net.rim.device.api.ui.component.ChoiceField
getAccessibleContext, getFocusRect, getHeightOfChoices, getLabel, getPreferredHeight, getPreferredWidth, getSelectedIndex, getSize, getWidthOfChoice, invokeAction, keyChar, keyStatus, layout, makeContextMenu, moveFocus, onUnfocus, paint, setLabel, setSelectedIndex, setSelectedIndex, setSelectedIndex, setSize, toString, trackwheelClick, trackwheelUnclick
 
Methods inherited from class net.rim.device.api.ui.Field
drawFocus, drawHighlightRegion, fieldChangeNotify, 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, isPasteable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyControl, 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, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setNonSpellCheckable, setPosition, setVisualState, touchEvent, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 



Constructor Detail

ObjectChoiceField

public ObjectChoiceField()
Constructs a new, empty ObjectChoiceField instance.


ObjectChoiceField

public ObjectChoiceField(String label,
                         Object[] choices)
Constructs a new ObjectChoiceField instance.

Parameters:
label - Label for the field.
choices - Array of objects for the field's list of choices.

ObjectChoiceField

public ObjectChoiceField(String label,
                         Object[] choices,
                         int initialIndex)
Constructs a new ObjectChoiceField instance and sets initially selected index.

This method builds a new object choice field, and sets the initially selected value based on your index parameter. If the array of choices you provide is null, then this method ignores your index parameter, and sets the initially selected index to -1.

Parameters:
label - Label for this field.
choices - Choices for this field; if this parameter is null, an empty object choice field is created.
initialIndex - Index of the initially selected value.

ObjectChoiceField

public ObjectChoiceField(String label,
                         Object[] choices,
                         int initialIndex,
                         long style)
Constructs a new ObjectChoiceField instance of provided style and sets initially selected index.

This method builds a new object choice field of a specified style, and sets the initially selected value based on your index parameter. If the array of choices you provide is null, then this method ignores your index parameter, and sets the initially selected index to -1.

Parameters:
label - Label for this field.
choices - Choices for this field; if this parameter is null, an empty object choice field is created.
initialIndex - Index of the initially selected value.
style - Style value for the newly created field.

ObjectChoiceField

public ObjectChoiceField(String label,
                         Object[] choices,
                         Object initialObject)
Constructs a new object choice field and sets initially selected object.

This method builds a new object choice field, and sets the initially selected value to your provided initial object parameter.

Parameters:
label - Label for this field.
choices - Choices for this field.
initialObject - Object to make the initial selected choice. To find a match for your initial object, this method invokes ChoiceField.setSelectedIndex(Object).


Method Detail

getChoice

public Object getChoice(int index)
                 throws IllegalArgumentException
Retrieves object by index.

Specified by:
getChoice in class ChoiceField
Parameters:
index - Index position in list of object you wish to retrieve.
Returns:
Object at the index you specify.
Throws:
IllegalArgumentException - If index is out of bounds.

setChoices

public void setChoices(Object[] choices)
Provides a new list of choices for this field.

Given a new array of choices, this method replaces this field's existing list with the one you provide. The selected choice is also reset to the first value in the new list (index zero).

Parameters:
choices - New list of choices for this field.





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.