From: Daniel Boles Date: Wed, 5 Jul 2023 11:01:43 +0000 (+0100) Subject: docs/list-widget: links, DirList, correct Sections X-Git-Tag: archive/raspbian/4.12.3+ds-1+rpi1~1^2^2^2~22^2~1^2~72 X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=d5ea376e7b1693d98a198f1041d0372298f9319d;p=gtk4.git docs/list-widget: links, DirList, correct Sections * Add links to various symbols. * Mention DirectoryList in the "ready-made choices available" section. * Don't say that GridView can display headers: it makes no attempt to. --- diff --git a/docs/reference/gtk/section-list-widget.md b/docs/reference/gtk/section-list-widget.md index 41db44ba0f..18267dc36c 100644 --- a/docs/reference/gtk/section-list-widget.md +++ b/docs/reference/gtk/section-list-widget.md @@ -30,12 +30,12 @@ Views display data from a **_model_**. Models implement the [`iface@Gio.ListMode interface and can be provided in a variety of ways: * List model implementations for many specific types of data already exist, for - example `GtkDirectoryList` or `GtkStringList`. + example [`class@Gtk.DirectoryList`] or [`class@Gtk.StringList`]. - * There are generic list model implementations like`GListStore` that allow building + * There are generic list model implementations like [`class@Gio.ListStore`] that allow building lists of arbitrary objects. - * Wrapping list models like `GtkFilterListModel` or `GtkSortListModel` + * Wrapping list models like [`class@Gtk.FilterListModel`] or [`class@Gtk.SortListModel`] modify, adapt or combine other models. * Last but not least, developers are encouraged to create their own `GListModel` @@ -133,8 +133,8 @@ tradeoffs of those and experiment with them. GTK offers a wide variety of wrapping models which change or supplement an existing model (or models) in some way. But when it comes to storing your -actual data, there are only a few ready-made choices available: [`class@Gio.ListStore`] -and [`class@Gtk.StringList`]. +actual data, there are only a few ready-made choices available: +[`class@Gio.ListStore`], [`class@Gtk.StringList`], and [`class@Gtk.DirectoryList`]. `GListStore` is backed by a balanced tree and has performance characteristics that are expected for that data structure. It works reasonably well for dataset @@ -147,6 +147,10 @@ that are expected for that data structure. `GtkStringList` is a good fit for any place where you would otherwise use `char*[]` and works best if the dataset is not very dynamic. +`GtkDirectoryList` is a list model that wraps [`method@Gio.File.enumerate_children_async`]. +It presents a `GListModel` and fills it asynchronously with the [`iface@Gio.File`]s +returned from that function. + If these models don't fit your use case or scalability requirements, you should make a custom `GListModel` implementation. It is a small interface and not very hard to implement. @@ -199,7 +203,7 @@ 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 +the `GtkSectionModel` interface. `GtkListView` can display headers for sections, by installing a separate **_header factory_**. Many GTK list models support section inherently, or they pass through the