<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
<!ENTITY pi "&#960;">
<!ENTITY solidus "&#8260;">
]>
<refentry id="GtkSwitch">
<refmeta>
<refentrytitle role="top_of_page" id="GtkSwitch.top_of_page">GtkSwitch</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GtkSwitch</refname>
<refpurpose>A “light switch” style toggle</refpurpose>
</refnamediv>

<refsect1 id="GtkSwitch.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="GtkWidget"><returnvalue>GtkWidget</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-switch-new">gtk_switch_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-switch-set-active">gtk_switch_set_active</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-switch-get-active">gtk_switch_get_active</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-switch-set-state">gtk_switch_set_state</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-switch-get-state">gtk_switch_get_state</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkSwitch.properties" role="properties">
<title role="properties.title">Properties</title>
<informaltable frame="none">
<tgroup cols="3">
<colspec colname="properties_type" colwidth="150px"/>
<colspec colname="properties_name" colwidth="300px"/>
<colspec colname="properties_flags" colwidth="200px"/>
<tbody>
<row><entry role="property_type"><link linkend="gboolean"><type>gboolean</type></link></entry><entry role="property_name"><link linkend="GtkSwitch--active">active</link></entry><entry role="property_flags">Read / Write</entry></row>
<row><entry role="property_type"><link linkend="gboolean"><type>gboolean</type></link></entry><entry role="property_name"><link linkend="GtkSwitch--state">state</link></entry><entry role="property_flags">Read / Write</entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkSwitch.signals" role="signal_proto">
<title role="signal_proto.title">Signals</title>
<informaltable frame="none">
<tgroup cols="3">
<colspec colname="signal_proto_type" colwidth="150px"/>
<colspec colname="signal_proto_name" colwidth="300px"/>
<colspec colname="signal_proto_flags" colwidth="200px"/>
<tbody>
<row><entry role="signal_type"><link linkend="void"><returnvalue>void</returnvalue></link></entry><entry role="signal_name"><link linkend="GtkSwitch-activate">activate</link></entry><entry role="signal_flags"><link linkend="G-SIGNAL-ACTION:CAPS">Action</link></entry></row>
<row><entry role="signal_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link></entry><entry role="signal_name"><link linkend="GtkSwitch-state-set">state-set</link></entry><entry role="signal_flags"><link linkend="G-SIGNAL-RUN-LAST:CAPS">Run Last</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkSwitch.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GtkSwitch-struct">GtkSwitch</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkSwitch.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>    <link linkend="GObject">GObject</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> <link linkend="GInitiallyUnowned">GInitiallyUnowned</link>
        <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> <link linkend="GtkWidget">GtkWidget</link>
            <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GtkSwitch
</screen>
</refsect1>
<refsect1 id="GtkSwitch.implemented-interfaces" role="impl_interfaces">
<title role="impl_interfaces.title">Implemented Interfaces</title>
<para>
GtkSwitch implements
 <link linkend="AtkImplementorIface">AtkImplementorIface</link>,  <link linkend="GtkBuildable">GtkBuildable</link>,  <link linkend="GtkConstraintTarget">GtkConstraintTarget</link> and  <link linkend="GtkActionable">GtkActionable</link>.</para>

</refsect1>

<refsect1 id="GtkSwitch.includes"><title>Includes</title><synopsis>#include &lt;gtk/gtk.h&gt;
</synopsis></refsect1>

<refsect1 id="GtkSwitch.description" role="desc">
<title role="desc.title">Description</title>
<para><link linkend="GtkSwitch"><type>GtkSwitch</type></link> 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.</para>
<para>GtkSwitch can also handle situations where the underlying state changes with
a delay. See <link linkend="GtkSwitch-state-set"><type>“state-set”</type></link> for details.</para>
<refsect2><title>CSS nodes</title><informalexample><programlisting role="example"><![CDATA[
switch
├── label
├── label
╰── slider
]]></programlisting></informalexample>
<para></para>
<para>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.</para>
</refsect2>

