[gtk/list-styles: 36/48] lists: Mention list style classes in docs

[Matthias Clasen <matthiasc src gnome org>]

commit 221786dda3cb262b47cc0959ca829925b7bec2a2
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Aug 5 16:41:53 2020 -0400

    lists: Mention list style classes in docs
    
    Document that GtkListView, GtkColumnView and GtkListBox
    support .rich-list, .navigation-sidebar and .data-table
    style classes.

 docs/reference/gtk/images/data-table.png         | Bin 0 -> 21717 bytes
 docs/reference/gtk/images/navigation-sidebar.png | Bin 0 -> 28865 bytes
 docs/reference/gtk/images/rich-list.png          | Bin 0 -> 8129 bytes
 docs/reference/gtk/meson.build                   |   3 +++
 docs/reference/gtk/section-list-widget.md        |  24 +++++++++++++++++++++++
 gtk/gtkcolumnview.c                              |   6 +++++-
 gtk/gtklistbox.c                                 |  14 ++++++++-----
 gtk/gtklistview.c                                |   6 +++++-
 8 files changed, 46 insertions(+), 7 deletions(-)
---
diff --git a/docs/reference/gtk/images/data-table.png b/docs/reference/gtk/images/data-table.png
new file mode 100644
index 0000000000..60eb959bf6
Binary files /dev/null and b/docs/reference/gtk/images/data-table.png differ
diff --git a/docs/reference/gtk/images/navigation-sidebar.png 
b/docs/reference/gtk/images/navigation-sidebar.png
new file mode 100644
index 0000000000..5a9b9945cc
Binary files /dev/null and b/docs/reference/gtk/images/navigation-sidebar.png differ
diff --git a/docs/reference/gtk/images/rich-list.png b/docs/reference/gtk/images/rich-list.png
new file mode 100644
index 0000000000..edfece1e5c
Binary files /dev/null and b/docs/reference/gtk/images/rich-list.png differ
diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build
index aa4b7f8673..431192c2c6 100644
--- a/docs/reference/gtk/meson.build
+++ b/docs/reference/gtk/meson.build
@@ -370,6 +370,9 @@ images = [
   'images/widget-hvalign.png',
   'images/window-default.png',
   'images/window.png',
+  'images/rich-list.png',
+  'images/data-table.png',
+  'images/navigation-sidebar.png'
 ]
 
 content_files = [
diff --git a/docs/reference/gtk/section-list-widget.md b/docs/reference/gtk/section-list-widget.md
index 53d25f0853..b93ab872e3 100644
--- a/docs/reference/gtk/section-list-widget.md
+++ b/docs/reference/gtk/section-list-widget.md
@@ -165,6 +165,30 @@ rows and provide a similar experience to #GtkTreeView.
 Developers should refer to those objects' API reference for more discussion
 on the topic.
 
+## List styles {#list-styles}
+
+One of the advantages of the new list widgets over #GtkTreeViews and cell
+renderers is that they are fully themable using GTK CSS. This provides a
+lot of flexibility. The themes that ship with GTK provide a few predefined
+list styles that can be used in many situations:
+
+![Rich list](rich-list.png)
+
+This style of list is low density, spacious and uses an outline focus ring.
+It is suitable for lists of controls, e.g. in preference dialogs or
+settings panels. Use the .rich-list style class.
+
+![Navigation sidebar](navigation-sidebar.png)
+
+This style of list is medium density, using a full background to indicate
+focus and selection. Use the .navigation-sidebar style class.
+
+![Data table](data-table.png)
+
+This 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.
+
 ## Comparison to GtkTreeView
 
 Developers familiar with #GtkTreeView may wonder how this way of doing lists
diff --git a/gtk/gtkcolumnview.c b/gtk/gtkcolumnview.c
index 176481f2ba..deadfd7b9e 100644
--- a/gtk/gtkcolumnview.c
+++ b/gtk/gtkcolumnview.c
@@ -80,7 +80,7 @@
  * # CSS nodes
  *
  * |[<!-- language="plain" -->
- * columnview[.column-separators]
+ * columnview[.column-separators][.rich-list][.navigation-sidebar][.data-table]
  * ├── header
  * │   ├── <column header>
  * ┊   ┊
@@ -101,6 +101,10 @@
  * #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.
  * 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):
+ * .rich-list, .navigation-sidebar or .data-table.
  */
 
 struct _GtkColumnView
diff --git a/gtk/gtklistbox.c b/gtk/gtklistbox.c
index fd0a86e4d2..98af2f58fa 100644
--- a/gtk/gtklistbox.c
+++ b/gtk/gtklistbox.c
@@ -75,14 +75,18 @@
  * # CSS nodes
  *
  * |[<!-- language="plain" -->
- * list[.separators]
+ * list[.separators][.rich-list][.navigation-sidebar]
  * ╰── row[.activatable]
  * ]|
  *
- * GtkListBox uses a single CSS node named list. It may carry the .separators style
- * class, when the #GtkListBox:show-separators property is set. Each GtkListBoxRow uses
- * a single CSS node named row. The row nodes get the .activatable
- * style class added when appropriate.
+ * GtkListBox uses a single CSS node named list. It may carry the .separators
+ * style class, when the #GtkListBox:show-separators property is set. Each
+ * GtkListBoxRow uses a single CSS node named row. The row nodes get the
+ * .activatable style class added when appropriate.
+ *
+ * The main list node may also carry style classes to select
+ * the style of [list presentation](ListContainers.html#list-styles):
+ * .rich-list, .navigation-sidebar or .data-table.
  */
 
 typedef struct _GtkListBoxClass   GtkListBoxClass;
diff --git a/gtk/gtklistview.c b/gtk/gtklistview.c
index e0a33b42f4..aa32b46865 100644
--- a/gtk/gtklistview.c
+++ b/gtk/gtklistview.c
@@ -118,7 +118,7 @@
  * # CSS nodes
  *
  * |[<!-- language="plain" -->
- * listview[.separators]
+ * listview[.separators][.rich-list][.navigation-sidebar][.data-table]
  * ├── row
  * │
  * ├── row
@@ -132,6 +132,10 @@
  * .separators style class, when #GtkListView:show-separators property
  * is set. Each child widget uses a single CSS node named row. For
  * rubberband selection, a node with name rubberband is used.
+ *
+ * The main listview node may also carry style classes to select
+ * the style of [list presentation](ListContainers.html#list-styles):
+ * .rich-list, .navigation-sidebar or .data-table.
  */
 
 typedef struct _ListRow ListRow;