## GtkToggleButton GtkToggleButton — Create buttons which retain their state |

## Functions

GtkWidget * | gtk_toggle_button_new ()
GtkWidget * | gtk_toggle_button_new_with_label ()
GtkWidget * | gtk_toggle_button_new_with_mnemonic ()
void | gtk_toggle_button_toggled ()
gboolean | gtk_toggle_button_get_active ()
void | gtk_toggle_button_set_active ()
void | gtk_toggle_button_set_group ()

## Properties

gboolean | active | Read / Write
GtkToggleButton * | group | Write

## Signals

void | toggled | Run First

## Types and Values

struct | GtkToggleButton

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkButton
                    ╰── GtkToggleButton

## Implemented Interfaces

GtkToggleButton implements GtkAccessible, GtkBuildable, GtkConstraintTarget and GtkActionable.

## Includes

    #include <gtk/gtk.h>

## Description

A GtkToggleButton is a GtkButton which will remain “pressed-in” when clicked. Clicking again will cause the toggle button to return to its normal state.

A toggle button is created by calling either `gtk_toggle_button_new()` or `gtk_toggle_button_new_with_label()`. If using the former, it is advisable to pack a widget, (such as a GtkLabel and/or a GtkImage), into the toggle button’s container. (See GtkButton for more information).

The state of a GtkToggleButton can be set specifically using `gtk_toggle_button_set_active()`, and retrieved using `gtk_toggle_button_get_active()`.

To simply switch the state of a toggle button, use `gtk_toggle_button_toggled()`.

### CSS nodes

GtkToggleButton has a single CSS node with name button. To differentiate it from a plain GtkButton, it gets the .toggle style class.

#### Creating two GtkToggleButton widgets.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    static void output_state (GtkToggleButton *source, gpointer user_data) {
      printf ("Active: %d\n", gtk_toggle_button_get_active (source));
    }

    void make_toggles (void) {
      GtkWidget *window, *toggle1, *toggle2;
      GtkWidget *box;
      const char *text;

      window = gtk_window_new ();
      box = gtk_box_new (GTK_ORIENTATION_VERTICAL, 12);

      text = "Hi, I’m a toggle button.";
      toggle1 = gtk_toggle_button_new_with_label (text);

      g_signal_connect (toggle1, "toggled",
                        G_CALLBACK (output_state),
                        NULL);
      gtk_box_append (GTK_BOX (box), toggle1);

      text = "Hi, I’m a toggle button.";
      toggle2 = gtk_toggle_button_new_with_label (text);
      g_signal_connect (toggle2, "toggled",
                        G_CALLBACK (output_state),
                        NULL);
      gtk_box_append (GTK_BOX (box), toggle2);

      gtk_window_set_child (GTK_WINDOW (window), box);
      gtk_widget_show (window);
    }

## Functions

### gtk_toggle_button_new ()

    GtkWidget *
    gtk_toggle_button_new (void);

Creates a new toggle button. A widget should be packed into the button, as in `gtk_button_new()`.

#### Returns

a new toggle button.

### gtk_toggle_button_new_with_label ()

    GtkWidget *
    gtk_toggle_button_new_with_label (const char *label);

Creates a new toggle button with a text label.

#### Parameters

label | a string containing the message to be placed in the toggle button. |

#### Returns

a new toggle button.

### gtk_toggle_button_new_with_mnemonic ()

    GtkWidget *
    gtk_toggle_button_new_with_mnemonic (const char *label);

Creates a new GtkToggleButton containing a label. The label will be created using `gtk_label_new_with_mnemonic()`, so underscores in `label` indicate the mnemonic for the button.

#### Parameters

label | the text of the button, with an underscore in front of the mnemonic character |

#### Returns

a new GtkToggleButton

### gtk_toggle_button_toggled ()

    void
    gtk_toggle_button_toggled (GtkToggleButton *toggle_button);

Emits the “toggled” signal on the GtkToggleButton. There is no good reason for an application ever to call this function.

#### Parameters

toggle_button | a GtkToggleButton. |

### gtk_toggle_button_get_active ()

    gboolean
    gtk_toggle_button_get_active (GtkToggleButton *toggle_button);

Queries a GtkToggleButton and returns its current state. Returns `TRUE` if the toggle button is pressed in and `FALSE` if it is raised.

#### Parameters

toggle_button | a GtkToggleButton. |

#### Returns

a gboolean value.

### gtk_toggle_button_set_active ()

    void
    gtk_toggle_button_set_active (GtkToggleButton *toggle_button,
                                  gboolean is_active);

Sets the status of the toggle button. Set to `TRUE` if you want the GtkToggleButton to be “pressed in”, and `FALSE` to raise it.

If the status of the button changes, this action causes the “toggled” signal to be emitted.

#### Parameters

toggle_button | a GtkToggleButton. |
is_active | `TRUE` or `FALSE`. |

### gtk_toggle_button_set_group ()

    void
    gtk_toggle_button_set_group (GtkToggleButton *toggle_button,
                                 GtkToggleButton *group);

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

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

toggle_button | a GtkToggleButton |
group | another GtkToggleButton to form a group with. | [nullable][transfer none]

## Types and Values

### struct GtkToggleButton

    struct GtkToggleButton;

## Property Details

### The `“active”` property

      “active”                   gboolean

If the toggle button should be pressed in.

Owner: GtkToggleButton

Flags: Read / Write

Default value: FALSE

### The `“group”` property

      “group”                    GtkToggleButton *

The toggle button whose group this widget belongs to.

Owner: GtkToggleButton

Flags: Write

## Signal Details

### The `“toggled”` signal

    void
    user_function (GtkToggleButton *togglebutton,
                   gpointer         user_data)

Should be connected if you wish to perform an action whenever the GtkToggleButton's state is changed.

#### Parameters

togglebutton | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

## See Also

GtkButton, GtkCheckButton