switch: Expand the docs

Add more text and explanation around active vs state,
since people seem easily confused by it.

diff --git a/docs/reference/gtk/images/meson.build b/docs/reference/gtk/images/meson.build
index d3bff0ce3fdef70209959a333a7e740e8fb6d946..9260583bf06c34e003d16af54d06c500ded3e027 100644 (file)
--- a/docs/reference/gtk/images/meson.build
+++ b/docs/reference/gtk/images/meson.build
@@ -68,6 +68,7 @@ ui_files = [
   'stackswitcher.ui',
   'statusbar.ui',
   'switch.ui',
+  'switch-state.ui',
   'toggle-button.ui',
   'video.ui',
   'volumebutton.ui',

diff --git a/docs/reference/gtk/images/switch-state.png b/docs/reference/gtk/images/switch-state.png
new file mode 100644 (file)
index 0000000..97a965b
Binary files /dev/null and b/docs/reference/gtk/images/switch-state.png differ

diff --git a/docs/reference/gtk/images/switch-state.ui b/docs/reference/gtk/images/switch-state.ui
new file mode 100644 (file)
index 0000000..e087058
--- /dev/null
+++ b/docs/reference/gtk/images/switch-state.ui
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+  <object class="GtkWindow">
+    <property name="decorated">0</property>
+    <property name="resizable">0</property>
+    <property name="default-width">280</property>
+    <property name="default-height">120</property>
+    <style>
+       <class name="nobackground"/>
+    </style>
+    <child>
+      <object class="GtkBox">
+        <style>
+          <class name="shadow"/>
+          <class name="background"/>
+          <class name="frame"/>
+        </style>
+        <child>
+          <object class="GtkBox">
+            <property name="orientation">vertical</property>
+            <property name="spacing">3</property>
+            <property name="hexpand">1</property>
+            <property name="vexpand">1</property>
+            <property name="halign">center</property>
+            <property name="valign">center</property>
+            <child>
+              <object class="GtkSwitch">
+                <property name="active">1</property>
+                <property name="state">0</property>
+              </object>
+            </child>
+            <child>
+              <object class="GtkSwitch">
+                <property name="active">0</property>
+                <property name="state">1</property>
+              </object>
+            </child>
+          </object>
+        </child>
+      </object>
+    </child>
+  </object>
+</interface>

diff --git a/gtk/gtkswitch.c b/gtk/gtkswitch.c
index 31d2d234f5daa8b1169d6b819338d426108038b2..7193d8b7c531889875dfc3bb5bde74e58079aa10 100644 (file)
--- a/gtk/gtkswitch.c
+++ b/gtk/gtkswitch.c
@@ -34,7 +34,14 @@
  * empty area, or by dragging the handle.
  *
  * `GtkSwitch` can also handle situations where the underlying state
- * changes with a delay. See [signal@Gtk.Switch::state-set] for details.
+ * changes with a delay. In this case, the slider position indicates
+ * the user's recent change (as indicated by the [property@Gtk.Switch:active]
+ * property), and the color indicates whether the underlying state (represented
+ * by the [property@Gtk.Switch:state] property) has been updated yet.
+ *
+ * ![GtkSwitch with delayed state change](switch-state.png)
+ *
+ * See [signal@Gtk.Switch::state-set] for details.
  *
  * # CSS nodes
  *