GNOME.org
 

[gtk/ebassi/gidocgen: 421/483] filechooserwidget: Convert docs


commit 4c281b5b0c55b70f0a4fb552efbef93cad790cb7
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Mar 1 08:17:29 2021 -0500

    filechooserwidget: Convert docs

 gtk/gtkfilechooserwidget.c | 156 +++++++++++++++++++++++++--------------------
 1 file changed, 86 insertions(+), 70 deletions(-)
---
diff --git a/gtk/gtkfilechooserwidget.c b/gtk/gtkfilechooserwidget.c
index 5674d3cbda..f6a58f3218 100644
--- a/gtk/gtkfilechooserwidget.c
+++ b/gtk/gtkfilechooserwidget.c
@@ -98,19 +98,17 @@
 #endif
 
 /**
- * SECTION:gtkfilechooserwidget
- * @Short_description: A file chooser widget
- * @Title: GtkFileChooserWidget
- * @See_also: #GtkFileChooserDialog
+ * GtkFileChooserWidget:
  *
- * #GtkFileChooserWidget is a widget for choosing files.
- * It exposes the #GtkFileChooser interface, and you should
+ * `GtkFileChooserWidget` is a widget for choosing files.
+ *
+ * It exposes the [iface@Gtk.FileChooser] interface, and you should
  * use the methods of this interface to interact with the
  * widget.
  *
  * # CSS nodes
  *
- * GtkFileChooserWidget has a single CSS node with name filechooser.
+ * `GtkFileChooserWidget` has a single CSS node with name filechooser.
  */
 
 /* 150 mseconds of delay */
@@ -7265,17 +7263,19 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * @widget: the object which received the signal
    * @path: a string that gets put in the text entry for the file name
    *
