[gtk/ebassi/gidocgen: 79/465] appchooserbutton: Convert docs
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk/ebassi/gidocgen: 79/465] appchooserbutton: Convert docs
- Date: Mon, 8 Mar 2021 22:26:02 +0000 (UTC)
commit b4ed3e6c5abe30648a6ee0a54199d4201ae6dd61
Author: Matthias Clasen <mclasen redhat com>
Date: Sun Feb 21 19:41:33 2021 -0500
appchooserbutton: Convert docs
Change link syntax, add an example image, generally clean things up.
gtk/gtkappchooserbutton.c | 121 +++++++++++++++++++++++++---------------------
1 file changed, 65 insertions(+), 56 deletions(-)
---
diff --git a/gtk/gtkappchooserbutton.c b/gtk/gtkappchooserbutton.c
index bc7bbb6876..e8f2c531de 100644
--- a/gtk/gtkappchooserbutton.c
+++ b/gtk/gtkappchooserbutton.c
@@ -19,36 +19,35 @@
*/
/**
- * SECTION:gtkappchooserbutton
- * @Title: GtkAppChooserButton
- * @Short_description: A button to launch an application chooser dialog
+ * GtkAppChooserButton:
*
- * The #GtkAppChooserButton is a widget that lets the user select
- * an application. It implements the #GtkAppChooser interface.
+ * The `GtkAppChooserButton` lets the user select an application.
*
- * Initially, a #GtkAppChooserButton selects the first application
+ * ![An example GtkAppChooserButton](appchooserbutton.png)
+ *
+ * Initially, a `GtkAppChooserButton` selects the first application
* in its list, which will either be the most-recently used application
- * or, if #GtkAppChooserButton:show-default-item is %TRUE, the
+ * or, if [property@Gtk.AppChooserButton:show-default-item] is %TRUE, the
* default application.
*
- * The list of applications shown in a #GtkAppChooserButton includes
+ * The list of applications shown in a `GtkAppChooserButton` includes
* the recommended applications for the given content type. When
- * #GtkAppChooserButton:show-default-item is set, the default application
- * is also included. To let the user chooser other applications,
- * you can set the #GtkAppChooserButton:show-dialog-item property,
- * which allows to open a full #GtkAppChooserDialog.
+ * [property@Gtk.AppChooserButton:show-default-item] is set, the default
+ * application is also included. To let the user chooser other applications,
+ * you can set the [property@Gtk.AppChooserButton:show-dialog-item] property,
+ * which allows to open a full [class@Gtk.AppChooserDialog].
*
* It is possible to add custom items to the list, using
- * gtk_app_chooser_button_append_custom_item(). These items cause
- * the #GtkAppChooserButton::custom-item-activated signal to be
+ * [method@Gtk.AppChooserButton.append_custom_item]. These items cause
+ * the [signal@Gtk.AppChooserButton::custom-item-activated] signal to be
* emitted when they are selected.
*
* To track changes in the selected application, use the
- * #GtkAppChooserButton::changed signal.
+ * [signal@Gtk.AppChooserButton::changed] signal.
*
* # CSS nodes
*
- * GtkAppChooserButton has a single CSS node with the name “appchooserbutton”.
+ * `GtkAppChooserButton` has a single CSS node with the name “appchooserbutton”.
*/
#include "config.h"
@@ -669,9 +668,8 @@ gtk_app_chooser_button_class_init (GtkAppChooserButtonClass *klass)
/**
* GtkAppChooserButton:show-dialog-item:
*
- * The #GtkAppChooserButton:show-dialog-item property determines
- * whether the dropdown menu should show an item that triggers
- * a #GtkAppChooserDialog when clicked.
+ * Determines whether the dropdown menu shows an item to open
+ * a `GtkAppChooserDialog`.
*/
properties[PROP_SHOW_DIALOG_ITEM] =
g_param_spec_boolean ("show-dialog-item",
@@ -683,8 +681,7 @@ gtk_app_chooser_button_class_init (GtkAppChooserButtonClass *klass)
/**
* GtkAppChooserButton:show-default-item:
*
- * The #GtkAppChooserButton:show-default-item property determines
- * whether the dropdown menu should show the default application
+ * Determines whether the dropdown menu shows the default application
* on top for the provided content type.
*/
properties[PROP_SHOW_DEFAULT_ITEM] =
@@ -698,7 +695,9 @@ gtk_app_chooser_button_class_init (GtkAppChooserButtonClass *klass)
* GtkAppChooserButton:heading:
*
* The text to show at the top of the dialog that can be
- * opened from the button. The string may contain Pango markup.
+ * opened from the button.
+ *
+ * The string may contain Pango markup.
*/
properties[PROP_HEADING] =
g_param_spec_string ("heading",
@@ -707,6 +706,11 @@ gtk_app_chooser_button_class_init (GtkAppChooserButtonClass *klass)
NULL,
G_PARAM_READWRITE|G_PARAM_STATIC_STRINGS|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkAppChooserButton:modal:
+ *
+ * Whether the app chooser dialog should be modal.
+ */
properties[PROP_MODAL] =
g_param_spec_boolean ("modal",
P_("Modal"),
@@ -719,8 +723,7 @@ gtk_app_chooser_button_class_init (GtkAppChooserButtonClass *klass)
* GtkAppChooserButton::changed:
* @self: the object which received the signal
*
- * Emitted when the active application on the #GtkAppChooserButton
- * changes.
+ * Emitted when the active application changes.
*/
signals[SIGNAL_CHANGED] =
g_signal_new (I_("changed"),
@@ -737,9 +740,10 @@ gtk_app_chooser_button_class_init (GtkAppChooserButtonClass *klass)
* @self: the object which received the signal
* @item_name: the name of the activated item
*
- * Emitted when a custom item, previously added with
- * gtk_app_chooser_button_append_custom_item(), is activated from the
- * dropdown menu.
+ * Emitted when a custom item is activated.
+ *
+ * Use [method@Gtk.AppChooserButton.append_custom_item],
+ * to add custom items.
*/
signals[SIGNAL_CUSTOM_ITEM_ACTIVATED] =
g_signal_new (I_("custom-item-activated"),
@@ -850,10 +854,10 @@ real_insert_separator (GtkAppChooserButton *self,
* gtk_app_chooser_button_new:
* @content_type: the content type to show applications for
*
- * Creates a new #GtkAppChooserButton for applications
+ * Creates a new `GtkAppChooserButton` for applications
* that can handle content of the given type.
*
- * Returns: a newly created #GtkAppChooserButton
+ * Returns: a newly created `GtkAppChooserButton`
*/
GtkWidget *
gtk_app_chooser_button_new (const char *content_type)
@@ -867,7 +871,7 @@ gtk_app_chooser_button_new (const char *content_type)
/**
* gtk_app_chooser_button_append_separator:
- * @self: a #GtkAppChooserButton
+ * @self: a `GtkAppChooserButton`
*
* Appends a separator to the list of applications that is shown
* in the popup.
@@ -885,17 +889,20 @@ gtk_app_chooser_button_append_separator (GtkAppChooserButton *self)
/**
* gtk_app_chooser_button_append_custom_item:
- * @self: a #GtkAppChooserButton
+ * @self: a `GtkAppChooserButton`
* @name: the name of the custom item
* @label: the label for the custom item
* @icon: the icon for the custom item
*
* Appends a custom item to the list of applications that is shown
- * in the popup; the item name must be unique per-widget.
- * Clients can use the provided name as a detail for the
- * #GtkAppChooserButton::custom-item-activated signal, to add a
+ * in the popup.
+ *
+ * The item name must be unique per-widget. Clients can use the
+ * provided name as a detail for the
+ * [signal@GtkAppChooserButton::custom-item-activated] signal, to add a
* callback for the activation of a particular custom item in the list.
- * See also gtk_app_chooser_button_append_separator().
+ *
+ * See also [method@Gtk.AppChooserButton.append_separator].
*/
void
gtk_app_chooser_button_append_custom_item (GtkAppChooserButton *self,
@@ -914,13 +921,14 @@ gtk_app_chooser_button_append_custom_item (GtkAppChooserButton *self,
/**
* gtk_app_chooser_button_set_active_custom_item:
- * @self: a #GtkAppChooserButton
+ * @self: a `GtkAppChooserButton`
* @name: the name of the custom item
*
- * Selects a custom item previously added with
- * gtk_app_chooser_button_append_custom_item().
+ * Selects a custom item.
*
- * Use gtk_app_chooser_refresh() to bring the selection
+ * See [method@Gtk.AppChooserButton.append_custom_item].
+ *
+ * Use [method@Gtk.AppChooser.refresh] to bring the selection
* to its initial state.
*/
void
@@ -944,12 +952,12 @@ gtk_app_chooser_button_set_active_custom_item (GtkAppChooserButton *self,
/**
* gtk_app_chooser_button_get_show_dialog_item:
- * @self: a #GtkAppChooserButton
+ * @self: a `GtkAppChooserButton`
*
- * Returns the current value of the #GtkAppChooserButton:show-dialog-item
- * property.
+ * Returns whether the dropdown menu shows an item
+ * for a `GtkAppChooserDialog`.
*
- * Returns: the value of #GtkAppChooserButton:show-dialog-item
+ * Returns: the value of [property@Gtk.AppChooserButton:show-dialog-item]
*/
gboolean
gtk_app_chooser_button_get_show_dialog_item (GtkAppChooserButton *self)
@@ -961,11 +969,11 @@ gtk_app_chooser_button_get_show_dialog_item (GtkAppChooserButton *self)
/**
* gtk_app_chooser_button_set_show_dialog_item:
- * @self: a #GtkAppChooserButton
- * @setting: the new value for #GtkAppChooserButton:show-dialog-item
+ * @self: a `GtkAppChooserButton`
+ * @setting: the new value for [property@Gtk.AppChooserButton:show-dialog-item]
*
* Sets whether the dropdown menu of this button should show an
- * entry to trigger a #GtkAppChooserDialog.
+ * entry to trigger a `GtkAppChooserDialog`.
*/
void
gtk_app_chooser_button_set_show_dialog_item (GtkAppChooserButton *self,
@@ -983,12 +991,12 @@ gtk_app_chooser_button_set_show_dialog_item (GtkAppChooserButton *self,
/**
* gtk_app_chooser_button_get_show_default_item:
- * @self: a #GtkAppChooserButton
+ * @self: a `GtkAppChooserButton`
*
- * Returns the current value of the #GtkAppChooserButton:show-default-item
- * property.
+ * Returns whether the dropdown menu should show the default
+ * application at the top.
*
- * Returns: the value of #GtkAppChooserButton:show-default-item
+ * Returns: the value of [property@Gtk.AppChooserButton:show-default-item]
*/
gboolean
gtk_app_chooser_button_get_show_default_item (GtkAppChooserButton *self)
@@ -1000,8 +1008,8 @@ gtk_app_chooser_button_get_show_default_item (GtkAppChooserButton *self)
/**
* gtk_app_chooser_button_set_show_default_item:
- * @self: a #GtkAppChooserButton
- * @setting: the new value for #GtkAppChooserButton:show-default-item
+ * @self: a `GtkAppChooserButton`
+ * @setting: the new value for [property@Gtk.AppChooserButton:show-default-item]
*
* Sets whether the dropdown menu of this button should show the
* default application for the given content type at top.
@@ -1024,10 +1032,11 @@ gtk_app_chooser_button_set_show_default_item (GtkAppChooserButton *self,
/**
* gtk_app_chooser_button_set_heading:
- * @self: a #GtkAppChooserButton
+ * @self: a `GtkAppChooserButton`
* @heading: a string containing Pango markup
*
* Sets the text to display at the top of the dialog.
+ *
* If the heading is not set, the dialog displays a default text.
*/
void
@@ -1044,7 +1053,7 @@ gtk_app_chooser_button_set_heading (GtkAppChooserButton *self,
/**
* gtk_app_chooser_button_get_heading:
- * @self: a #GtkAppChooserButton
+ * @self: a `GtkAppChooserButton`
*
* Returns the text to display at the top of the dialog.
*
@@ -1061,7 +1070,7 @@ gtk_app_chooser_button_get_heading (GtkAppChooserButton *self)
/**
* gtk_app_chooser_button_set_modal:
- * @self: a #GtkAppChooserButton
+ * @self: a `GtkAppChooserButton`
* @modal: %TRUE to make the dialog modal
*
* Sets whether the dialog should be modal.
@@ -1082,7 +1091,7 @@ gtk_app_chooser_button_set_modal (GtkAppChooserButton *self,
/**
* gtk_app_chooser_button_get_modal:
- * @self: a #GtkAppChooserButton
+ * @self: a `GtkAppChooserButton`
*
* Gets whether the dialog is modal.
*
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]