[gtk/ebassi/gidocgen: 316/478] columnview: Convert docs




commit 9145dbe1c6edc1ccc03d76a5d959cf23bfbc9add
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Feb 28 12:55:13 2021 -0500

    columnview: Convert docs

 gtk/gtkcolumnview.c | 242 +++++++++++++++++++++++++++-------------------------
 gtk/gtkcolumnview.h |   6 +-
 2 files changed, 125 insertions(+), 123 deletions(-)
---
diff --git a/gtk/gtkcolumnview.c b/gtk/gtkcolumnview.c
index 2e835d366a..d166055659 100644
--- a/gtk/gtkcolumnview.c
+++ b/gtk/gtkcolumnview.c
@@ -44,42 +44,42 @@
 #include "gtkgestureclick.h"
 
 /**
- * SECTION:gtkcolumnview
- * @title: GtkColumnView
- * @short_description: A widget for displaying lists in multiple columns
- * @see_also: #GtkColumnViewColumn, #GtkTreeView
+ * GtkColumnView:
  *
- * GtkColumnView is a widget to present a view into a large dynamic list of items
- * using multiple columns with headers.
+ * `GtkColumnView` presents a large dynamic list of items using multiple columns
+ * with headers.
  *
- * GtkColumnView uses the factories of its columns to generate a cell widget for
+ * `GtkColumnView` uses the factories of its columns to generate a cell widget for
  * each column, for each visible item and displays them together as the row for
- * this item. The #GtkColumnView:show-row-separators and
- * #GtkColumnView:show-column-separators properties offer a simple way to display
- * separators between the rows or columns.
+ * this item.
  *
- * GtkColumnView allows the user to select items according to the selection
+ * The [property@Gtk.ColumnView:show-row-separators] and
+ * [propertyGtk.ColumnView:show-column-separators] properties offer a simple way
+ * to display separators between the rows or columns.
+ *
+ * `GtkColumnView` allows the user to select items according to the selection
  * characteristics of the model. For models that allow multiple selected items,
  * it is possible to turn on *rubberband selection*, using
- * #GtkColumnView:enable-rubberband.
+ * [property@Gtk.ColumnView:enable-rubberband].
  *
  * The column view supports sorting that can be customized by the user by
- * clicking on column headers. To set this up, the #GtkSorter returned by
- * gtk_column_view_get_sorter() must be attached to a sort model for the data
- * that the view is showing, and the columns must have sorters attached to them
- * by calling gtk_column_view_column_set_sorter(). The initial sort order can be
- * set with gtk_column_view_sort_by_column().
+ * clicking on column headers. To set this up, the `GtkSorter` returned by
+ * [method@Gtk.ColumnView.get_sorter] must be attached to a sort model for the
+ * data that the view is showing, and the columns must have sorters attached to
+ * them by calling [method@Gtk.ColumnViewColumn.set_sorter]. The initial sort
+ * order can be set with [method@Gtk.ColumnView.sort_by_column].
  *
  * The column view also supports interactive resizing and reordering of
  * columns, via Drag-and-Drop of the column headers. This can be enabled or
- * disabled with the #GtkColumnView:reorderable and #GtkColumnViewColumn:resizable
- * properties.
+ * disabled with the [property@Gtk.ColumnView:reorderable] and
+ * [property@Gtk.ColumnViewColumn:resizable] properties.
  *
- * To learn more about the list widget framework, see the [overview](#ListWidget).
+ * To learn more about the list widget framework, see the
+ * [overview](section-list-widget.html).
  *
  * # CSS nodes
  *
- * |[<!-- language="plain" -->
+ * ```
  * columnview[.column-separators][.rich-list][.navigation-sidebar][.data-table]
  * ├── header
  * │   ├── <column header>
@@ -90,28 +90,27 @@
  * │
  * ┊
  * ╰── [rubberband]
-
- * ]|
+ * ```
  *
- * GtkColumnView uses a single CSS node named columnview. It may carry the
- * .column-separators style class, when #GtkColumnView:show-column-separators
- * property is set. Header widets appear below a node with name header.
- * The rows are contained in a GtkListView widget, so there is a listview
- * node with the same structure as for a standalone GtkListView widget. If
- * #GtkColumnView:show-row-separators is set, it will be passed on to the
- * list view, causing its CSS node to carry the .separators style class.
+ * `GtkColumnView` uses a single CSS node named columnview. It may carry the
+ * .column-separators style class, when [property@Gtk.ColumnView:show-column-separators]
+ * property is set. Header widgets appear below a node with name header.
+ * The rows are contained in a `GtkListView` widget, so there is a listview
+ * node with the same structure as for a standalone `GtkListView` widget.
+ * If [property@Gtk.ColumnView:show-row-separators] is set, it will be passed
+ * on to the list view, causing its CSS node to carry the .separators style class.
  * For rubberband selection, a node with name rubberband is used.
  *
  * The main columnview node may also carry style classes to select
- * the style of [list presentation](ListContainers.html#list-styles):
+ * the style of [list presentation](section-list-widget.html#list-styles):
  * .rich-list, .navigation-sidebar or .data-table.
  *
  * # Accessibility
  *
- * GtkColumnView uses the #GTK_ACCESSIBLE_ROLE_TREE_GRID role, header title
- * widgets are using the #GTK_ACCESSIBLE_ROLE_COLUMN_HEADER role. The row widgets
- * are using the #GTK_ACCESSIBLE_ROLE_ROW role, and individual cells are using
- * the #GTK_ACCESSIBLE_ROLE_GRID_CELL role
+ * `GtkColumnView` uses the %GTK_ACCESSIBLE_ROLE_TREE_GRID role, header title
+ * widgets are using the %GTK_ACCESSIBLE_ROLE_COLUMN_HEADER role. The row widgets
+ * are using the %GTK_ACCESSIBLE_ROLE_ROW role, and individual cells are using
+ * the %GTK_ACCESSIBLE_ROLE_GRID_CELL role
  */
 
 /* We create a subclass of GtkListView for the sole purpose of overriding
@@ -674,9 +673,9 @@ gtk_column_view_class_init (GtkColumnViewClass *klass)
                              g_object_interface_find_property (iface, "vscroll-policy"));
 
   /**
-   * GtkColumnView:columns:
+   * GtkColumnView:columns: (attributes org.gtk.Property.get=gtk_column_view_get_columns)
    *
-   * The list of columns
+   * The list of columns.
    */
   properties[PROP_COLUMNS] =
     g_param_spec_object ("columns",
@@ -686,9 +685,9 @@ gtk_column_view_class_init (GtkColumnViewClass *klass)
                          G_PARAM_READABLE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS);
 
   /**
-   * GtkColumnView:model:
+   * GtkColumnView:model: (attributes org.gtk.Property.get=gtk_column_view_get_model 
org.gtk.Property.set=gtk_column_view_set_model)
    *
-   * Model for the items displayed
+   * Model for the items displayed.
    */
   properties[PROP_MODEL] =
     g_param_spec_object ("model",
@@ -698,9 +697,9 @@ gtk_column_view_class_init (GtkColumnViewClass *klass)
                          G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS);
 
   /**
-   * GtkColumnView:show-row-separators:
+   * GtkColumnView:show-row-separators: (attributes 
org.gtk.Property.get=gtk_column_view_get_show_row_separators 
org.gtk.Property.set=gtk_column_view_set_show_row_separators)
    *
-   * Show separators between rows
+   * Show separators between rows.
    */
   properties[PROP_SHOW_ROW_SEPARATORS] =
     g_param_spec_boolean ("show-row-separators",
@@ -710,9 +709,9 @@ gtk_column_view_class_init (GtkColumnViewClass *klass)
                           G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkColumnView:show-column-separators:
+   * GtkColumnView:show-column-separators: (attributes 
org.gtk.Property.get=gtk_column_view_get_show_column_separators 
org.gtk.Property.set=gtk_column_view_set_show_column_separators)
    *
-   * Show separators between columns
+   * Show separators between columns.
    */
   properties[PROP_SHOW_COLUMN_SEPARATORS] =
     g_param_spec_boolean ("show-column-separators",
@@ -722,9 +721,9 @@ gtk_column_view_class_init (GtkColumnViewClass *klass)
                           G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkColumnView:sorter:
+   * GtkColumnView:sorter: (attributes org.gtk.Property.get=gtk_column_view_get_sorter)
    *
-   * Sorter with the sorting choices of the user
+   * Sorter with the sorting choices of the user.
    */
   properties[PROP_SORTER] =
     g_param_spec_object ("sorter",
@@ -734,9 +733,9 @@ gtk_column_view_class_init (GtkColumnViewClass *klass)
                          G_PARAM_READABLE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS);
 
   /**
-   * GtkColumnView:single-click-activate:
+   * GtkColumnView:single-click-activate: (attributes 
org.gtk.Property.get=gtk_column_view_get_single_click_activate 
org.gtk.Property.set=gtk_column_view_set_single_click_activate)
    *
-   * Activate rows on single click and select them on hover
+   * Activate rows on single click and select them on hover.
    */
   properties[PROP_SINGLE_CLICK_ACTIVATE] =
     g_param_spec_boolean ("single-click-activate",
@@ -746,9 +745,9 @@ gtk_column_view_class_init (GtkColumnViewClass *klass)
                           G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkColumnView:reorderable:
+   * GtkColumnView:reorderable: (attributes org.gtk.Property.get=gtk_column_view_get_reorderable 
org.gtk.Property.set=gtk_column_view_set_reorderable)
    *
-   * Whether columns are reorderable
+   * Whether columns are reorderable.
    */
   properties[PROP_REORDERABLE] =
     g_param_spec_boolean ("reorderable",
@@ -758,9 +757,9 @@ gtk_column_view_class_init (GtkColumnViewClass *klass)
                           G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS);
 
   /**
-   * GtkColumnView:enable-rubberband:
+   * GtkColumnView:enable-rubberband: (attributes org.gtk.Property.get=gtk_column_view_get_enable_rubberband 
org.gtk.Property.set=gtk_column_view_set_enable_rubberband)
    *
-   * Allow rubberband selection
+   * Allow rubberband selection.
    */
   properties[PROP_ENABLE_RUBBERBAND] =
     g_param_spec_boolean ("enable-rubberband",
@@ -773,14 +772,15 @@ gtk_column_view_class_init (GtkColumnViewClass *klass)
 
   /**
    * GtkColumnView::activate:
-   * @self: The #GtkColumnView
+   * @self: The `GtkColumnView`
    * @position: position of item to activate
    *
-   * The ::activate signal is emitted when a row has been activated by the user,
-   * usually via activating the GtkListBase|list.activate-item action.
+   * Emitted when a row has been activated by the user, usually via activating
+   * the GtkListBase|list.activate-item action.
    *
    * This allows for a convenient way to handle activation in a columnview.
-   * See gtk_list_item_set_activatable() for details on how to use this signal.
+   * See [method@Gtk.ListItem.set_activatable] for details on how to use this
+   * signal.
    */
   signals[ACTIVATE] =
     g_signal_new (I_("activate"),
@@ -1329,12 +1329,12 @@ gtk_column_view_init (GtkColumnView *self)
  * gtk_column_view_new:
  * @model: (allow-none) (transfer full): the list model to use, or %NULL
  *
- * Creates a new #GtkColumnView.
+ * Creates a new `GtkColumnView`.
  *
- * You most likely want to call gtk_column_view_append_column() to
- * add columns next.
+ * You most likely want to call [method@Gtk.ColumnView.append_column]
+ * to add columns next.
  *
- * Returns: a new #GtkColumnView
+ * Returns: a new `GtkColumnView`
  **/
 GtkWidget *
 gtk_column_view_new (GtkSelectionModel *model)
@@ -1354,13 +1354,13 @@ gtk_column_view_new (GtkSelectionModel *model)
 }
 
 /**
- * gtk_column_view_get_model:
- * @self: a #GtkColumnView
+ * gtk_column_view_get_model: (attributes org.gtk.Method.get_property=model)
+ * @self: a `GtkColumnView`
  *
  * Gets the model that's currently used to read the items displayed.
  *
  * Returns: (nullable) (transfer none): The model in use
- **/
+ */
 GtkSelectionModel *
 gtk_column_view_get_model (GtkColumnView *self)
 {
@@ -1370,12 +1370,14 @@ gtk_column_view_get_model (GtkColumnView *self)
 }
 
 /**
- * gtk_column_view_set_model:
+ * gtk_column_view_set_model: (attributes org.gtk.Method.set_property=model)
  * @self: a #GtkColumnView
  * @model: (allow-none) (transfer none): the model to use or %NULL for none
  *
- * Sets the #GtkSelectionModel to use.
- **/
+ * Sets the model to use.
+ *
+ * This must be a [iface@Gtk.SelectionModel].
+ */
 void
 gtk_column_view_set_model (GtkColumnView     *self,
                            GtkSelectionModel *model)
@@ -1392,15 +1394,17 @@ gtk_column_view_set_model (GtkColumnView     *self,
 }
 
 /**
- * gtk_column_view_get_columns:
- * @self: a #GtkColumnView
+ * gtk_column_view_get_columns: (attributes org.gtk.Method.get_property=columns)
+ * @self: a `GtkColumnView`
+ *
+ * Gets the list of columns in this column view.
  *
- * Gets the list of columns in this column view. This list is constant over
- * the lifetime of @self and can be used to monitor changes to the columns
- * of @self by connecting to the #GListModel:items-changed signal.
+ * This list is constant over the lifetime of @self and can be used to
+ * monitor changes to the columns of @self by connecting to the
+ * ::items-changed signal.
  *
  * Returns: (transfer none): The list managing the columns
- **/
+ */
 GListModel *
 gtk_column_view_get_columns (GtkColumnView *self)
 {
@@ -1410,8 +1414,8 @@ gtk_column_view_get_columns (GtkColumnView *self)
 }
 
 /**
- * gtk_column_view_set_show_row_separators:
- * @self: a #GtkColumnView
+ * gtk_column_view_set_show_row_separators: (attributes org.gtk.Method.set_property=show-row-separators)
+ * @self: a `GtkColumnView`
  * @show_row_separators: %TRUE to show row separators
  *
  * Sets whether the list should show separators
@@ -1432,8 +1436,8 @@ gtk_column_view_set_show_row_separators (GtkColumnView *self,
 }
 
 /**
- * gtk_column_view_get_show_row_separators:
- * @self: a #GtkColumnView
+ * gtk_column_view_get_show_row_separators: (attributes org.gtk.Method.get_property=show-row-separators)
+ * @self: a `GtkColumnView`
  *
  * Returns whether the list should show separators
  * between rows.
@@ -1449,8 +1453,8 @@ gtk_column_view_get_show_row_separators (GtkColumnView *self)
 }
 
 /**
- * gtk_column_view_set_show_column_separators:
- * @self: a #GtkColumnView
+ * gtk_column_view_set_show_column_separators: (attributes 
org.gtk.Method.set_property=show-column-separators)
+ * @self: a `GtkColumnView`
  * @show_column_separators: %TRUE to show column separators
  *
  * Sets whether the list should show separators
@@ -1476,8 +1480,8 @@ gtk_column_view_set_show_column_separators (GtkColumnView *self,
 }
 
 /**
- * gtk_column_view_get_show_column_separators:
- * @self: a #GtkColumnView
+ * gtk_column_view_get_show_column_separators: (attributes 
org.gtk.Method.get_property=show-column-separators)
+ * @self: a `GtkColumnView`
  *
  * Returns whether the list should show separators
  * between columns.
@@ -1494,12 +1498,12 @@ gtk_column_view_get_show_column_separators (GtkColumnView *self)
 
 /**
  * gtk_column_view_append_column:
- * @self: a #GtkColumnView
- * @column: a #GtkColumnViewColumn that hasn't been added to a
- *     #GtkColumnView yet
+ * @self: a `GtkColumnView`
+ * @column: a `GtkColumnViewColumn` that hasn't been added to a
+ *     `GtkColumnView` yet
  *
  * Appends the @column to the end of the columns in @self.
- **/
+ */
 void
 gtk_column_view_append_column (GtkColumnView       *self,
                                GtkColumnViewColumn *column)
@@ -1514,11 +1518,11 @@ gtk_column_view_append_column (GtkColumnView       *self,
 
 /**
  * gtk_column_view_remove_column:
- * @self: a #GtkColumnView
- * @column: a #GtkColumnViewColumn that's part of @self
+ * @self: a `GtkColumnView`
+ * @column: a `GtkColumnViewColumn` that's part of @self
  *
  * Removes the @column from the list of columns of @self.
- **/
+ */
 void
 gtk_column_view_remove_column (GtkColumnView       *self,
                                GtkColumnViewColumn *column)
@@ -1545,9 +1549,9 @@ gtk_column_view_remove_column (GtkColumnView       *self,
 
 /**
  * gtk_column_view_insert_column:
- * @self: a #GtkColumnView
+ * @self: a `GtkColumnView`
  * @position: the position to insert @column at
- * @column: the #GtkColumnViewColumn to insert
+ * @column: the `GtkColumnViewColumn` to insert
  *
  * Inserts a column at the given position in the columns of @self.
  *
@@ -1638,8 +1642,8 @@ gtk_column_view_get_list_view (GtkColumnView *self)
 }
 
 /**
- * gtk_column_view_get_sorter:
- * @self: a #GtkColumnView
+ * gtk_column_view_get_sorter: (attributes org.gtk.Method.get_property=sorter)
+ * @self: a `GtkColumnView`
  *
  * Returns a special sorter that reflects the users sorting
  * choices in the column view.
@@ -1648,20 +1652,20 @@ gtk_column_view_get_list_view (GtkColumnView *self)
  * headers, this sorter needs to be set on the sort model underneath
  * the model that is displayed by the view.
  *
- * See gtk_column_view_column_set_sorter() for setting up
+ * See [method@Gtk.ColumnViewColumn.set_sorter] for setting up
  * per-column sorting.
  *
  * Here is an example:
- * |[
- *   gtk_column_view_column_set_sorter (column, sorter);
- *   gtk_column_view_append_column (view, column);
- *   sorter = g_object_ref (gtk_column_view_get_sorter (view)));
- *   model = gtk_sort_list_model_new (store, sorter);
- *   selection = gtk_no_selection_new (model);
- *   gtk_column_view_set_model (view, selection);
- * ]|
+ * ```c
+ * gtk_column_view_column_set_sorter (column, sorter);
+ * gtk_column_view_append_column (view, column);
+ * sorter = g_object_ref (gtk_column_view_get_sorter (view)));
+ * model = gtk_sort_list_model_new (store, sorter);
+ * selection = gtk_no_selection_new (model);
+ * gtk_column_view_set_model (view, selection);
+ * ```
  *
- * Returns: (nullable) (transfer none): the #GtkSorter of @self
+ * Returns: (nullable) (transfer none): the `GtkSorter` of @self
  */
 GtkSorter *
 gtk_column_view_get_sorter (GtkColumnView *self)
@@ -1673,17 +1677,19 @@ gtk_column_view_get_sorter (GtkColumnView *self)
 
 /**
  * gtk_column_view_sort_by_column:
- * @self: a #GtkColumnView
- * @column: (allow-none): the #GtkColumnViewColumn to sort by, or %NULL
+ * @self: a `GtkColumnView`
+ * @column: (allow-none): the `GtkColumnViewColumn` to sort by, or %NULL
  * @direction: the direction to sort in
  *
  * Sets the sorting of the view.
  *
- * This function should be used to set up the initial sorting. At runtime,
- * users can change the sorting of a column view by clicking on the list headers.
+ * This function should be used to set up the initial sorting.
+ * At runtime, users can change the sorting of a column view
+ * by clicking on the list headers.
  *
- * This call only has an effect if the sorter returned by gtk_column_view_get_sorter()
- * is set on a sort model, and gtk_column_view_column_set_sorter() has been called
+ * This call only has an effect if the sorter returned by
+ * [method@Gtk.ColumnView.get_sorter] is set on a sort model,
+ * and [method@Gtk.ColumnViewColumn.set_sorter] has been called
  * on @column to associate a sorter with the column.
  *
  * If @column is %NULL, the view will be unsorted.
@@ -1706,8 +1712,8 @@ gtk_column_view_sort_by_column (GtkColumnView       *self,
 }
 
 /**
- * gtk_column_view_set_single_click_activate:
- * @self: a #GtkColumnView
+ * gtk_column_view_set_single_click_activate: (attributes org.gtk.Method.set_property=single-click-activate)
+ * @self: a `GtkColumnView`
  * @single_click_activate: %TRUE to activate items on single click
  *
  * Sets whether rows should be activated on single click and
@@ -1728,8 +1734,8 @@ gtk_column_view_set_single_click_activate (GtkColumnView *self,
 }
 
 /**
- * gtk_column_view_get_single_click_activate:
- * @self: a #GtkColumnView
+ * gtk_column_view_get_single_click_activate: (attributes org.gtk.Method.get_property=single-click-activate)
+ * @self: a `GtkColumnView`
  *
  * Returns whether rows will be activated on single click and
  * selected on hover.
@@ -1745,8 +1751,8 @@ gtk_column_view_get_single_click_activate (GtkColumnView *self)
 }
 
 /**
- * gtk_column_view_set_reorderable:
- * @self: a #GtkColumnView
+ * gtk_column_view_set_reorderable: (attributes org.gtk.Method.set_property=reorderable)
+ * @self: a `GtkColumnView`
  * @reorderable: whether columns should be reorderable
  *
  * Sets whether columns should be reorderable by dragging.
@@ -1766,8 +1772,8 @@ gtk_column_view_set_reorderable (GtkColumnView *self,
 }
 
 /**
- * gtk_column_view_get_reorderable:
- * @self: a #GtkColumnView
+ * gtk_column_view_get_reorderable: (attributes org.gtk.Method.get_property=reorderable)
+ * @self: a `GtkColumnView`
  *
  * Returns whether columns are reorderable.
  *
@@ -1782,8 +1788,8 @@ gtk_column_view_get_reorderable (GtkColumnView *self)
 }
 
 /**
- * gtk_column_view_set_enable_rubberband:
- * @self: a #GtkColumnView
+ * gtk_column_view_set_enable_rubberband: (attributes org.gtk.Method.set_property=enable-rubberband)
+ * @self: a `GtkColumnView`
  * @enable_rubberband: %TRUE to enable rubberband selection
  *
  * Sets whether selections can be changed by dragging with the mouse.
@@ -1803,8 +1809,8 @@ gtk_column_view_set_enable_rubberband (GtkColumnView *self,
 }
 
 /**
- * gtk_column_view_get_enable_rubberband:
- * @self: a #GtkColumnView
+ * gtk_column_view_get_enable_rubberband: (attributes org.gtk.Method.get_property=enable-rubberband)
+ * @self: a `GtkColumnView`
  *
  * Returns whether rows can be selected by dragging with the mouse.
  *
diff --git a/gtk/gtkcolumnview.h b/gtk/gtkcolumnview.h
index b781f3388d..c2daa53092 100644
--- a/gtk/gtkcolumnview.h
+++ b/gtk/gtkcolumnview.h
@@ -38,11 +38,7 @@ G_BEGIN_DECLS
 #define GTK_IS_COLUMN_VIEW_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), GTK_TYPE_COLUMN_VIEW))
 #define GTK_COLUMN_VIEW_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GTK_TYPE_COLUMN_VIEW, 
GtkColumnViewClass))
 
-/**
- * GtkColumnView:
- *
- * GtkColumnView is the simple list implementation for GTK's list widgets.
- */
+
 typedef struct _GtkColumnView GtkColumnView;
 typedef struct _GtkColumnViewClass GtkColumnViewClass;
 /* forward declaration */


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]