GtkToggleButton

GtkToggleButton — Create buttons which retain their state

Properties

gboolean active Read / Write

Signals

void toggled Run First

Types and Values

Object Hierarchy

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

Implemented Interfaces

GtkToggleButton implements AtkImplementorIface, 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 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.

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.

 

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

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