From: Matthias Clasen <mclasen@redhat.com>
Date: Mon, 1 May 2023 19:15:25 +0000 (-0400)
Subject: switch: Expand the docs
X-Git-Tag: archive/raspbian/4.12.3+ds-1+rpi1~1^2^2^2~22^2~1^2~325^2
X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=9bd9847b3f074f2ae5ef6ad96e5114e757615c20;p=gtk4.git

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 d3bff0ce3f..9260583bf0 100644
--- 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
index 0000000000..97a965b4ef
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
index 0000000000..e087058e87
--- /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 31d2d234f5..7193d8b7c5 100644
--- 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
  *