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

## Properties

gboolean | active | Read / Write

## Signals

void | toggled | Run First

## Types and Values

struct | GtkToggleButton

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GtkButton
                            ╰── GtkToggleButton
                                ├── GtkCheckButton
                                ╰── GtkMenuButton

## Implemented Interfaces

GtkToggleButton implements AtkImplementorIface, GtkBuildable 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
    void make_toggles (void) {
       GtkWidget *dialog, *toggle1, *toggle2;
       GtkWidget *content_area;
       const char *text;

       dialog = gtk_dialog_new (text);
       content_area = gtk_dialog_get_content_area ();

       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_pack_start (GTK_BOX (content_area),
                           toggle1, FALSE, FALSE, 2);

       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_pack_start (GTK_BOX (content_area),
                           toggle2, FALSE, FALSE, 2);

       gtk_widget_show (dialog);
    }

## 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 gchar *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 gchar *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. This action causes the “toggled” signal and the “clicked” signal to be emitted.

#### Parameters

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

## Types and Values

### struct GtkToggleButton

    struct GtkToggleButton;

## Property Details

### The `“active”` property

      “active”                   gboolean

If the toggle button should be pressed in.

Flags: Read / Write

Default value: FALSE

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