org.apache.pivot.wtk
Class RadioButtonGroup

java.lang.Object
  extended by org.apache.pivot.wtk.ButtonGroup
      extended by org.apache.pivot.wtk.RadioButtonGroup
All Implemented Interfaces:
Iterable<Button>, Group<Button>

public class RadioButtonGroup
extends ButtonGroup

Extension of ButtonGroup providing keyboard navigation within the group and modified focus navigation that treats the group as a single focusable entity.

UP & LEFT Select the previous button
DOWN & RIGHT Select the next button
HOME Select the first button
END Select the last button

(Note that only focusable buttons are considered when searching for a Button to select)

When a button within the group is focused and key is typed, an attempt is made to find the next button (default) or previous button (when the SHIFT modifier is pressed) whose renderer text starts with the typed character. This search will always behave as if the circular property were set.

By default, TAB and SHIFT+TAB key presses will transfer focus out of the group (forwards or backwards respectively). This is managed by the intraGroupFocusTransferEnabled property.

The circular property can be enabled to allow the selection to transfer seamlessly from one end of the group to the other. (i.e. holding down an arrow key will cycle through all focusable buttons)

Note that due to the conflicting return types of the add(T) and remove(T) methods in the Group and Sequence interfaces, this class cannot actually implement Sequence<Button>, although most of the same methods are implemented.


Constructor Summary
RadioButtonGroup()
           
 
Method Summary
 boolean add(Button button)
          Add a button to the group.
 Button get(int index)
          Return the button at the specified index.
 int getLength()
          Return the number of buttons in the group.
 int indexOf(Button button)
          Return the index (order) of the button within the group.
 void insert(Button button, int index)
          Insert a button at the specified index.
 boolean isCircular()
          When enabled, a search for the previous or next focusable button will not stop when the group's lower or upper bounds (respectively) are reached.
 boolean isIntraGroupFocusTransferEnabled()
          When true, TAB and SHIFT+TAB transfer focus out of the RadioButtonGroup.
 Iterator<Button> iterator()
          Return an iterator for the ordered list of buttons
 boolean remove(Button button)
          Remove the button from the group.
 Sequence<Button> remove(int index, int count)
          Remove count buttons from the group starting at index.
 void selectFirstButton()
          Select the first focusable button in the group.
 void selectLastButton()
          Select the last focusable button in the group.
 void selectNextButton(Button button)
          Working forwards from the specified button, select the first focusable button.
 void selectPreviousButton(Button button)
          Working backwards from the specified button, select the first focusable button.
 void setCircular(boolean circular)
          When enabled, a search for the previous or next focusable button will not stop when the group's lower or upper bounds (respectively) are reached.
 void setIntraGroupFocusTransferEnabled(boolean intraGroupFocusTransferEnabled)
          Controls whether TAB and SHIFT+TAB will transfer focus out of the RadioButtonGroup, or simply maintain their default behaviour.
 void setSelection(Button button)
          Select and focus the specified button.
 void setSelection(int index)
          Select and focus the button at the specified index, unless the index is NOT_FOUND_INDEX.
 
Methods inherited from class org.apache.pivot.wtk.ButtonGroup
contains, getButtonGroupListeners, getSelection
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RadioButtonGroup

public RadioButtonGroup()
Method Detail

isCircular

public boolean isCircular()
When enabled, a search for the previous or next focusable button will not stop when the group's lower or upper bounds (respectively) are reached.
Instead, the search will 'wrap' and continue from the opposite bound until each button in the entire group has been tested for inclusion.

Defaults to false


setCircular

public void setCircular(boolean circular)
When enabled, a search for the previous or next focusable button will not stop when the group's lower or upper bounds (respectively) are reached.
Instead, the search will 'wrap' and continue from the opposite bound until each button in the entire group has been tested for inclusion.


isIntraGroupFocusTransferEnabled

public boolean isIntraGroupFocusTransferEnabled()
When true, TAB and SHIFT+TAB transfer focus out of the RadioButtonGroup.
Defaults to false


setIntraGroupFocusTransferEnabled

public void setIntraGroupFocusTransferEnabled(boolean intraGroupFocusTransferEnabled)
Controls whether TAB and SHIFT+TAB will transfer focus out of the RadioButtonGroup, or simply maintain their default behaviour.


add

public boolean add(Button button)
Add a button to the group.

Specified by:
add in interface Group<Button>
Overrides:
add in class ButtonGroup
Parameters:
button - The element to add to the group.
Returns:
true if the element was added to the group; false, otherwise.
See Also:
Group.add(Object), Sequence.add(Object)

get

public Button get(int index)
Return the button at the specified index.

See Also:
Sequence.get(int)

getLength

public int getLength()
Return the number of buttons in the group.

See Also:
Sequence.getLength()

indexOf

public int indexOf(Button button)
Return the index (order) of the button within the group.

Returns:
The index or -1 if the button does not belong to this RadioButtonGroup
See Also:
Sequence.indexOf(Object)

insert

public void insert(Button button,
                   int index)
Insert a button at the specified index.

See Also:
Sequence.insert(Object, int)

remove

public boolean remove(Button button)
Remove the button from the group.

Specified by:
remove in interface Group<Button>
Overrides:
remove in class ButtonGroup
Parameters:
button - The element to remove from the set.
Returns:
true if the element was removed from the group; false, otherwise.
See Also:
Group.remove(Object), Sequence.remove(Object)

remove

public Sequence<Button> remove(int index,
                               int count)
Remove count buttons from the group starting at index.

See Also:
Sequence.remove(int, int)

iterator

public Iterator<Button> iterator()
Return an iterator for the ordered list of buttons

Specified by:
iterator in interface Iterable<Button>
Overrides:
iterator in class ButtonGroup

setSelection

public void setSelection(Button button)
Select and focus the specified button.

Overrides:
setSelection in class ButtonGroup
See Also:
ButtonGroup.setSelection(Button)

setSelection

public void setSelection(int index)
Select and focus the button at the specified index, unless the index is NOT_FOUND_INDEX.


selectFirstButton

public void selectFirstButton()
Select the first focusable button in the group.


selectLastButton

public void selectLastButton()
Select the last focusable button in the group.


selectNextButton

public void selectNextButton(Button button)
Working forwards from the specified button, select the first focusable button.

Parameters:
button - If null, the first available button will be selected, unless the group contains a selected or focused button, in which case that button will be used as the starting point for the search.

selectPreviousButton

public void selectPreviousButton(Button button)
Working backwards from the specified button, select the first focusable button.

Parameters:
button - If null, the last available button will be selected, unless the group contains a selected or focused button, in which case that button will be used as the starting point for the search.