|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.ui.Field
net.rim.device.api.ui.component.ChoiceField
public abstract class ChoiceField
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. |
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 java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final int CONTEXT_CHANGE_OPTION
Constructor Detail |
---|
protected ChoiceField()
protected ChoiceField(long style)
style
- Field style for this field: can be a combination of any
generic field style, Field.FOCUSABLE
and
Field.NON_FOCUSABLE
.protected ChoiceField(String label, int numChoices, int index)
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.protected ChoiceField(String label, int numChoices, int index, long style)
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 |
---|
public abstract Object getChoice(int index) throws IllegalArgumentException
Subclasses must implement this method to provide this functionality.
index
- Index of choice for which to retrieve value.
IllegalArgumentException
- If index is out of bounds.public String toString()
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())
toString
in class Object
public void getFocusRect(XYRect rect)
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).
getFocusRect
in class Field
rect
- To contain the local coordinates of the focus rect.public String getLabel()
public int getPreferredWidth()
Field.getPreferredWidth()
for more information.
This field's manager invokes this method to assist in its layout.
getPreferredWidth
in class Field
public int getPreferredHeight()
Field.getPreferredHeight()
for more information.
getPreferredHeight
in class Field
public int getSelectedIndex()
For an empty ChoiceField, returns -1.
public int getSize()
protected int getWidthOfChoice(int index)
ChoiceField.getWidthOfChoice(int, Font)
with the ChoiceField font.
index
- Index of the choice whose width should be returned.
protected int getHeightOfChoices()
#getHeightOfChoice(Font)
with the
ChoiceField font.
protected boolean invokeAction(int action)
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.
invokeAction
in class Field
action
- the action to be performed on this field.
true
if the action was consumed or false
if the action was not consumed.protected boolean keyChar(char key, int status, int time)
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.
keyChar
in class Field
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.
protected boolean keyControl(char ch, int status, int time)
keyControl
in class Field
ch
- Character generated.status
- Modifier key status. See KeypadListener
.time
- Number of milliseconds since the device was turned on.
protected boolean keyStatus(int keycode, int time)
keyStatus
in class Field
keycode
- Code of status key.time
- Number of milliseconds since the device was turned on.
protected boolean touchEvent(TouchEvent message)
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.
touchEvent
in class Field
message
- TouchEvent
object containing various input parameters
including the event type and touch coordinates.
IllegalArgumentException
- If message
is null.protected boolean trackwheelClick(int status, int time)
The system invokes this method when passing on a trackwheel click event. This method is transparent, and the event is not consumed.
trackwheelClick
in class Field
status
- State of the modifier keys.time
- Number of milliseconds since the device was turned on.
protected boolean trackwheelUnclick(int status, int time)
The system invokes this method when passing on a trackwheel release event.
trackwheelUnclick
in class Field
status
- Bitfield of values defined by Keypad
.time
- Number of milliseconds since the device was turned on.
protected void layout(int width, int height)
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.
layout
in class Field
width
- Amount of available horizontal space.height
- Amount of available vertical space.protected void makeContextMenu(ContextMenu contextMenu)
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.
makeContextMenu
in class Field
contextMenu
- Context menu to build.ContextMenu
protected int moveFocus(int amount, int status, int time)
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.
Prior to invoking this method, the framework invokes
Field.focusRemove()
. After invoking this method, the framework invokes
Field.focusAdd(boolean)
.
This method also clears this field's muddy state.
moveFocus
in class Field
amount
- Number of positions to move, positive means down, negative
means up.status
- Modifier key status applied when the trackwheel
roll occurred (combination of applicable modifier keycode values from
KeypadListener
).time
- Number of milliseconds since the device was turned on.
protected void paint(Graphics graphics)
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)
.
paint
in class Field
graphics
- Graphics context for repainting this field.protected void drawFocus(Graphics graphics, boolean on)
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.
drawFocus
in class Field
graphics
- Graphics context for drawing the focus.on
- True if the focus should be set; otherwise, false.public void setLabel(String label)
label
- Label string for this field.protected void setSize(int size)
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).
size
- Number of choices for this field.ChoiceField.setSelectedIndex(int)
protected void setNumberOfChoices(int numChoices)
numChoices
- the number of choicespublic void setSelectedIndex(int index)
index
- Index of the selected value.
IllegalArgumentException
- If index parameter is out of bounds.protected void setSelectedIndex(int index, int context)
index
- Index of the selected value.context
- Information specifying the origin of the change.
IllegalArgumentException
- If index parameter is out of bounds.FieldChangeListener
public void setSelectedIndex(Object 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.
object
- Object to seek for.
NullPointerException
- If object parameter is null.public void setEditable(boolean editable)
This method lets you change the style of this field by either adding,
or removing, the Field.EDITABLE
style.
setEditable
in class Field
editable
- If True, make this field editable; otherwise, make this
field non-editable.protected void onUnfocus()
The method will not be invoked if this field does not already have the focus.
onUnfocus
in class Field
public AccessibleContext getAccessibleContext()
getAccessibleContext
in class Field
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.