Package org.apache.pivot.wtk

Class RadioButtonGroup

  • All Implemented Interfaces:
    java.lang.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 and LEFT Select the previous button
    DOWN and 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.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean add​(Button button)
      Add a button to the group.
      Button get​(int index)  
      int getLength()  
      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.
      Instead, the search will 'wrap' and continue from the opposite bound until each button in the entire group has been tested for inclusion.
      boolean isIntraGroupFocusTransferEnabled()
      When true, TAB and SHIFT+TAB transfer focus out of the RadioButtonGroup.
      java.util.Iterator<Button> iterator()  
      Sequence<Button> remove​(int index, int count)
      Remove count buttons from the group starting at index.
      boolean remove​(Button button)
      Remove the button from the group.
      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.
      Instead, the search will 'wrap' and continue from the opposite bound until each button in the entire group has been tested for inclusion.
      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​(int index)
      Select and focus the button at the specified index, unless the index is NOT_FOUND_INDEX.
      void setSelection​(Button button)
      Select and focus the specified button.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • 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
        Returns:
        Whether the group is circular.

      • 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.
        Parameters:
        circular - New setting for the group.

      • isIntraGroupFocusTransferEnabled

        public boolean isIntraGroupFocusTransferEnabled()
        When true, TAB and SHIFT+TAB transfer focus out of the RadioButtonGroup.
        Defaults to false
        Returns:
        Whether focus transfers out of the group on TAB.

      • 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.
        Parameters:
        intraGroupFocusTransferEnabled - New setting for this group.

      • 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 button to add.
        Returns:
        true if the element was added to the group; false, otherwise.
        Throws:
        java.lang.IllegalArgumentException - if the button parameter is null.
        See Also:
        Group.add(Object), Sequence.add(Object)

      • get

        public Button get​(int index)
        Parameters:
        index - The location to retrieve the button from.
        Returns:
        The button at the specified index.
        See Also:
        Sequence.get(int)

      • getLength

        public int getLength()
        Returns:
        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.
        Parameters:
        button - The button to search for in this group.
        Returns:
        The index or NOT_FOUND_INDEX 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.
        Parameters:
        button - The button to be inserted.
        index - Where to insert the button.
        Throws:
        java.lang.IllegalArgumentException - if the button parameter is null.
        See Also:
        Sequence.insert(Object, int)

      • remove

        public Sequence<Button> remove​(int index,
                               int count)
        Remove count buttons from the group starting at index.
        Parameters:
        index - Starting point for the removal.
        count - Number of buttons to remove.
        Returns:
        The sequence of buttons actually removed (will not be null, but could be an empty sequence).
        See Also:
        Sequence.remove(int, int)

      • iterator

        public java.util.Iterator<Button> iterator()
        Specified by:
        iterator in interface java.lang.Iterable<Button>
        Overrides:
        iterator in class ButtonGroup
        Returns:
        An iterator for the ordered list of buttons

      • setSelection

        public void setSelection​(int index)
        Select and focus the button at the specified index, unless the index is NOT_FOUND_INDEX.
        Parameters:
        index - The new selection index for the group.

      • 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.