From 9bd9847b3f074f2ae5ef6ad96e5114e757615c20 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 1 May 2023 15:15:25 -0400 Subject: [PATCH] switch: Expand the docs Add more text and explanation around active vs state, since people seem easily confused by it. --- docs/reference/gtk/images/meson.build | 1 + docs/reference/gtk/images/switch-state.png | Bin 0 -> 3716 bytes docs/reference/gtk/images/switch-state.ui | 43 +++++++++++++++++++++ gtk/gtkswitch.c | 9 ++++- 4 files changed, 52 insertions(+), 1 deletion(-) create mode 100644 docs/reference/gtk/images/switch-state.png create mode 100644 docs/reference/gtk/images/switch-state.ui 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 0000000000000000000000000000000000000000..97a965b4ef22121d6d635f963116c3f26a76e267 GIT binary patch literal 3716 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 O+htQ5~Hq#cR? literal 0 HcmV?d00001 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 @@ + + + + 0 + 0 + 280 + 120 + + + + + + + vertical + 3 + 1 + 1 + center + center + + + 1 + 0 + + + + + 0 + 1 + + + + + + + + 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 * -- 2.30.2