Gnome::Gtk4::CheckButton
Description
A Gnome::Gtk4::CheckButton places a label next to an indicator.
A Gnome::Gtk4::CheckButton is created by calling either .newcheckbutton()
or .new-with-label()
.
The state of a Gnome::Gtk4::CheckButton can be set specifically using .set-active()
, and retrieved using .get-active()
.
Inconsistent state
In addition to "on" and "off", check buttons can be an "in between" state that is neither on nor off. This can be used e.g. when the user has selected a range of elements (such as some text or spreadsheet cells) that are affected by a check button, and the current values in that range are inconsistent.
To set a Gnome::Gtk4::CheckButton to inconsistent state, use .set-inconsistent()
.
Grouping
Check buttons can be grouped together, to form mutually exclusive groups - only one of the buttons can be toggled at a time, and toggling another one will switch the currently toggled one off.
Grouped check buttons use a different indicator, and are commonly referred to as *radio buttons*.
To add a Gnome::Gtk4::CheckButton to a group, use .set-group()
.
When the code must keep track of the state of a group of radio buttons, it is recommended to keep track of such state through a stateful Gnome::Gio::R-Action with a target for each button. Using the toggled signals to keep track of the group changes and state is discouraged.
CSS nodes
A Gnome::Gtk4::CheckButton has a main node with name checkbutton. If the label or child properties are set, it contains a child widget. The indicator node is named check when no group is set, and radio if the checkbutton is grouped together with other checkbuttons.
Accessibility
Gnome::Gtk4::CheckButton uses the GTK_ACCESSIBLE_ROLE_CHECKBOX
role.
Class initialization
new
:native-object
Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.
multi method new ( N-Object :$native-object! )
new-checkbutton
Creates a new Gnome::Gtk4::CheckButton.
method new-checkbutton ( --> Gnome::Gtk4::CheckButton \)
new-with-label
Creates a new Gnome::Gtk4::CheckButton with the given text.
method new-with-label ( Str $label --> Gnome::Gtk4::CheckButton \)
$label; the text for the check button..
new-with-mnemonic
Creates a new Gnome::Gtk4::CheckButton with the given text and a mnemonic.
method new-with-mnemonic ( Str $label --> Gnome::Gtk4::CheckButton \)
$label; The text of the button, with an underscore in front of the mnemonic character.
Methods
get-active
Returns whether the check button is active.
method get-active (--> Bool )
Return value; whether the check button is active.
get-child
Gets the child widget of $button
or undefined if [property $CheckButton
:label] is set.
method get-child (--> N-Object )
Return value; the child widget of $button
.
get-inconsistent
Returns whether the check button is in an inconsistent state.
method get-inconsistent (--> Bool )
Return value; True
if $check-button
is currently in an inconsistent state.
get-label
Returns the label of the check button or undefined if [property $CheckButton
:child] is set.
method get-label (--> Str )
Return value; The label $self
shows next to the indicator. If no label is shown, undefined will be returned..
get-use-underline
Returns whether underlines in the label indicate mnemonics.
method get-use-underline (--> Bool )
Return value; The value of the use-underline property. See .set-use-underline()
for details on how to set a new value..
set-active
Changes the check buttons active state.
method set-active ( Bool() $setting )
$setting; the new value to set.
set-child
Sets the child widget of $button
.
Note that by using this API, you take full responsibility for setting up the proper accessibility label and description information for $button
. Most likely, you'll either set the accessibility label or description for $button
explicitly, or you'll set a labelled-by or described-by relations from $child
to $button
.
method set-child ( N-Object() $child )
$child; the child widget.
set-group
Adds $self
to the group of $group
.
In a group of multiple check buttons, only one button can be active at a time. The behavior of a checkbutton in a group is also commonly known as a *radio button*.
Setting the group of a check button also changes the css name of the indicator widget's CSS node to 'radio'.
Setting up groups in a cycle leads to undefined behavior.
Note that the same effect can be achieved via the Gnome::Gtk4::R-Actionable API, by using the same action with parameter type and state type 's' for all buttons in the group, and giving each button its own target value.
method set-group ( N-Object() $group )
$group; another Gnome::Gtk4::CheckButton to form a group with.
set-inconsistent
Sets the Gnome::Gtk4::CheckButton to inconsistent state.
You should turn off the inconsistent state again if the user checks the check button. This has to be done manually.
method set-inconsistent ( Bool() $inconsistent )
$inconsistent;
True
if state is inconsistent.
set-label
Sets the text of $self
.
If use-underline is True
, an underscore in $label
is interpreted as mnemonic indicator, see .set-use-underline()
for details on this behavior.
method set-label ( Str $label )
$label; The text shown next to the indicator, or undefined to show no text.
set-use-underline
Sets whether underlines in the label indicate mnemonics.
If $setting
is True
, an underscore character in $self
's label indicates a mnemonic accelerator key. This behavior is similar to use-underline defined in Gnome::Gtk4::Label.
method set-use-underline ( Bool() $setting )
$setting; the new value to set.
Signals
activate
Emitted to when the check button is activated.
The `::activate` signal on Gnome::Gtk4::CheckButton is an action signal and emitting it causes the button to animate press then release.
Applications should never connect to this signal, but use the toggled signal.
The default bindings for this signal are all forms of the <kbd>␣</kbd> and <kbd>Enter</kbd> keys.
method handler ( Int :$_handle_id, N-GObject :$_native-object, Gnome::Gtk4::CheckButton :$_widget, *C<user>-options )
$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::CheckButton object.
$_widget; The object which registered the signal. User code may have left the object going out of scope.
user
-options; A list of named arguments provided at the.register-signal()
method from Gnome::GObject::Object.
toggled
Emitted when the buttons's active property changes.
method handler ( Int :$_handle_id, N-GObject :$_native-object, Gnome::Gtk4::CheckButton :$_widget, *C<user>-options )
$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::CheckButton object.
$_widget; The object which registered the signal. User code may have left the object going out of scope.
user
-options; A list of named arguments provided at the.register-signal()
method from Gnome::GObject::Object.