GtkCheckButton

GtkCheckButton — Create widgets with a discrete toggle button

Properties

gboolean active Read / Write
GtkCheckButton * group Write
gboolean inconsistent Read / Write
char * label Read / Write
gboolean use-underline Read / Write

Signals

void activate Action
void toggled Run First

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkCheckButton

Implemented Interfaces

GtkCheckButton implements GtkAccessible, GtkBuildable, GtkConstraintTarget and GtkActionable.

Includes

#include <gtk/gtk.h>

Description

A GtkCheckButton places a label next to an indicator.

CSS nodes

1
2
3
checkbutton[.text-button]
├── check
╰── [label]

A GtkCheckButton has a main node with name checkbutton. If the “label” property is set, it contains a label child. 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 GTK_ACCESSIBLE_ROLE_CHECKBOX role.

Functions

gtk_check_button_new ()

GtkWidget *
gtk_check_button_new (void);

Creates a new GtkCheckButton.

Returns

a GtkWidget.


gtk_check_button_new_with_label ()

GtkWidget *
gtk_check_button_new_with_label (const char *label);

Creates a new GtkCheckButton with a GtkLabel next to it, if label is non-NULL.

Parameters

label

the text for the check button.

[nullable]

Returns

a new GtkCheckButton


gtk_check_button_new_with_mnemonic ()

GtkWidget *
gtk_check_button_new_with_mnemonic (const char *label);

Creates a new GtkCheckButton containing a label. Underscores in label indicate the mnemonic for the check button.

Parameters

label

The text of the button, with an underscore in front of the mnemonic character.

[nullable]

Returns

a new GtkCheckButton


gtk_check_button_get_label ()

const char *
gtk_check_button_get_label (GtkCheckButton *self);

Returns the label of the checkbutton.

Parameters

self

a GtkCheckButton

 

Returns

The label self shows next to the indicator. If no label is shown, NULL will be returned.

[nullable][transfer none]


gtk_check_button_set_label ()

void
gtk_check_button_set_label (GtkCheckButton *self,
                            const char *label);

Sets the text of self . If “use-underline” is TRUE, the underscore in label is interpreted as mnemonic indicator, see gtk_check_button_set_use_underline() for details on this behavior.

Parameters

self

a GtkCheckButton

 

label

The text shown next to the indicator, or NULL to show no text.

[nullable]

gtk_check_button_get_use_underline ()

gboolean
gtk_check_button_get_use_underline (GtkCheckButton *self);

Returns the current value of the “use-underline” property.

Parameters

self

a GtkCheckButton

 

Returns

The value of the “use-underline” property. See gtk_check_button_set_use_underline() for details on how to set a new value.


gtk_check_button_set_use_underline ()

void
gtk_check_button_set_use_underline (GtkCheckButton *self,
                                    gboolean setting);

Sets the new value of the “use-underline” property. See also gtk_check_button_get_use_underline().

If setting is TRUE, an underscore character in self 's label indicates a mnemonic accelerator key. This behavior is similar to “use-underline”.

Parameters

self

a GtkCheckButton

 

setting

the new value to set

 

gtk_check_button_set_group ()

void
gtk_check_button_set_group (GtkCheckButton *self,
                            GtkCheckButton *group);

Adds self to the group of group . In a group of multiple check buttons, only one button can be active at a time.

Setting the group of a check button also changes the css name of the indicator widget's CSS node to 'radio'.

The behavior of a checkbutton in a group is also commonly known as a 'radio button'.

Note that the same effect can be achieved via the GtkActionable 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.

Parameters

self

a GtkCheckButton

 

group

another GtkCheckButton to form a group with.

[nullable][transfer none]

gtk_check_button_get_active ()

gboolean
gtk_check_button_get_active (GtkCheckButton *self);

Returns the current value of the “active” property.

Parameters

self

a GtkCheckButton

 

Returns

The value of the “active” property. See gtk_check_button_set_active() for details on how to set a new value.


gtk_check_button_set_active ()

void
gtk_check_button_set_active (GtkCheckButton *self,
                             gboolean setting);

Sets the new value of the “active” property. See also gtk_check_button_get_active().

Setting “active” to TRUE will add the :checked: state to both the checkbutton and the indicator CSS node.

Parameters

self

a GtkCheckButton

 

setting

the new value to set

 

gtk_check_button_get_inconsistent ()

gboolean
gtk_check_button_get_inconsistent (GtkCheckButton *check_button);

Returns whether the check button is in an inconsistent state.

Parameters

check_button

a GtkCheckButton

 

Returns

TRUE if check_button is currently in an 'in between' state, FALSE otherwise.


gtk_check_button_set_inconsistent ()

void
gtk_check_button_set_inconsistent (GtkCheckButton *check_button,
                                   gboolean inconsistent);

If 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, you may want to display the toggle in an "in between" state. Normally you would turn off the inconsistent state again if the user checks the check button. This has to be done manually, gtk_check_button_set_inconsistent only affects visual appearance, not the semantics of the button.

Parameters

check_button

a GtkCheckButton

 

inconsistent

TRUE if state is inconsistent

 

Types and Values

struct GtkCheckButton

struct GtkCheckButton;

Property Details

The “active” property

  “active”                   gboolean

If the toggle button should be pressed in.

Owner: GtkCheckButton

Flags: Read / Write

Default value: FALSE


The “group” property

  “group”                    GtkCheckButton *

The check button whose group this widget belongs to.

Owner: GtkCheckButton

Flags: Write


The “inconsistent” property

  “inconsistent”             gboolean

If the check button is in an “in between” state.

Owner: GtkCheckButton

Flags: Read / Write

Default value: FALSE


The “label” property

  “label”                    char *

Text of the label widget inside the button, if the button contains a label widget.

Owner: GtkCheckButton

Flags: Read / Write

Default value: NULL


The “use-underline” property

  “use-underline”            gboolean

If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key.

Owner: GtkCheckButton

Flags: Read / Write

Default value: FALSE

Signal Details

The “activate” signal

void
user_function (GtkCheckButton *widget,
               gpointer        user_data)

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 “toggled” signal.

Parameters

widget

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “toggled” signal

void
user_function (GtkCheckButton *checkbutton,
               gpointer        user_data)

Emitted when the buttons's “active” flag changes.

Parameters

user_data

user data set when the signal handler was connected.

 

Flags: Run First