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

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--net.rim.device.api.ui.component.ChoiceField

All Implemented Interfaces:

IComponent, InputMethodListener

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

EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, READONLY, USE_ALL_HEIGHT, USE_ALL_WIDTH

Constructor Summary

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

Method Summary

abstract Object	getChoice(int index) Retrieves value for specified index.
void	getFocusRect(XYRect rect) Retrieves this field's current focus region.
String	getLabel() Retrieves this field's label.
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 boolean	keyChar(char key, int status, int time) Traps key events to seek to appropriate choice.
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	paint(Graphics graphics) Redraws this field.
void	setLabel(String label) Sets label string for this field.
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.

Methods inherited from class net.rim.device.api.ui.Field

drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getChangeListener, getContextMenu, getCookie, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getPreferredHeight, getScreen, getStyle, getTop, getWidth, invalidate, invalidate, isDirty, isEditable, isFocusable, isMuddy, isPasteable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isVisible, keyControl, keyDown, keyRepeat, keyUp, moveFocus, onFocus, onUnfocus, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setChangeListener, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setPosition, trackwheelClick, trackwheelUnclick, updateLayout

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, 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.

Constructor Detail

ChoiceField

protected ChoiceField()

Constructs a new choice field.

ChoiceField

protected ChoiceField(long style)

Constructs a new choice field with provided style.

Parameters:

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

ChoiceField

protected ChoiceField(String label,
                      int numChoices,
                      int index)

Constructs a new choice field 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 choice field 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.

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.

Since:

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

Since:

JDE 3.7.0

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.

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.

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.

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 - Ticks since device reset (this parameter is ignored).

Returns:

True if this event was consumed; otherwise, false.

Since:

JDE 3.7.0

keyStatus

protected boolean keyStatus(int keycode,
                            int time)

Handles key status events.

Overrides:

keyStatus in class Field

Since:

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

Overrides:

layout in class Field

Parameters:

width - Amount of available horizontal space.

height - Amount of available vertical space.

Since:

JDE 3.7.0

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 the UI is not operating in MODE_ADVANCD mode (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

Since:

JDE 3.7.0

moveFocus

protected int moveFocus(int amount,
                        int status,
                        int time)

Handles moving the focus within this field.

This field's manager invokes this method only when the field already has the focus.

If this field is EDITABLE, then this method handles the case where the user ALT-rolls the trackwheel (trapping these events to move to the next or subsequent choices in the list, depending on the roll amount passed in). Otherwise, this field simply passes the amount of the event on.

Overrides:

moveFocus in class Field

Parameters:

amount - Number of positions to move, positive means downwards, negative means upwards.

status - Modifier key state: if not STATUS_ALT, then this method does nothing and passes on the event.

time - Ticks since device reset (this parameter ignored).

Returns:

Remaining scroll amount not used up. If the trackwheel is being ALT-rolled, then this method always returns 0 (that is, all the trackwheel movement is consumed by the method); otherwise, the entire amount is returned (the method used none of the trackwheel movement).

Since:

JDE 3.7.0

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.

Overrides:

paint in class Field

Parameters:

graphics - Graphics context for repainting this field.

Since:

JDE 3.7.0

setLabel

public void setLabel(String label)

Sets label string for this field.

Parameters:

label - Label string for this field.

Since:

JDE 3.7.0

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.

Since:

JDE 3.7.0

See Also:

setSelectedIndex(int)

setSelectedIndex

public void setSelectedIndex(int index)

Sets the currently chosen value.

Parameters:

index - Index of the selected value.

Throws:

IllegalArgumentException - If index is out of bounds.

Since:

JDE 3.7.0

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 is out of bounds.

Since:

JDE 3.7.0

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.

Since:

JDE 3.7.0