## GtkCheckButton GtkCheckButton — Create widgets with a discrete toggle button |

## Functions

GtkWidget * | gtk_check_button_new ()
GtkWidget * | gtk_check_button_new_with_label ()
GtkWidget * | gtk_check_button_new_with_mnemonic ()
const char * | gtk_check_button_get_label ()
void | gtk_check_button_set_label ()
gboolean | gtk_check_button_get_use_underline ()
void | gtk_check_button_set_use_underline ()
void | gtk_check_button_set_group ()
gboolean | gtk_check_button_get_active ()
void | gtk_check_button_set_active ()
gboolean | gtk_check_button_get_inconsistent ()
void | gtk_check_button_set_inconsistent ()

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

struct | GtkCheckButton

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

## See Also

GtkButton, GtkToggleButton