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

int slider-height Read
int 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

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.

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

Since: 3.14

Style Property Details

The “slider-height” style property

  “slider-height”            int

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.

Owner: GtkSwitch

Flags: Read

Allowed values: >= 22

Default value: 22

Since: 3.18

The “slider-width” style property

  “slider-width”             int

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.

Owner: GtkSwitch

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

© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.
https://developer.gnome.org/gtk3/3.24/GtkSwitch.html