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

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--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.

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

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.

Method Summary

protected void	drawFocus(Graphics graphics, boolean on) Draws the focus indicator for this field.
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.
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 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	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.

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

drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getChangeListener, getContextMenu, getCookie, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getWidth, invalidate, invalidate, isDirty, isEditable, isFocusable, isMuddy, isPasteable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isVisible, keyControl, keyDown, keyRepeat, keyStatus, keyUp, moveFocus, 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

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.

RadioButtonField

public RadioButtonField(String label)

Constructs a new RadioButtonField instance with label.

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

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.

Parameters:

label - Label for this field.

group - RadioButtonGroup this button belongs to.

selected - if true, the radio button begins as selected.

Throws:

NullPointerException - If group parameter is null.

Method Detail

makeContextMenu

protected void makeContextMenu(ContextMenu contextMenu)

Builds this field's context menu.

Overrides:

makeContextMenu in class Field

Since:

JDE 3.6

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)

Draws the focus indicator for this field.

Overrides:

drawFocus in class Field

Since:

JDE 3.6

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.

Since:

JDE 3.6

getLabel

public String getLabel()

Retrieves this field's label.

Returns:

Current field string label.

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

Returns:

True if the event was consumed (ENTER or SPACE key pressed); otherwise false.

Since:

JDE 3.6

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

height - Vertical space available.

Since:

JDE 3.6

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:

g - Graphics context for repainting this field.

Since:

JDE 3.6

setLabel

public void setLabel(String label)

Sets the label for this field.

Parameters:

label - New label for this field.

Since:

JDE 3.6

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.

Since:

JDE 3.6