[gtk/ebassi/gidocgen: 84/465] switch: Convert docs
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk/ebassi/gidocgen: 84/465] switch: Convert docs
- Date: Mon, 8 Mar 2021 22:26:02 +0000 (UTC)
commit 158c00e77019ce20975249ccdbdf374858ee0200
Author: Matthias Clasen <mclasen redhat com>
Date: Sun Feb 21 19:43:19 2021 -0500
switch: Convert docs
Change link syntax, add an example image, generally clean things up.
gtk/gtkswitch.c | 98 ++++++++++++++++++++++++++++-----------------------------
1 file changed, 48 insertions(+), 50 deletions(-)
---
diff --git a/gtk/gtkswitch.c b/gtk/gtkswitch.c
index d7a8e3a44b..61ba44dc62 100644
--- a/gtk/gtkswitch.c
+++ b/gtk/gtkswitch.c
@@ -24,17 +24,17 @@
*/
/**
- * SECTION:gtkswitch
- * @Short_Description: A “light switch” style toggle
- * @Title: GtkSwitch
- * @See_Also: #GtkToggleButton
+ * GtkSwitch:
+ *
+ * `GtkSwitch` is a "light switch" that has two states: on or off.
+ *
+ * ![An example GtkSwitch](switch.png)
*
- * #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.
+ * 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 #GtkSwitch::state-set for details.
+ * `GtkSwitch` can also handle situations where the underlying state
+ * changes with a delay. See [signal@GtkSwitch::state-set] for details.
*
* # CSS nodes
*
@@ -45,12 +45,13 @@
* ╰── slider
* ]|
*
- * 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.
+ * `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.
*
* # Accessibility
*
- * GtkSwitch uses the #GTK_ACCESSIBLE_ROLE_SWITCH role.
+ * `GtkSwitch` uses the #GTK_ACCESSIBLE_ROLE_SWITCH role.
*/
#include "config.h"
@@ -74,12 +75,6 @@
typedef struct _GtkSwitchClass GtkSwitchClass;
-/**
- * GtkSwitch:
- *
- * The #GtkSwitch-struct contains private
- * data and it should only be accessed using the provided API.
- */
struct _GtkSwitch
{
GtkWidget parent_instance;
@@ -520,7 +515,7 @@ gtk_switch_class_init (GtkSwitchClass *klass)
/**
* GtkSwitch:active:
*
- * Whether the #GtkSwitch widget is in its on or off state.
+ * Whether the `GtkSwitch` widget is in its on or off state.
*/
switch_props[PROP_ACTIVE] =
g_param_spec_boolean ("active",
@@ -532,8 +527,9 @@ gtk_switch_class_init (GtkSwitchClass *klass)
/**
* GtkSwitch:state:
*
- * The backend state that is controlled by the switch.
- * See #GtkSwitch::state-set for details.
+ * The backend state that is controlled by the switch.
+ *
+ * See [signal@GtkSwitch::state-set] for details.
*/
switch_props[PROP_STATE] =
g_param_spec_boolean ("state",
@@ -554,12 +550,12 @@ gtk_switch_class_init (GtkSwitchClass *klass)
/**
* GtkSwitch::activate:
- * @widget: the object which received the signal.
+ * @widget: the object which received the signal
*
- * 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.
+ * Emitted to animate the switch.
+ *
+ * Applications should never connect to this signal,
+ * but use the [property@Gtk.Switch:active] property.
*/
signals[ACTIVATE] =
g_signal_new (I_("activate"),
@@ -577,19 +573,21 @@ gtk_switch_class_init (GtkSwitchClass *klass)
* @widget: the object on which the signal was emitted
* @state: the new state of the switch
*
- * 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 #GtkSwitch:active
- * property.
+ * Emitted to change the underlying state.
+ *
+ * The ::state-set signal is emitted when the user changes the switch
+ * position. The default handler keeps the state in sync with the
+ * [property@Gtk.Switch: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.
+ * To implement delayed state change, applications can connect to this
+ * signal, initiate the change of the underlying state, and call
+ * [method@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 #GtkSwitch:active property is represented by the
- * position of the switch.
+ * the switch, while the [property@Gtk.Switch`:active] property is
+ * represented by the position of the switch.
*
* Returns: %TRUE to stop the signal emission
*/
@@ -676,9 +674,9 @@ gtk_switch_init (GtkSwitch *self)
/**
* gtk_switch_new:
*
- * Creates a new #GtkSwitch widget.
+ * Creates a new `GtkSwitch` widget.
*
- * Returns: the newly created #GtkSwitch instance
+ * Returns: the newly created `GtkSwitch` instance
*/
GtkWidget *
gtk_switch_new (void)
@@ -688,7 +686,7 @@ gtk_switch_new (void)
/**
* gtk_switch_set_active:
- * @self: a #GtkSwitch
+ * @self: a `GtkSwitch`
* @is_active: %TRUE if @self should be active, and %FALSE otherwise
*
* Changes the state of @self to the desired one.
@@ -728,11 +726,11 @@ gtk_switch_set_active (GtkSwitch *self,
/**
* gtk_switch_get_active:
- * @self: a #GtkSwitch
+ * @self: a `GtkSwitch`
*
- * Gets whether the #GtkSwitch is in its “on” or “off” state.
+ * Gets whether the `GtkSwitch` is in its “on” or “off” state.
*
- * Returns: %TRUE if the #GtkSwitch is active, and %FALSE otherwise
+ * Returns: %TRUE if the `GtkSwitch` is active, and %FALSE otherwise
*/
gboolean
gtk_switch_get_active (GtkSwitch *self)
@@ -744,16 +742,16 @@ gtk_switch_get_active (GtkSwitch *self)
/**
* gtk_switch_set_state:
- * @self: a #GtkSwitch
+ * @self: a `GtkSwitch`
* @state: the new state
*
- * Sets the underlying state of the #GtkSwitch.
+ * Sets the underlying state of the `GtkSwitch`.
*
- * Normally, this is the same as #GtkSwitch:active, unless the switch
- * is set up for delayed state changes. This function is typically
- * called from a #GtkSwitch::state-set signal handler.
+ * Normally, this is the same as [property@Gtk.Switch:active], unless
+ * the switch is set up for delayed state changes. This function is
+ * typically called from a [signal@Gtk.Switch`::state-set] signal handler.
*
- * See #GtkSwitch::state-set for details.
+ * See [signal@Gtk.Switch::state-set] for details.
*/
void
gtk_switch_set_state (GtkSwitch *self,
@@ -784,9 +782,9 @@ gtk_switch_set_state (GtkSwitch *self,
/**
* gtk_switch_get_state:
- * @self: a #GtkSwitch
+ * @self: a `GtkSwitch`
*
- * Gets the underlying state of the #GtkSwitch.
+ * Gets the underlying state of the `GtkSwitch`.
*
* Returns: the underlying state
*/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]