GtkSwitch: GTK+ 3 Reference Manual

## GtkSwitch GtkSwitch — A “light switch” style toggle |

## Functions

GtkWidget * | gtk_switch_new ()
void | gtk_switch_set_active ()
gboolean | gtk_switch_get_active ()
void | gtk_switch_set_state ()
gboolean | gtk_switch_get_state ()

## Properties

gboolean | active | Read / Write
gboolean | state | Read / Write

## Style Properties

gint | slider-height | Read
gint | slider-width | Read

## Signals

void | activate | Action
gboolean | state-set | Run Last

## Types and Values

struct | GtkSwitch
struct | GtkSwitchClass

## Object Hierarchy

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

## Implemented Interfaces

GtkSwitch implements AtkImplementorIface, GtkBuildable, GtkActionable and GtkActivatable.

## 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
    switch
    ╰── slider

GtkSwitch has two css nodes, the main node with the name switch and a subnode named slider. 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

Since: 3.0

### gtk_switch_set_active ()

    void
    gtk_switch_set_active (GtkSwitch *sw,
                           gboolean is_active);

Changes the state of `sw` to the desired one.

#### Parameters

sw | a GtkSwitch |
is_active | `TRUE` if `sw` should be active, and `FALSE` otherwise |

Since: 3.0

### gtk_switch_get_active ()

    gboolean
    gtk_switch_get_active (GtkSwitch *sw);

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

#### Parameters

sw | a GtkSwitch |

#### Returns

`TRUE` if the GtkSwitch is active, and `FALSE` otherwise

Since: 3.0

### gtk_switch_set_state ()

    void
    gtk_switch_set_state (GtkSwitch *sw,
                          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

sw | a GtkSwitch |
state | the new state |

Since: 3.14

### gtk_switch_get_state ()

    gboolean
    gtk_switch_get_state (GtkSwitch *sw);

Gets the underlying state of the GtkSwitch.

#### Parameters

sw | a GtkSwitch |

#### Returns

the underlying state

Since: 3.14

## Types and Values

### struct GtkSwitch

    struct GtkSwitch;

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

### struct GtkSwitchClass

    struct GtkSwitchClass {
      GtkWidgetClass parent_class;

      void (* activate) (GtkSwitch *sw);

      gboolean (* state_set) (GtkSwitch *sw, gboolean state);
    };

#### Members

`activate` () | An action signal and emitting it causes the switch to animate. |
`state_set` () | Class handler for the ::state-set signal. |

## Property Details

### The `“active”` property

      “active”                   gboolean

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

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.

Flags: Read / Write

Default value: FALSE

Since: 3.14

## Style Property Details

### The `“slider-height”` style property

      “slider-height”            gint

The minimum height of the GtkSwitch handle, in pixels.

`GtkSwitch:slider-height` has been deprecated since version 3.20 and should not be used in newly-written code.

Use the CSS min-height property instead.

Flags: Read

Allowed values: >= 22

Default value: 22

Since: 3.18

### The `“slider-width”` style property

      “slider-width”             gint

The minimum width of the GtkSwitch handle, in pixels.

`GtkSwitch:slider-width` has been deprecated since version 3.20 and should not be used in newly-written code.

Use the CSS min-width property instead.

Flags: Read

Allowed values: >= 36

Default value: 36

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

Since: 3.14

## See Also

GtkToggleButton