GtkSwitch

GtkSwitch — A “light switch” style toggle

Properties

gboolean active Read / Write
gboolean state Read / Write

Signals

void activate Action
gboolean state-set Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkSwitch

Implemented Interfaces

GtkSwitch implements AtkImplementorIface, GtkBuildable, GtkConstraintTarget and GtkActionable.

Includes

#include <gtk/gtk.h>

Description

GtkSwitch is a widget that has two states: on or off. The user can control which state should be active by clicking the empty area, or by dragging the handle.

GtkSwitch can also handle situations where the underlying state changes with a delay. See “state-set” for details.

CSS nodes

1
2
3
4
switch
├── label
├── label
╰── slider

GtkSwitch has four css nodes, the main node with the name switch and subnodes for the slider and the on and off labels. Neither of them is using any style classes.

Functions

gtk_switch_new ()

GtkWidget *
gtk_switch_new (void);

Creates a new GtkSwitch widget.

Returns

the newly created GtkSwitch instance


gtk_switch_set_active ()

void
gtk_switch_set_active (GtkSwitch *self,
                       gboolean is_active);

Changes the state of self to the desired one.

Parameters

self

a GtkSwitch

 

is_active

TRUE if self should be active, and FALSE otherwise

 

gtk_switch_get_active ()

gboolean
gtk_switch_get_active (GtkSwitch *self);

Gets whether the GtkSwitch is in its “on” or “off” state.

Parameters

self

a GtkSwitch

 

Returns

TRUE if the GtkSwitch is active, and FALSE otherwise


gtk_switch_set_state ()

void
gtk_switch_set_state (GtkSwitch *self,
                      gboolean state);

Sets the underlying state of the GtkSwitch.

Normally, this is the same as “active”, unless the switch is set up for delayed state changes. This function is typically called from a “state-set” signal handler.

See “state-set” for details.

Parameters

self

a GtkSwitch

 

state

the new state

 

gtk_switch_get_state ()

gboolean
gtk_switch_get_state (GtkSwitch *self);

Gets the underlying state of the GtkSwitch.

Parameters

self

a GtkSwitch

 

Returns

the underlying state

Types and Values

GtkSwitch

typedef struct _GtkSwitch GtkSwitch;

The GtkSwitch contains private data and it should only be accessed using the provided API.

Property Details

The “active” property

  “active”                   gboolean

Whether the GtkSwitch widget is in its on or off state.

Owner: GtkSwitch

Flags: Read / Write

Default value: FALSE


The “state” property

  “state”                    gboolean

The backend state that is controlled by the switch. See “state-set” for details.

Owner: GtkSwitch

Flags: Read / Write

Default value: FALSE

Signal Details

The “activate” signal

void
user_function (GtkSwitch *widget,
               gpointer   user_data)

The ::activate signal on GtkSwitch is an action signal and emitting it causes the switch to animate. Applications should never connect to this signal, but use the notify::active signal.

Parameters

widget

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “state-set” signal

gboolean
user_function (GtkSwitch *widget,
               gboolean   state,
               gpointer   user_data)

The ::state-set signal on GtkSwitch is emitted to change the underlying state. It is emitted when the user changes the switch position. The default handler keeps the state in sync with the “active” property.

To implement delayed state change, applications can connect to this signal, initiate the change of the underlying state, and call gtk_switch_set_state() when the underlying state change is complete. The signal handler should return TRUE to prevent the default handler from running.

Visually, the underlying state is represented by the trough color of the switch, while the “active” property is represented by the position of the switch.

Parameters

widget

the object on which the signal was emitted

 

state

the new state of the switch

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE to stop the signal emission

Flags: Run Last

See Also

GtkToggleButton