NAME

       "Tickit::Widget::RadioButton" - a widget allowing a selection from multiple options

SYNOPSIS

          use Tickit;
          use Tickit::Widget::RadioButton;
          use Tickit::Widget::VBox;

          my $group = Tickit::Widget::RadioButton::Group->new;

          my $vbox = Tickit::Widget::VBox->new;
          $vbox->add( Tickit::Widget::RadioButton->new(
                caption => "Radio button $_",
                group   => $group,
          ) ) for 1 .. 5;

          Tickit->new( root => $vbox )->run;

DESCRIPTION

       This class provides a widget which allows a selection of one value from a group of related
       options. It provides a clickable area and a visual indication of which button in the group
       is the one currently active. Selecting a new button within a group will unselect the
       previously-selected one.

       This widget is part of an experiment in evolving the design of the Tickit::Style widget
       integration code, and such is subject to change of details.

STYLE

       The default style pen is used as the widget pen. The following style pen prefixes are also
       used:

       tick => PEN
           The pen used to render the tick marker

       The following style keys are used:

       tick => STRING
           The text used to indicate the active button

       spacing => INT
           Number of columns of spacing between the tick mark and the caption text

       The following style tags are used:

       :active
           Set when this button is the active one of the group.

       The following style actions are used:

       activate
           The main action to activate the "on_click" handler.

CONSTRUCTOR

   new
          $radiobutton = Tickit::Widget::RadioButton->new( %args )

       Constructs a new "Tickit::Widget::RadioButton" object.

       Takes the following named argmuents

       label => STRING
               The label text to display alongside this button.

       group => Tickit::Widget::RadioButton::Group
               Optional. If supplied, the group that the button should belong to. If not
               supplied, a new group will be constructed that can be accessed using the "group"
               accessor.

       value => SCALAR
               Optional. If supplied, used to set the button's identification value, which is
               passed to the group's "on_changed" callback.

ACCESSORS

   group
          $group = $radiobutton->group

       Returns the "Tickit::Widget::RadioButton::Group" this button belongs to.

   label
   set_label
          $label = $radiobutton->label

          $radiobutton->set_label( $label )

       Returns or sets the label text of the button.

   on_toggle
          $on_toggle = $radiobutton->on_toggle

   set_on_toggle
          $radiobutton->set_on_toggle( $on_toggle )

       Return or set the CODE reference to be called when the button state is changed.

        $on_toggle->( $radiobutton, $active )

       When the radio tick mark moves from one button to another, the old button is marked
       unactive before the new one is marked active.

   value
          $value = $radiobutton->value

   set_value
          $radiobutton->set_value( $value )

       Return or set the scalar value used to identify the radio button to the group's
       "on_changed" callback. This can be any scalar value; it is simply stored by the button and
       not otherwise used.

METHODS

   activate
          $radiobutton->activate

       Sets this button as the active member of the group, deactivating the previous one.

   is_active
          $active = $radiobutton->is_active

       Returns true if this button is the active button of the group.

GROUPS

       Every "Tickit::Widget::RadioButton" belongs to a group. Only one button can be active in a
       group at any one time. The "group" accessor returns the group the button is a member of.
       The following methods are available on it.

       A group can be explicitly created to pass to a button's constructor, or one will be
       implicitly created for a button if none is passed.

   new
          $group = Tickit::Widget::RadioButton::Group->new

       Returns a new group.

   active
          $radiobutton = $group->active

       Returns the button which is currently active in the group

   on_changed
          $on_changed = $group->on_changed

   set_on_changed
          $group->set_on_changed( $on_changed )

       Return or set the CODE reference to be called when the active member of the group changes.
       This may be more convenient than setting the "on_toggle" callback of each button in the
       group.

       The callback is passed the currently-active button, and its "value".

          $on_changed->( $active, $value )

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>