</refsect1>
<refsect1 id="GtkSwitch.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gtk-switch-new" role="function">
<title>gtk_switch_new&#160;()</title>
<indexterm zone="gtk-switch-new"><primary>gtk_switch_new</primary></indexterm>
<programlisting language="C"><link linkend="GtkWidget"><returnvalue>GtkWidget</returnvalue></link>&#160;*
gtk_switch_new (<parameter><type>void</type></parameter>);</programlisting>
<para>Creates a new <link linkend="GtkSwitch"><type>GtkSwitch</type></link> widget.</para>
<refsect3 id="gtk-switch-new.returns" role="returns">
<title>Returns</title>
<para> the newly created <link linkend="GtkSwitch"><type>GtkSwitch</type></link> instance</para>
</refsect3></refsect2>
<refsect2 id="gtk-switch-set-active" role="function">
<title>gtk_switch_set_active&#160;()</title>
<indexterm zone="gtk-switch-set-active"><primary>gtk_switch_set_active</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_switch_set_active (<parameter><link linkend="GtkSwitch"><type>GtkSwitch</type></link> *self</parameter>,
                       <parameter><link linkend="gboolean"><type>gboolean</type></link> is_active</parameter>);</programlisting>
<para>Changes the state of <parameter>self</parameter>
 to the desired one.</para>
<refsect3 id="gtk-switch-set-active.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>self</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkSwitch"><type>GtkSwitch</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>is_active</para></entry>
<entry role="parameter_description"><para><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>self</parameter>
should be active, and <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-switch-get-active" role="function">
<title>gtk_switch_get_active&#160;()</title>
<indexterm zone="gtk-switch-get-active"><primary>gtk_switch_get_active</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_switch_get_active (<parameter><link linkend="GtkSwitch"><type>GtkSwitch</type></link> *self</parameter>);</programlisting>
<para>Gets whether the <link linkend="GtkSwitch"><type>GtkSwitch</type></link> is in its “on” or “off” state.</para>
<refsect3 id="gtk-switch-get-active.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>self</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkSwitch"><type>GtkSwitch</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-switch-get-active.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the <link linkend="GtkSwitch"><type>GtkSwitch</type></link> is active, and <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise</para>
</refsect3></refsect2>
<refsect2 id="gtk-switch-set-state" role="function">
<title>gtk_switch_set_state&#160;()</title>
<indexterm zone="gtk-switch-set-state"><primary>gtk_switch_set_state</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_switch_set_state (<parameter><link linkend="GtkSwitch"><type>GtkSwitch</type></link> *self</parameter>,
                      <parameter><link linkend="gboolean"><type>gboolean</type></link> state</parameter>);</programlisting>
<para>Sets the underlying state of the <link linkend="GtkSwitch"><type>GtkSwitch</type></link>.</para>
<para>Normally, this is the same as <link linkend="GtkSwitch--active"><type>“active”</type></link>, unless the switch
is set up for delayed state changes. This function is typically
called from a <link linkend="GtkSwitch-state-set"><type>“state-set”</type></link> signal handler.</para>
<para>See <link linkend="GtkSwitch-state-set"><type>“state-set”</type></link> for details.</para>
<refsect3 id="gtk-switch-set-state.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>self</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkSwitch"><type>GtkSwitch</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>state</para></entry>
<entry role="parameter_description"><para>the new state</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-switch-get-state" role="function">
<title>gtk_switch_get_state&#160;()</title>
<indexterm zone="gtk-switch-get-state"><primary>gtk_switch_get_state</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_switch_get_state (<parameter><link linkend="GtkSwitch"><type>GtkSwitch</type></link> *self</parameter>);</programlisting>
<para>Gets the underlying state of the <link linkend="GtkSwitch"><type>GtkSwitch</type></link>.</para>
<refsect3 id="gtk-switch-get-state.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>self</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkSwitch"><type>GtkSwitch</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-switch-get-state.returns" role="returns">
<title>Returns</title>
<para> the underlying state</para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GtkSwitch.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GtkSwitch-struct" role="struct">
<title>GtkSwitch</title>
<indexterm zone="GtkSwitch-struct"><primary>GtkSwitch</primary></indexterm>
<programlisting language="C">typedef struct _GtkSwitch GtkSwitch;</programlisting>
<para>The <link linkend="GtkSwitch-struct"><type>GtkSwitch</type></link> contains private
data and it should only be accessed using the provided API.</para>
</refsect2>

