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

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

public class RadioButtonField
extends Field

Field to provide a radio-button control.

Behaviour
Displays a circular button to the left of the text label. With the default font, this button is either empty or contain a solid circle depending on the state of the field. When this field has the focus, the button appears inverted.

You group together Radio buttons fields using the RadioButtonGroup class. At most one button within the group can be selected at any one time. The group can be programmatically created or changed so that no button is selected, but a user cannot deselect all fields in the group.

If the control is EDITABLE (radio button fields are created this way by default), pressing ENTER selects this field and deselects the previously selected radio button field in the group.


Field Summary
 
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
RadioButtonField()
          Constructs a new RadioButtonField instance.
RadioButtonField(String label)
          Constructs a new RadioButtonField instance with label.
RadioButtonField(String label, RadioButtonGroup group, boolean selected)
          Constructs a new RadioButtonField instance for a group, with label and initial state.
RadioButtonField(String label, RadioButtonGroup group, boolean selected, long style)
          Constructs a new RadioButtonField instance for a group, with label, initial state and style.
 
Method Summary
protected  void drawFocus(Graphics graphics, boolean on)
          Draws the focus indicator for this field.
 AccessibleContext getAccessibleContext()
          Returns accessible representation of the field for a screen reader.
 void getFocusRect(XYRect rect)
          Retrieves this field's current focus region.
 RadioButtonGroup getGroup()
          Retrieves this field's controlling group.
 String getLabel()
          Retrieves this field's label.
 int getPreferredHeight()
          Retrieves this field's preferred height.
 int getPreferredWidth()
          Retrieves this field's preferred width.
 boolean isSelected()
          Determines if this field's radio button is selected.
protected  boolean keyChar(char key, int status, int time)
          Traps ENTER or SPACE key generation events.
protected  boolean keyDown(int keycode, int time)
           This method handles and consumes a key generation event, if it's the '5/GH' key (the 'Action' hotkey for Charm device) that's generated; otherwise, this method does nothing and does not consume the event.
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  void onFocus(int direction)
          Invoked when a field receives the focus.
protected  void onUnfocus()
          Invoked when a field loses the focus.
protected  void paint(Graphics graphics)
          Redraws this field.
 void setLabel(String label)
          Sets the label for this field.
 void setSelected(boolean selected)
          Sets the state of this field's radio button.
protected  boolean touchEvent(TouchEvent message)
          Traps touch screen input events.
protected  boolean trackwheelClick(int status, int time)
          Indicates a trackwheel click event.
protected  boolean trackwheelUnclick(int status, int time)
          Indicates a trackwheel release event.
 
Methods inherited from class net.rim.device.api.ui.Field
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, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isMuddy, isPasteable, isScrollCopyable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyControl, keyRepeat, keyStatus, keyUp, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEditable, setEnabled, setExtent, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

RadioButtonField

public RadioButtonField()
Constructs a new RadioButtonField instance.

This builds a new, unselected radio button field with no label, and no initial assigned group.

If full available width is not desired, then RadioButtonField.NO_USE_ALL_WIDTH style must be specified using the appropriate constructor.


RadioButtonField

public RadioButtonField(String label)
Constructs a new RadioButtonField instance with label.

Before you can use the newly built radio button field, you must add it to a valid radio button group.

If full available width is not desired, then RadioButtonField.NO_USE_ALL_WIDTH style must be specified using the appropriate constructor.

Parameters:
label - Label for this field.

RadioButtonField

public RadioButtonField(String label,
                        RadioButtonGroup group,
                        boolean selected)
Constructs a new RadioButtonField instance for a group, with label and initial state.

If full available width is not desired, then RadioButtonField.NO_USE_ALL_WIDTH style must be specified using the appropriate constructor.

Parameters:
label - Label for this field.
group - RadioButtonGroup this button belongs to.
selected - if true, the radio button begins as selected.

RadioButtonField

public RadioButtonField(String label,
                        RadioButtonGroup group,
                        boolean selected,
                        long style)
Constructs a new RadioButtonField instance for a group, with label, initial state and style.

If full available width is not desired, then RadioButtonField.NO_USE_ALL_WIDTH style must be specified using the appropriate constructor.

Parameters:
label - Label for this field.
group - RadioButtonGroup this button belongs to.
selected - if true, the radio button begins as selected.
style - The style for this field.
Since:
BlackBerry API 3.7.0


