From: Matthias Clasen <mclasen@redhat.com>
Date: Sun, 21 May 2023 23:11:15 +0000 (-0400)
Subject: Improve section model docs
X-Git-Tag: archive/raspbian/4.12.3+ds-1+rpi1~1^2^2^2~22^2~1^2~230^2
X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=534f11e317bb8cffe5220f48bb73cfb89041af4d;p=gtk4.git

Improve section model docs

Mention sections in the list widget overview,
and document the list models that support sections.
---

diff --git a/docs/reference/gtk/section-list-widget.md b/docs/reference/gtk/section-list-widget.md
index 9ab0be7112..41db44ba0f 100644
--- a/docs/reference/gtk/section-list-widget.md
+++ b/docs/reference/gtk/section-list-widget.md
@@ -196,6 +196,15 @@ The _data table_ style of list is a high density table, similar in style to a
 traditional treeview. Individual cells can be selectable and editable. Use
 the `.data-table` style class.
 
+## Sections
+
+List models can optionally group their items into **_sections_**, by implementing
+the `GtkSectionModel` interface. Both `GtkListView` and `GtkGridView` can
+display headers for sections, by installing a separate **_header factory_**.
+
+Many GTK list models support section inherently, or they pass through the
+section of a model they are wrapping.
+
 ## Comparison to GtkTreeView
 
 Developers familiar with `GtkTreeView` may wonder how this way of doing lists
diff --git a/gtk/gtkfilterlistmodel.c b/gtk/gtkfilterlistmodel.c
index 7e53e52c11..a41b19fa6e 100644
--- a/gtk/gtkfilterlistmodel.c
+++ b/gtk/gtkfilterlistmodel.c
@@ -34,9 +34,11 @@
  * It hides some elements from the other model according to
  * criteria given by a `GtkFilter`.
  *
- * The model can be set up to do incremental searching, so that
+ * The model can be set up to do incremental filtering, so that
  * filtering long lists doesn't block the UI. See
  * [method@Gtk.FilterListModel.set_incremental] for details.
+ *
+ * `GtkFilterListModel` passes through sections from the underlying model.
  */
 
 enum {
diff --git a/gtk/gtkflattenlistmodel.c b/gtk/gtkflattenlistmodel.c
index f80e80ff6d..805fca8b70 100644
--- a/gtk/gtkflattenlistmodel.c
+++ b/gtk/gtkflattenlistmodel.c
@@ -29,8 +29,8 @@
  *
  * `GtkFlattenListModel` is a list model that concatenates other list models.
  *
- * `GtkFlattenListModel` takes a list model containing list models,
- *  and flattens it into a single model.
+ * `GtkFlattenListModel` takes a list model containing list models, and flattens
+ * it into a single model. Each list model becomes a section in the single model.
  */
 
 enum {
diff --git a/gtk/gtksectionmodel.c b/gtk/gtksectionmodel.c
index a5084ab340..eccbe72369 100644
--- a/gtk/gtksectionmodel.c
+++ b/gtk/gtksectionmodel.c
@@ -26,21 +26,19 @@
 /**
  * GtkSectionModel:
  *
- * `GtkSectionModel` is an interface that adds support for section to list models.
+ * `GtkSectionModel` is an interface that adds support for sections to list models.
  *
- * This support is then used by widgets using list models to be able to group their
- * items into sections.
+ * A `GtkSectionModel` groups successive items into so-called sections. List widgets
+ * like `GtkListView` and `GtkGridView` then allow displaying section headers for
+ * these sections by installing a header factory.
  *
  * Many GTK list models support sections inherently, or they pass through the sections
  * of a model they are wrapping.
  *
- * A `GtkSectionModel` groups successive items into so-called sections. List widgets
- * like `GtkListView` then allow displaying section headers for these sections.
- *
- * When the section groupings of a model changes, the model will emit the
+ * When the section groupings of a model change, the model will emit the
  * [signal@Gtk.SectionModel::sections-changed] signal by calling the
  * [method@Gtk.SectionModel.sections_changed] function. All sections in the given range
- * now need to be queried again.  
+ * then need to be queried again.
  * The [signal@Gio.ListModel::items-changed] signal has the same effect, all sections in
  * that range are invalidated, too.
  *