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

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

public class RadioButtonGroup
extends Object

Groups a set of related radio button fields.

Behaviour
The index of a RadioButtonField in the group does not necessarily correspond to the order of the buttons on screen. Indices are assigned in the order that buttons are added to the group. Each Radio button field can belong to only one group at a time.


Constructor Summary
RadioButtonGroup()
          Constructs a new RadioButtonGroup instance.
 
Method Summary
 int add(RadioButtonField button)
          Adds a radio button field to this group.
 FieldChangeListener getChangeListener()
          Retrieves this radio button group's current change listener.
 boolean getNotifyReselected()
          Determines state of reselection notification.
 int getSelectedIndex()
          Retrieves the index of the currently selected button.
 int getSize()
          Retrieves the number of buttons in this group.
 void remove(RadioButtonField button)
          Removes radio button field from this group.
 void setChangeListener(FieldChangeListener listener)
          Registers a listener for radio button group selection changes.
 void setNotifyReselected(boolean notifyReselected)
          Sets state of reselection notification.
 void setSelectedIndex(int selected)
          Selects radio button field by index.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RadioButtonGroup

public RadioButtonGroup()
Constructs a new RadioButtonGroup instance.

Method Detail

add

public int add(RadioButtonField button)
Adds a radio button field to this group.

Parameters:
button - Radio button field to add.
Returns:
Index of added button.
Throws:
IllegalStateException - If button is already a member of a group.

getChangeListener

public FieldChangeListener getChangeListener()
Retrieves this radio button group's current change listener.

Returns:
Current change listener, or null if no listener set.

getNotifyReselected

public final boolean getNotifyReselected()
Determines state of reselection notification.

If reselection notification is on, then the group notifies the change listener when a button is reselected.

By default, reselection notification is turned off.

Returns:
If true, then reselection notification is turned on; otherwise, false.

getSelectedIndex

public int getSelectedIndex()
Retrieves the index of the currently selected button.

Returns:
Index of currently selected button, or -1 if no button currently selected.

getSize

public final int getSize()
Retrieves the number of buttons in this group.

Returns:
Number of radion buttons in this group.

remove

public void remove(RadioButtonField button)
Removes radio button field from this group.

Since a radio button can belong to only one group at a time, you should release a group's buttons if the group is taken off the screen.

Parameters:
button - Radio button field to remove from this group.
Throws:
IllegalArgumentException - If button was not in the group.
IllegalStateException - If button belongs to a Manager (remove the button from the manager first).

setChangeListener

public void setChangeListener(FieldChangeListener listener)
Registers a listener for radio button group selection changes.

Only one listener can be set per group. To change the listener you must first invoke this method passing in null, to unset the current listener, and then invoke it again with the new listener.

Parameters:
listener - Object to listen for radio group changes, or null to remove the listener.
Throws:
IllegalStateException - When a listener has been set, and listener parameter is not null (this occurs even if you attempt to register the same listener twice).

setNotifyReselected

public final void setNotifyReselected(boolean notifyReselected)
Sets state of reselection notification.

If reselection notification is on, then the group notifies the change listener when a button is reselected.

By default, reselection notification is turned off.

Parameters:
notifyReselected - If true, turn reselection notification on; otherwise, turn it off.

setSelectedIndex

public void setSelectedIndex(int selected)
Selects radio button field by index.

Parameters:
selected - Index within this group of the button you want selected; or -1 to remove the selection from all buttons in this group.
Throws:
IllegalArgumentException - If invalid index.



Copyright 1999-2009 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.