</refsect1>
<refsect1 id="GtkSwitch.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="GtkSwitch--active" role="property"><title>The <literal>“active”</literal> property</title>
<indexterm zone="GtkSwitch--active"><primary>GtkSwitch:active</primary></indexterm>
<programlisting>  “active”                   <link linkend="gboolean"><type>gboolean</type></link></programlisting>
<para>Whether the <link linkend="GtkSwitch"><type>GtkSwitch</type></link> widget is in its on or off state.</para>
<para>Owner: GtkSwitch</para>
<para>Flags: Read / Write</para>
<para>Default value: FALSE</para>
</refsect2>
<refsect2 id="GtkSwitch--state" role="property"><title>The <literal>“state”</literal> property</title>
<indexterm zone="GtkSwitch--state"><primary>GtkSwitch:state</primary></indexterm>
<programlisting>  “state”                    <link linkend="gboolean"><type>gboolean</type></link></programlisting>
<para>The backend state that is controlled by the switch.

See <link linkend="GtkSwitch-state-set"><type>“state-set”</type></link> for details.</para>
<para>Owner: GtkSwitch</para>
<para>Flags: Read / Write</para>
<para>Default value: FALSE</para>
</refsect2>

</refsect1>
<refsect1 id="GtkSwitch.signal-details" role="signals">
<title role="signals.title">Signal Details</title>
<refsect2 id="GtkSwitch-activate" role="signal"><title>The <literal>“activate”</literal> signal</title>
<indexterm zone="GtkSwitch-activate"><primary>GtkSwitch::activate</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
user_function (<link linkend="GtkSwitch"><type>GtkSwitch</type></link> *widget,
               <link linkend="gpointer"><type>gpointer</type></link>   user_data)</programlisting>
<para>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.</para>
<refsect3 id="GtkSwitch-activate.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>widget</para></entry>
<entry role="parameter_description"><para>the object which received the signal.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><simpara>user_data</simpara></entry>
<entry role="parameter_description"><simpara>user data set when the signal handler was connected.</simpara></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para>Flags: <link linkend="G-SIGNAL-ACTION:CAPS">Action</link></para>
</refsect2><refsect2 id="GtkSwitch-state-set" role="signal"><title>The <literal>“state-set”</literal> signal</title>
<indexterm zone="GtkSwitch-state-set"><primary>GtkSwitch::state-set</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
user_function (<link linkend="GtkSwitch"><type>GtkSwitch</type></link> *widget,
               <link linkend="gboolean"><type>gboolean</type></link>   state,
               <link linkend="gpointer"><type>gpointer</type></link>   user_data)</programlisting>
<para>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 <link linkend="GtkSwitch--active"><type>“active”</type></link>
property.</para>
<para>To implement delayed state change, applications can connect to this signal,
initiate the change of the underlying state, and call <link linkend="gtk-switch-set-state"><function>gtk_switch_set_state()</function></link>
when the underlying state change is complete. The signal handler should
return <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> to prevent the default handler from running.</para>
<para>Visually, the underlying state is represented by the trough color of
the switch, while the <link linkend="GtkSwitch--active"><type>“active”</type></link> property is represented by the
position of the switch.</para>
<refsect3 id="GtkSwitch-state-set.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>widget</para></entry>
<entry role="parameter_description"><para>the object on which the signal was emitted</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>state</para></entry>
<entry role="parameter_description"><para>the new state of the switch</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><simpara>user_data</simpara></entry>
<entry role="parameter_description"><simpara>user data set when the signal handler was connected.</simpara></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="GtkSwitch-state-set.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> to stop the signal emission</para>
</refsect3><para>Flags: <link linkend="G-SIGNAL-RUN-LAST:CAPS">Run Last</link></para>
</refsect2>
</refsect1>
<refsect1 id="GtkSwitch.see-also">
<title>See Also</title>
<para><link linkend="GtkToggleButton"><type>GtkToggleButton</type></link></para>

</refsect1>

</refentry>
