---
name: "Tickit::Widget::RadioButton"
section: "3pm"
platform: "linux"
package: "libtickit-widgets-perl"
version: "0.42-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Tickit::Widget::RadioButton"
---

# Tickit::Widget::RadioButton(3pm)

a widget allowing a selection from multiple options

## 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\>