-   * The ::location-popup signal is a [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user asks for it.
+   * Emitted when the user asks for it.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
    *
    * This is used to make the file chooser show a "Location" prompt which
    * the user can use to manually type the name of the file he wishes to select.
    *
-   * The default bindings for this signal are `Control + L` with a @path string
-   * of "" (the empty string).  It is also bound to `/` with a @path string of
-   * "`/`" (a slash):  this lets you type `/` and immediately type a path name.
-   * On Unix systems, this is bound to `~` (tilde) with a @path string of "~"
-   * itself for access to home directories.
+   * The default bindings for this signal are <kbd>Control</kbd>-<kbd>L</kbd>
+   * with a @path string of "" (the empty string). It is also bound to
+   * <kbd>/</kbd> with a @path string of "`/`" (a slash):  this lets you
+   * type `/` and immediately type a path name. On Unix systems, this is
+   * bound to <kbd>~</kbd> (tilde) with a @path string of "~" itself for
+   * access to home directories.
    */
   signals[LOCATION_POPUP] =
     g_signal_new_class_handler (I_("location-popup"),
@@ -7290,13 +7290,14 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * GtkFileChooserWidget::location-popup-on-paste:
    * @widget: the object which received the signal
    *
-   * The ::location-popup-on-paste signal is a [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user asks for it.
+   * Emitted when the user asks for it.
    *
-   * This is used to make the file chooser show a "Location" prompt when the user
-   * pastes into a #GtkFileChooserWidget.
+   * This is a [keybinding signal](class.SignalAction.html).
    *
-   * The default binding for this signal is `Control + V`.
+   * This is used to make the file chooser show a "Location" prompt
+   * when the user pastes into a `GtkFileChooserWidget`.
+   *
+   * The default binding for this signal is <kbd>Control</kbd>-<kbd>V</kbd>.
    */
   signals[LOCATION_POPUP_ON_PASTE] =
     g_signal_new_class_handler (I_("location-popup-on-paste"),
@@ -7311,13 +7312,15 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * GtkFileChooserWidget::location-toggle-popup:
    * @widget: the object which received the signal
    *
-   * The ::location-toggle-popup signal is a [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user asks for it.
+   * Emitted when the user asks for it.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
    *
-   * This is used to toggle the visibility of a "Location" prompt which the user
-   * can use to manually type the name of the file he wishes to select.
+   * This is used to toggle the visibility of a "Location" prompt
+   * which the user can use to manually type the name of the file
+   * he wishes to select.
    *
-   * The default binding for this signal is `Control + L`.
+   * The default binding for this signal is <kbd>Control</kbd>-<kbd>L</kbd>.
    */
   signals[LOCATION_TOGGLE_POPUP] =
     g_signal_new_class_handler (I_("location-toggle-popup"),
@@ -7332,13 +7335,14 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * GtkFileChooserWidget::up-folder:
    * @widget: the object which received the signal
    *
-   * The ::up-folder signal is a [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user asks for it.
+   * Emitted when the user asks for it.
    *
-   * This is used to make the file chooser go to the parent of the current folder
-   * in the file hierarchy.
+   * This is a [keybinding signal](class.SignalAction.html).
    *
-   * The default binding for this signal is `Alt + Up`.
+   * This is used to make the file chooser go to the parent
+   * of the current folder in the file hierarchy.
+   *
+   * The default binding for this signal is <kbd>Alt</kbd>-<kbd>Up</kbd>.
    */
   signals[UP_FOLDER] =
     g_signal_new_class_handler (I_("up-folder"),
@@ -7353,16 +7357,18 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * GtkFileChooserWidget::down-folder:
    * @widget: the object which received the signal
    *
-   * The ::down-folder signal is a [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user asks for it.
+   * Emitted when the user asks for it.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
    *
-   * This is used to make the file chooser go to a child of the current folder
-   * in the file hierarchy. The subfolder that will be used is displayed in the
-   * path bar widget of the file chooser. For example, if the path bar is showing
-   * "/foo/bar/baz", with bar currently displayed, then this will cause the file
-   * chooser to switch to the "baz" subfolder.
+   * This is used to make the file chooser go to a child of the
+   * current folder in the file hierarchy. The subfolder that will
+   * be used is displayed in the path bar widget of the file chooser.
+   * For example, if the path bar is showing "/foo/bar/baz", with bar
+   * currently displayed, then this will cause the file chooser to
+   * switch to the "baz" subfolder.
    *
-   * The default binding for this signal is `Alt + Down`.
+   * The default binding for this signal is <kbd>Alt</kbd>-<kbd>Down</kbd>.
    */
   signals[DOWN_FOLDER] =
     g_signal_new_class_handler (I_("down-folder"),
@@ -7377,13 +7383,14 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * GtkFileChooserWidget::home-folder:
    * @widget: the object which received the signal
    *
-   * The ::home-folder signal is a [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user asks for it.
+   * Emitted when the user asks for it.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
    *
    * This is used to make the file chooser show the user's home
    * folder in the file list.
    *
-   * The default binding for this signal is `Alt + Home`.
+   * The default binding for this signal is <kbd>Alt</kbd>-<kbd>Home</kbd>.
    */
   signals[HOME_FOLDER] =
     g_signal_new_class_handler (I_("home-folder"),
@@ -7398,13 +7405,14 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * GtkFileChooserWidget::desktop-folder:
    * @widget: the object which received the signal
    *
-   * The ::desktop-folder signal is a [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user asks for it.
+   * Emitted when the user asks for it.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
    *
    * This is used to make the file chooser show the user's Desktop
    * folder in the file list.
    *
-   * The default binding for this signal is `Alt + D`.
+   * The default binding for this signal is <kbd>Alt</kbd>-<kbd>D</kbd>.
    */
   signals[DESKTOP_FOLDER] =
     g_signal_new_class_handler (I_("desktop-folder"),
@@ -7420,18 +7428,20 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * @widget: the object which received the signal
    * @bookmark_index: the number of the bookmark to switch to
    *
-   * The ::quick-bookmark signal is a [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user asks for it.
+   * Emitted when the user asks for it.
    *
-   * This is used to make the file chooser switch to the bookmark specified
-   * in the @bookmark_index parameter. For example, if you have three bookmarks,
-   * you can pass 0, 1, 2 to this signal to switch to each of them, respectively.
+   * This is a [keybinding signal](class.SignalAction.html).
    *
-   * The default binding for this signal is `Alt + 1`, `Alt + 2`,
-   * etc. until `Alt + 0`.  Note that in the default binding, that
-   * `Alt + 1` is actually defined to switch to the bookmark at index
-   * 0, and so on successively; `Alt + 0` is defined to switch to the
-   * bookmark at index 10.
+   * This is used to make the file chooser switch to the bookmark
+   * specified in the @bookmark_index parameter. For example, if
+   * you have three bookmarks, you can pass 0, 1, 2 to this signal
+   * to switch to each of them, respectively.
+   *
+   * The default binding for this signal is <kbd>Alt</kbd>-<kbd>1</kbd>,
+   * <kbd>Alt</kbd>-<kbd>2</kbd>, etc. until <kbd>Alt</kbd>-<kbd>0</kbd>.
+   * Note that in the default binding, that <kbd>Alt</kbd>-<kbd>1</kbd> is
+   * actually defined to switch to the bookmark at index 0, and so on
+   * successively.
    */
   signals[QUICK_BOOKMARK] =
     g_signal_new_class_handler (I_("quick-bookmark"),
@@ -7446,12 +7456,13 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * GtkFileChooserWidget::show-hidden:
    * @widget: the object which received the signal
    *
-   * The ::show-hidden signal is a [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user asks for it.
+   * Emitted when the user asks for it.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
    *
    * This is used to make the file chooser display hidden files.
    *
-   * The default binding for this signal is `Control + H`.
+   * The default binding for this signal is <kbd>Control</kbd>-<kbd>H</kbd>.
    */
   signals[SHOW_HIDDEN] =
     g_signal_new_class_handler (I_("show-hidden"),
@@ -7466,12 +7477,13 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * GtkFileChooserWidget::search-shortcut:
    * @widget: the object which received the signal
    *
-   * The ::search-shortcut signal is a [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user asks for it.
+   * Emitted when the user asks for it.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
    *
    * This is used to make the file chooser show the search entry.
    *
-   * The default binding for this signal is `Alt + S`.
+   * The default binding for this signal is <kbd>Alt</kbd>-<kbd>S</kbd>.
    */
   signals[SEARCH_SHORTCUT] =
     g_signal_new_class_handler (I_("search-shortcut"),
@@ -7486,12 +7498,13 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * GtkFileChooserWidget::recent-shortcut:
    * @widget: the object which received the signal
    *
-   * The ::recent-shortcut signal is a [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user asks for it.
+   * Emitted when the user asks for it.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
    *
    * This is used to make the file chooser show the Recent location.
    *
-   * The default binding for this signal is `Alt + R`.
+   * The default binding for this signal is <kbd>Alt</kbd>-<kbd>R</kbd>.
    */
   signals[RECENT_SHORTCUT] =
     g_signal_new_class_handler (I_("recent-shortcut"),
@@ -7506,12 +7519,13 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class)
    * GtkFileChooserWidget::places-shortcut:
    * @widget: the object which received the signal
    *
-   * The ::places-shortcut signal is a [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user asks for it.
+   * Emitted when the user asks for it.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
    *
    * This is used to move the focus to the places sidebar.
    *
-   * The default binding for this signal is `Alt + P`.
+   * The default binding for this signal is <kbd>Alt</kbd>-<kbd>P</kbd>.
    */
   signals[PLACES_SHORTCUT] =
     g_signal_new_class_handler (I_("places-shortcut"),
@@ -7892,12 +7906,14 @@ gtk_file_chooser_widget_init (GtkFileChooserWidget *impl)
  * gtk_file_chooser_widget_new:
  * @action: Open or save mode for the widget
  *
- * Creates a new #GtkFileChooserWidget. This is a file chooser widget that can
- * be embedded in custom windows, and it is the same widget that is used by
- * #GtkFileChooserDialog.
+ * Creates a new `GtkFileChooserWidget`.
+ *
+ * This is a file chooser widget that can be embedded in custom
+ * windows, and it is the same widget that is used by
+ * `GtkFileChooserDialog`.
  *
- * Returns: a new #GtkFileChooserWidget
- **/
+ * Returns: a new `GtkFileChooserWidget`
+ */
 GtkWidget *
 gtk_file_chooser_widget_new (GtkFileChooserAction action)
 {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]