Places a label next to an indicator.
<picture> <source srcset="check-button-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Example GtkCheckButtons" src="check-button.png"> </picture> A GtkCheckButton is created by calling either [ctorGtk.CheckButton.new] or [ctorGtk.CheckButton.new_with_label].
The state of a GtkCheckButton can be set specifically using [methodGtk.CheckButton.set_active], and retrieved using [methodGtk.CheckButton.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 GtkCheckButton to inconsistent state, use [methodGtk.CheckButton.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.
<picture> <source srcset="radio-button-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Example GtkRadioButtons" src="radio-button.png"> </picture> To add a GtkCheckButton to a group, use [methodGtk.CheckButton.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 GAction with a target for each button. Using the toggled signals to keep track of the group changes and state is discouraged.
# Shortcuts and Gestures
GtkCheckButton supports the following keyboard shortcuts:
<kbd>â£</kbd> or <kbd>Enter</kbd> activates the button.
# CSS nodes
checkbutton[.text-button][.grouped] âââ check â°ââ [label]
A GtkCheckButton has a main node with name checkbutton. If the [propertyGtk.CheckButton:label] or [propertyGtk.CheckButton: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
GtkCheckButton uses the [enumGtk.AccessibleRole.checkbox] role.
function "+"
(Widget : access Gtk_Check_Button_Record'Class)
return Gtk.Accessible.Gtk_Accessible
function "+"
(Widget : access Gtk_Check_Button_Record'Class)
return Gtk.Buildable.Gtk_Buildable
function "+"
(Widget : access Gtk_Check_Button_Record'Class)
return Gtk.Constraint_Target.Gtk_Constraint_Target
function "-"
(Interf : Gtk.Accessible.Gtk_Accessible)
return Gtk_Check_Button
function "-"
(Interf : Gtk.Buildable.Gtk_Buildable)
return Gtk_Check_Button
function "-"
(Interf : Gtk.Constraint_Target.Gtk_Constraint_Target)
return Gtk_Check_Button
Active_Property : constant Glib.Properties.Property_Boolean;
If the check button is active.
Setting active to True will add the :checked: state to both the check button and the indicator CSS node.
procedure Announce
(Self : not null access Gtk_Check_Button_Record;
Message : UTF8_String;
Priority : Gtk.Accessible.Gtk_Accessible_Announcement_Priority)
type Cb_GObject_Void is not null access procedure
(Self : access Glib.Object.GObject_Record'Class);
type Cb_Gtk_Check_Button_Void is not null access procedure
(Self : access Gtk_Check_Button_Record'Class);
Child_Property : constant Glib.Properties.Property_Object;
Type: Gtk.Widget.Gtk_Widget The child widget.
function Get_Accessible_Id
(Self : not null access Gtk_Check_Button_Record) return UTF8_String
function Get_Accessible_Parent
(Self : not null access Gtk_Check_Button_Record)
return Gtk.Accessible.Gtk_Accessible
function Get_Accessible_Role
(Self : not null access Gtk_Check_Button_Record)
return Gtk.Accessible.Gtk_Accessible_Role
function Get_Active
(Self : not null access Gtk_Check_Button_Record) return Boolean
Returns whether the check button is active.
whether the check button is active
function Get_At_Context
(Self : not null access Gtk_Check_Button_Record)
return Gtk.Atcontext.Gtk_Atcontext
function Get_Bounds
(Self : not null access Gtk_Check_Button_Record;
X : out Glib.Gint;
Y : out Glib.Gint;
Width : out Glib.Gint;
Height : out Glib.Gint) return Boolean
function Get_Child
(Self : not null access Gtk_Check_Button_Record)
return Gtk.Widget.Gtk_Widget
Gets the child widget of Button or NULL if [propertyCheckbutton:label] is set. Since: gtk+ 4.8
the child widget of Button. Has transfer-ownership='none'.
function Get_First_Accessible_Child
(Self : not null access Gtk_Check_Button_Record)
return Gtk.Accessible.Gtk_Accessible
function Get_Inconsistent
(Self : not null access Gtk_Check_Button_Record) return Boolean
Returns whether the check button is in an inconsistent state.
True if Check_Button is currently in an inconsistent state
function Get_Label
(Self : not null access Gtk_Check_Button_Record) return UTF8_String
Returns the label of the check button or NULL if [propertyCheckbutton:child] is set.
The label Self shows next to the indicator. If no label is shown, null will be returned.
function Get_Next_Accessible_Sibling
(Self : not null access Gtk_Check_Button_Record)
return Gtk.Accessible.Gtk_Accessible
function Get_Platform_State
(Self : not null access Gtk_Check_Button_Record;
State : Gtk.Accessible.Gtk_Accessible_Platform_State) return Boolean
function Get_Type return Glib.GType
function Get_Use_Underline
(Self : not null access Gtk_Check_Button_Record) return Boolean
Returns whether underlines in the label indicate mnemonics.
The value of the [propertyGtk.CheckButton:use-underline] property. See [methodGtk.CheckButton.set_use_underline] for details on how to set a new value.
Group_Property : constant Glib.Properties.Property_Object;
Type: Gtk_Check_Button Flags: write The check button whose group this widget belongs to.
type Gtk_Check_Button is access all Gtk_Check_Button_Record'Class;
function Gtk_Check_Button_New return Gtk_Check_Button
Creates a new GtkCheckButton.
function Gtk_Check_Button_New_With_Label
(Label : UTF8_String := "") return Gtk_Check_Button
Creates a new GtkCheckButton with the given text.
the text for the check button.
function Gtk_Check_Button_New_With_Mnemonic
(Label : UTF8_String := "") return Gtk_Check_Button
Creates a new GtkCheckButton with the given text and a mnemonic.
The text of the button, with an underscore in front of the mnemonic character
type Gtk_Check_Button_Record is new Gtk_Widget_Record with null record;
procedure Gtk_New (Self : out Gtk_Check_Button)
Creates a new GtkCheckButton. Initialize does nothing if the object was already created with another call to Initialize* or G_New.
procedure Gtk_New_With_Label
(Self : out Gtk_Check_Button;
Label : UTF8_String := "")
Creates a new GtkCheckButton with the given text. Initialize_With_Label does nothing if the object was already created with another call to Initialize* or G_New.
the text for the check button.
procedure Gtk_New_With_Mnemonic
(Self : out Gtk_Check_Button;
Label : UTF8_String := "")
Creates a new GtkCheckButton with the given text and a mnemonic. Initialize_With_Mnemonic does nothing if the object was already created with another call to Initialize* or G_New.
The text of the button, with an underscore in front of the mnemonic character
package Implements_Gtk_Accessible is new Glib.Types.Implements
(Gtk.Accessible.Gtk_Accessible, Gtk_Check_Button_Record, Gtk_Check_Button);
package Implements_Gtk_Buildable is new Glib.Types.Implements
(Gtk.Buildable.Gtk_Buildable, Gtk_Check_Button_Record, Gtk_Check_Button);
package Implements_Gtk_Constraint_Target is new Glib.Types.Implements
(Gtk.Constraint_Target.Gtk_Constraint_Target, Gtk_Check_Button_Record, Gtk_Check_Button);
Inconsistent_Property : constant Glib.Properties.Property_Boolean;
If the check button is in an "in between" state.
The inconsistent state only affects visual appearance, not the semantics of the button.
procedure Initialize
(Self : not null access Gtk_Check_Button_Record'Class)
Creates a new GtkCheckButton. Initialize does nothing if the object was already created with another call to Initialize* or G_New.
procedure Initialize_With_Label
(Self : not null access Gtk_Check_Button_Record'Class;
Label : UTF8_String := "")
Creates a new GtkCheckButton with the given text. Initialize_With_Label does nothing if the object was already created with another call to Initialize* or G_New.
the text for the check button.
procedure Initialize_With_Mnemonic
(Self : not null access Gtk_Check_Button_Record'Class;
Label : UTF8_String := "")
Creates a new GtkCheckButton with the given text and a mnemonic. Initialize_With_Mnemonic does nothing if the object was already created with another call to Initialize* or G_New.
The text of the button, with an underscore in front of the mnemonic character
Label_Property : constant Glib.Properties.Property_String;
Text of the label inside the check button, if it contains a label widget.
procedure On_Activate
(Self : not null access Gtk_Check_Button_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
Emitted to when the check button is activated.
The ::activate signal on GtkCheckButton 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 [signalGtk.CheckButton::toggled] signal.
The default bindings for this signal are all forms of the <kbd>â£</kbd> and <kbd>Enter</kbd> keys.
procedure On_Activate
(Self : not null access Gtk_Check_Button_Record;
Call : Cb_Gtk_Check_Button_Void;
After : Boolean := False)
Emitted to when the check button is activated.
The ::activate signal on GtkCheckButton 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 [signalGtk.CheckButton::toggled] signal.
The default bindings for this signal are all forms of the <kbd>â£</kbd> and <kbd>Enter</kbd> keys.
procedure On_Toggled
(Self : not null access Gtk_Check_Button_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
Emitted when the buttons's [propertyGtk.CheckButton:active] property changes.
procedure On_Toggled
(Self : not null access Gtk_Check_Button_Record;
Call : Cb_Gtk_Check_Button_Void;
After : Boolean := False)
Emitted when the buttons's [propertyGtk.CheckButton:active] property changes.
procedure Reset_Property
(Self : not null access Gtk_Check_Button_Record;
Property : Gtk.Accessible.Gtk_Accessible_Property)
procedure Reset_Relation
(Self : not null access Gtk_Check_Button_Record;
Relation : Gtk.Accessible.Gtk_Accessible_Relation)
procedure Reset_State
(Self : not null access Gtk_Check_Button_Record;
State : Gtk.Accessible.Gtk_Accessible_State)
procedure Set_Accessible_Parent
(Self : not null access Gtk_Check_Button_Record;
Parent : Gtk.Accessible.Gtk_Accessible;
Next_Sibling : Gtk.Accessible.Gtk_Accessible)
procedure Set_Active
(Self : not null access Gtk_Check_Button_Record;
Setting : Boolean)
Changes the check buttons active state.
the new value to set
procedure Set_Child
(Self : not null access Gtk_Check_Button_Record;
Child : access Gtk.Widget.Gtk_Widget_Record'Class)
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. Since: gtk+ 4.8
the child widget
procedure Set_Group
(Self : not null access Gtk_Check_Button_Record;
Group : access Gtk_Check_Button_Record'Class)
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 [ifaceGtk.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.
another GtkCheckButton to form a group with
procedure Set_Inconsistent
(Self : not null access Gtk_Check_Button_Record;
Inconsistent : Boolean)
Sets the GtkCheckButton to inconsistent state. You should turn off the inconsistent state again if the user checks the check button. This has to be done manually.
True if state is inconsistent
procedure Set_Label
(Self : not null access Gtk_Check_Button_Record;
Label : UTF8_String := "")
Sets the text of Self. If [propertyGtk.CheckButton:use-underline] is True, an underscore in Label is interpreted as mnemonic indicator, see [methodGtk.CheckButton.set_use_underline] for details on this behavior.
The text shown next to the indicator, or null to show no text
procedure Set_Use_Underline
(Self : not null access Gtk_Check_Button_Record;
Setting : Boolean)
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 [propertyGtk.Label:use-underline].
the new value to set
Signal_Activate : constant Glib.Signal_Name := "activate";
Emitted to when the check button is activated.
The ::activate signal on GtkCheckButton 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 [signalGtk.CheckButton::toggled] signal.
The default bindings for this signal are all forms of the <kbd>â£</kbd> and <kbd>Enter</kbd> keys.
Signal_Toggled : constant Glib.Signal_Name := "toggled";
Emitted when the buttons's [propertyGtk.CheckButton:active] property changes.
procedure Update_Next_Accessible_Sibling
(Self : not null access Gtk_Check_Button_Record;
New_Sibling : Gtk.Accessible.Gtk_Accessible)
procedure Update_Platform_State
(Self : not null access Gtk_Check_Button_Record;
State : Gtk.Accessible.Gtk_Accessible_Platform_State)
Use_Underline_Property : constant Glib.Properties.Property_Boolean;
If set, an underline in the text indicates that the following character is to be used as mnemonic.