From: Benjamin Otte <otte@redhat.com>
Date: Fri, 13 Dec 2019 06:45:57 +0000 (+0100)
Subject: treelistmodel: Improve docs
X-Git-Tag: archive/raspbian/4.4.1+ds1-2+rpi1^2~18^2~20^2~525
X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=c4043a8eef888f159c057cde7f9cc35b1cea38a2;p=gtk4.git

treelistmodel: Improve docs

- Move into its own section
- Split GtkTreeListRow into its own document

Trees are weird with listmodels and they deserve their own treatment,
they shouldn't be mushed up with the rest of the list machinery.
---

diff --git a/docs/reference/gtk/gtk4-docs.xml b/docs/reference/gtk/gtk4-docs.xml
index 8d4a96f66d..13bbfe4228 100644
--- a/docs/reference/gtk/gtk4-docs.xml
+++ b/docs/reference/gtk/gtk4-docs.xml
@@ -49,12 +49,16 @@
       <xi:include href="xml/gtkmaplistmodel.xml" />
       <xi:include href="xml/gtkslicelistmodel.xml" />
       <xi:include href="xml/gtksortlistmodel.xml" />
-      <xi:include href="xml/gtktreelistmodel.xml" />
       <xi:include href="xml/gtkselectionmodel.xml" />
       <xi:include href="xml/gtknoselection.xml" />
       <xi:include href="xml/gtksingleselection.xml" />
     </chapter>
 
+    <chapter id="Trees">
+      <xi:include href="xml/gtktreelistrow.xml" />
+      <xi:include href="xml/gtktreelistmodel.xml" />
+    </chapter>
+
     <chapter id="Application">
       <title>Application support</title>
       <xi:include href="xml/gtkapplication.xml" />
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index 4939bbda58..698e116302 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -3434,6 +3434,29 @@ GTK_TOOLTIP
 gtk_tooltip_get_type
 </SECTION>
 
+<SECTION>
+<FILE>gtktreelistrow</FILE>
+<TITLE>GtkTreeListRow</TITLE>
+gtk_tree_list_row_get_item
+gtk_tree_list_row_set_expanded
+gtk_tree_list_row_get_expanded
+gtk_tree_list_row_is_expandable
+gtk_tree_list_row_get_position
+gtk_tree_list_row_get_depth
+gtk_tree_list_row_get_children
+gtk_tree_list_row_get_parent
+gtk_tree_list_row_get_child_row
+<SUBSECTION Standard>
+GTK_TREE_LIST_ROW
+GTK_IS_TREE_LIST_ROW
+GTK_TYPE_TREE_LIST_ROW
+GTK_TREE_LIST_ROW_CLASS
+GTK_IS_TREE_LIST_ROW_CLASS
+GTK_TREE_LIST_ROW_GET_CLASS
+<SUBSECTION Private>
+gtk_tree_list_row_get_type
+</SECTION>
+
 <SECTION>
 <FILE>gtktreelistmodel</FILE>
 <TITLE>GtkTreeListModel</TITLE>
@@ -3447,18 +3470,6 @@ gtk_tree_list_model_set_autoexpand
 gtk_tree_list_model_get_autoexpand
 gtk_tree_list_model_get_child_row
 gtk_tree_list_model_get_row
-
-<SUBSECTION>
-gtk_tree_list_row_get_item
-gtk_tree_list_row_set_expanded
-gtk_tree_list_row_get_expanded
-gtk_tree_list_row_is_expandable
-gtk_tree_list_row_get_position
-gtk_tree_list_row_get_depth
-gtk_tree_list_row_get_children
-gtk_tree_list_row_get_parent
-gtk_tree_list_row_get_child_row
-
 <SUBSECTION Standard>
 GTK_TREE_LIST_MODEL
 GTK_IS_TREE_LIST_MODEL
@@ -3466,14 +3477,7 @@ GTK_TYPE_TREE_LIST_MODEL
 GTK_TREE_LIST_MODEL_CLASS
 GTK_IS_TREE_LIST_MODEL_CLASS
 GTK_TREE_LIST_MODEL_GET_CLASS
-GTK_TREE_LIST_ROW
-GTK_IS_TREE_LIST_ROW
-GTK_TYPE_TREE_LIST_ROW
-GTK_TREE_LIST_ROW_CLASS
-GTK_IS_TREE_LIST_ROW_CLASS
-GTK_TREE_LIST_ROW_GET_CLASS
 <SUBSECTION Private>
-gtk_tree_list_model_get_type
 gtk_tree_list_row_get_type
 </SECTION>
 
diff --git a/docs/reference/gtk/gtk4.types.in b/docs/reference/gtk/gtk4.types.in
index 2db6ce2348..45d26146c7 100644
--- a/docs/reference/gtk/gtk4.types.in
+++ b/docs/reference/gtk/gtk4.types.in
@@ -206,6 +206,7 @@ gtk_tool_button_get_type
 gtk_tool_item_get_type
 gtk_tree_drag_dest_get_type
 gtk_tree_drag_source_get_type
+gtk_tree_expander_get_type
 gtk_tree_list_model_get_type
 gtk_tree_list_row_get_type
 gtk_tree_model_filter_get_type
diff --git a/gtk/gtktreelistmodel.c b/gtk/gtktreelistmodel.c
index 333b8b70e6..597de53c6f 100644
--- a/gtk/gtktreelistmodel.c
+++ b/gtk/gtktreelistmodel.c
@@ -930,7 +930,24 @@ gtk_tree_list_model_get_child_row (GtkTreeListModel *self,
   return tree_node_get_row (child);
 }
 
-/***   ROW   ***/
+/**
+ * SECTION:gtktreelistrow
+ * @Short_description: rows in a tree
+ * @Title: GtkTreeListRow
+ * @See_also: #GtkTreeListModel
+ *
+ * #GtkTreeListRow is the object used by #GtkTreeListModel to
+ * represent items. It allows navigating the model as a tree and
+ * modify the state of rows.
+ *
+ * #GtkTreeListRow instances are created by a #GtkTreeListModel only
+ * when the GtkTreeListModel:passthrough property is not set.
+ *
+ * There are various support objects that can make use of #GtkTreeListRow
+ * objects, such as the #GtkTreeExpander widget that allows displaying
+ * an icon to expand or collapse a row or #GtkTreeListRowSorter that makes
+ * it possible to sort trees properly.
+ */
 
 enum {
   ROW_PROP_0,