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/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 = [

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

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

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;

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;