Method Detail

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)
Draws the focus indicator for this field.

Overrides:
drawFocus in class Field
Parameters:
graphics - Graphics context for drawing the focus.
on - True if the focus should be set; otherwise, false.
Since:
BlackBerry API 3.6.0

getFocusRect

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

The framework uses this method to retrieve the current focus region for this field (the extent of the 'radio button' part of the field, not including the label).

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

getLabel

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

Returns:
Current field string label.

getPreferredHeight

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

Managers may make use of this value during layout.

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

getPreferredWidth

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

Managers make use of this value during layout.

Overrides:
getPreferredWidth in class Field
Returns:
Preferred width for this field.
Since:
BlackBerry API 4.0.0

getGroup

public RadioButtonGroup getGroup()
Retrieves this field's controlling group.

Invoke this method to retrieve the radio button group that controls this field.

Returns:
Group this field belongs to; if this field hasn't been assigned to a group yet, this method returns null.

isSelected

public boolean isSelected()
Determines if this field's radio button is selected.

Returns:
True if this field's radio button is selected; otherwise, false.
Throws:
IllegalStateException - If the button is not a member of a group.

keyChar

protected boolean keyChar(char key,
                          int status,
                          int time)
Traps ENTER or SPACE key generation events.

This method handles and consumes a key generation event, if it's the ENTER or SPACE key that's generated; otherwise, this method does nothing and does not consume the event.

If the ENTER or SPACE key was pressed, then this method selects this field as if invoking setSelected(true).

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

keyDown

protected boolean keyDown(int keycode,
                          int time)

This method handles and consumes a key generation event, if it's the '5/GH' key (the 'Action' hotkey for Charm device) that's generated; otherwise, this method does nothing and does not consume the event.

If the '5/GH' key was pressed, then this method selects this field as if invoking setSelected(true).

Overrides:
keyDown in class Field
Parameters:
keycode - Character generated by the event.
time - Number of milliseconds since the device was turned on.
Returns:
True if the event was consumed ('5/GH' key pressed); otherwise Field.keyDown(int, int).
Since:
BlackBerry API 4.0.0

touchEvent

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

This method handles touch screen input events. DOWN events cause this RadioButtonField to enter a focused state, which is in fact handled at the Manager level. UNCLICK events select the radio button. The remaining touch screen input events are consumed and/or 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

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 - Horizontal space available (note that radio button fields always use all available horizontal space).
height - Vertical space available.

makeContextMenu

protected void makeContextMenu(ContextMenu contextMenu)
Builds 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 - Context menu to build.
See Also:
ContextMenu
Since:
BlackBerry API 3.6.0

onFocus

protected void onFocus(int direction)
Description copied from class: Field
Invoked when a field receives the focus.

The method will not be invoked if this field already has focus. Also, it will not be invoked if this field returns false from Field.isFocusable().

Managers should find a child field that accepts focus and cascade this method's call to it.

The direction value indicates how the focus came to enter the field:

Overrides:
onFocus in class Field
Parameters:
direction - Indicates from which direction the focus enters the field.
Since:
BlackBerry API 4.2.1

onUnfocus

protected void onUnfocus()
Description copied from class: Field
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 this method on the parent though, or the muddy bit won't get cleared.

Overrides:
onUnfocus in class Field
Since:
BlackBerry API 4.2.1

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.

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

setLabel

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

Parameters:
label - New label for this field.

setSelected

public void setSelected(boolean selected)
Sets the state of this field's radio button.

Invoke this method to change the selected state of this radio button field. Notice that radio button selection is typically handled by the RadioButtonGroup; using this method is a programmatic change which can result in no buttons in a group being selected.

Parameters:
selected - True if this field should be selected (if another radio button field in the group was selected, it is deselected); false if this field should be deselected (if this radio button field was previously selected, then no field in the group will be selected).
Throws:
IllegalStateException - If the button is not a member of a group.

trackwheelClick

protected boolean trackwheelClick(int status,
                                  int time)
Indicates a trackwheel click event.

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

The ALT-click combination will enter selection mode, or if in selection mode will copy.

Overrides:
trackwheelClick in class Field
Parameters:
status - Bitfield of values defined by Keypad.
time - Number of milliseconds since the device was turned on.
Returns:
True if this method consumed the event; otherwise, false.
Since:
BlackBerry API 4.3.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 6.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-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.