in roughly the same way.
Lists are perfectly fine to be used for very short list of only 2 or 3 elements,
-but generally scale fine to millions of items. Of course, the larger the list
-grows, the more care needs to be taken to choose the right data structures to
-keep things running well.
+but generally scale to millions of items. Of course, the larger the list grows,
+the more care needs to be taken to choose the right data structures to keep things
+running well.
Lists are meant to be used with changing data, both with the items itself changing
as well as the list adding and removing items. Of course, they work just as well
**_Views_** or **_list widgets_** are the widgets that hold and manage the lists.
Examples of these widgets would be [`class@Gtk.ListView`] or [`class@Gtk.GridView`].
-Views display data from a **_model_**. A model is a [`iface@Gio.ListModel`] and
-models can be provided in 3 ways or combinations thereof:
+Views display data from a **_model_**. Models implement the [`iface@Gio.ListModel`]
+interface and can be provided in a variety of ways:
- * Many list models implementations already exist. There are models that provide
- specific data, like `GtkDirectoryList`. And there are models like `GListStore`
- that allow building lists manually.
+ * List model implementations for many specific types of data already exist, for
+ example `GtkDirectoryList` or `GtkStringList`.
+
+ * There are generic list model implementations like`GListStore` that allow building
+ lists of arbitrary objects.
* Wrapping list models like `GtkFilterListModel` or `GtkSortListModel`
modify, adapt or combine other models.
Every item in a model has a **_position_** which is the unsigned integer that
describes where in the model the item is located. The first item in a model is
-at position 0. The position of an item can of course change as other items are
-added or removed from the model.
+at position 0. The position of an item can change as other items are added or
+removed from the model.
It is important to be aware of the difference between items and positions
because the mapping from position to item is not permanent, so developers
for the data displayed, the programming language and development environment
is an important task that can simplify setting up the view tremendously.
-Views support selections via a **_selection model_**. A selection model is an
-implementation of the [`iface@Gtk.SelectionModel`] interface on top of the
-[`iface@Gio.ListModel`] interface that allows marking each item in a model as either
-selected or not selected. Just like regular models, this can be implemented
+Views support selections via a **_selection model_**. A selection model is
+an implementation of the [`iface@Gtk.SelectionModel`] interface on top of the
+[`iface@Gio.ListModel`] interface that allows marking each item in a model as
+either selected or not selected. Just like regular models, this can be implemented
either by implementing `GtkSelectionModel` directly or by wrapping a model with
one of the GTK models provided for this purposes, such as [`class@Gtk.NoSelection`]
or [`class@Gtk.SingleSelection`].
Views and listitems also support activation. Activation means that double
clicking or pressing enter while inside a focused row will cause the view
-to emit and activation signal such as [`signal@Gtk.ListView::activate`]. This
-provides an easy way to set up lists, but can also be turned off on listitems
-if undesired.
+to emit a signal such as [`signal@Gtk.ListView::activate`]. This provides an
+easy way to set up lists, but can also be turned off on listitems if undesired.
Both selections and activation are supported among other things via widget
[actions](#actions-overview). This allows developers to add widgets to their
-lists that cause selections to change or to trigger activation via
-the [`iface@Gtk.Actionable`] interface. For a list of all supported actions see
-the relevant documentation.
+lists that cause selections to change or to trigger activation via the
+[`iface@Gtk.Actionable`] interface. For a list of all supported actions
+see the relevant documentation.
## Behind the scenes
-While for short lists it is not a problem to instantiate widgets for every
+While it is not a problem for short lists to instantiate widgets for every
item in the model, once lists grow to thousands or millions of elements, this
gets less feasible. Because of this, the views only create a limited amount of
listitems and recycle them by binding them to new items. In general, views try
screen.
While this behavior allows views to scale effortlessly to huge lists, it has a
-few implication on what can be done with views. For example, it is not possible
+few implications for what can be done with views. For example, it is not possible
to query a view for a listitem used for a certain position - there might not be
one and even if there is, that listitem might soon be recycled for a new
position.
use case is displaying lists and not trees and it greatly simplifies the API
interface provided.
-However, GTK provides functionality to make trees look and behave like lists
-for the people who still want to display lists. This is achieved by using
-the [`class@Gtk.TreeListModel`] model to flatten a tree into a list. The
+However, GTK provides functionality to make lists look and behave like trees
+for use cases that require trees. This is achieved by using the
+[`class@Gtk.TreeListModel`] model to flatten a tree into a list. The
[`class@Gtk.TreeExpander`] widget can then be used inside a listitem to allow
users to expand and collapse rows and provide a similar experience to
`GtkTreeView`.
## List styles
One of the advantages of the new list widgets over `GtkTreeView` 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:
+renderers is that they are styleable 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:
-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
+This _rich list_ style 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.
-This style of list is medium density, using a full background to indicate
-focus and selection. Use the `.navigation-sidebar` style class.
+The _sidebar_ style of list is medium density, using a full background to
+indicate focus and selection. Use the `.navigation-sidebar` style class.
-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.
+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.
## Comparison to GtkTreeView
and differences between the two.
This new approach tries to provide roughly the same functionality as the old
-approach but often uses a very different approach to achieve these goals.
+approach but often uses a very different way to achieve these goals.
The main difference and one of the primary reasons for this new development is
-that items can be displayed using regular widgets and `GtkCellRenderer` is no
-longer necessary. This allows all benefits that widgets provide, such as complex
-layout and animating widgets and not only makes cell renderers obsolete, but
-also `GtkCellArea`.
+that items can be displayed using regular widgets and the separate cell renderer
+machinery is no longer necessary. This allows all benefits that widgets provide,
+such as complex layout, animations and CSS styling.
The other big difference is the massive change to the data model. `GtkTreeModel`
-was a rather complex interface for a tree data structure and `GListModel` was
-deliberately designed to be a simple data structure for lists only. (See
+was a rather complex interface for a tree data structure. `GListModel` is
+deliberately designed to be a very simple data structure for lists only. (See
[above](#displaying-trees)) for how to still do trees with this new model.)
-Another big change is that the new model allows for bulk changes via
-the `GListModel::items-changed` signal while `GtkTreeModel` only allows a single
+Another big change is that the new model allows for bulk changes via the
+`GListModel::items-changed` signal while `GtkTreeModel` only allows a single
item to change at once. The goal here is of course to encourage implementation
of custom list models.
the selection models. In particular this allows for complex use cases with
specialized requirements.
-Finally here's a quick list of equivalent functionality to look for when
-transitioning code for easy lookup:
+Finally here's a quick comparison chart of equivalent functionality to look for
+when transitioning code:
| Old | New |
| -------------------- | ------------------------------------------------------- |
projects / gtk4.git / commitdiff