src/libide/tree/ide-tree.c (597) static void ide_tree_init (IdeTree *self) {.} src/libide/tree/ide-tree-model.c (663) static void tree_model_iface_init (GtkTreeModelIface *iface) {.} src/libide/tree/ide-tree-node.c (31) Since: 3.32 * The #IdeTreeNode class is used to represent an item that should be displayed in the tree of the Ide application. * The #IdeTreeAddin plugins create and maintain these nodes during the lifetime of the program. * Plugins that want to add items to the tree should implement the #IdeTreeAddin interface and register it during plugin initialization. src/libide/tree/ide-tree-node.c (127) enum { PROP_0, PROP_CHILDREN_POSSIBLE, PROP_DESTROY_ITEM, PROP_DISPLAY_NAME, PROP_EXPANDED_ICON, PROP_EXPANDED_ICON_NAME, PROP_HAS_ERROR, PROP_ICON, PROP_ICON_NAME, PROP_IS_HEADER, PROP_ITEM, PROP_RESET_ON_COLLAPSE, PROP_TAG, PROP_USE_MARKUP, N_PROPS }; src/libide/tree/ide-tree-node.c (48) struct _IdeTreeNode { GObject parent_instance; /* A pointer to the model, which is only set on the root node. */ IdeTreeModel *model; /* The following are fields containing the values for various properties on the tree node. * Usually, icon, display_name, and item will be set on all nodes. */ GIcon *icon; GIcon *expanded_icon; gchar *display_name; GObject *item; gchar *tag; GList *emblems; /* The following items are used to maintain a tree structure of nodes for which we can use O(1) operations. * The link is inserted into the parents children queue. The parent pointer is unowned, and set by the parent (cleared upon removal). * This also allows maintaining the tree structure with zero additional allocations beyond the nodes themselves. */ IdeTreeNode *parent; GQueue children; GList link; /* Foreground and Background colors */ GdkRGBA background; GdkRGBA foreground; /* Flags for state cell renderer */ IdeTreeNodeFlags flags; /* When did we start loading? This is used to avoid drawing "Loading..." when the tree loads really quickly. Otherwise, we risk looking janky when the loads are quite fast. */ gint64 started_loading_at; /* If we're currently loading */ guint is_loading : 1; /* If the node is a header (bold, etc) */ guint is_header : 1; /* If this is a synthesized empty node */ guint is_empty : 1; /* If there are errors associated with the node's item */ guint has_error : 1; /* If the node maybe has children */ guint children_possible : 1; /* If this node needs to have the children built */ guint needs_build_children : 1; /* If true, we remove all children on collapse */ guint reset_on_collapse : 1; /* If pango markup should be used */ guint use_markup : 1; /* If true, we use ide_clear_and_destroy_object() */ guint destroy_item : 1; /* If colors are set */ guint background_set : 1; guint foreground_set : 1; }; src/libide/tree/ide-tree-node.c (1763) /* If the node is not on screen, we need to animate until we get there. */ src/libide/tree/ide-tree-node.c (1776) /* FIXME: Time period comes from gtk animation duration. Not curently available in pubic API. * We need to be greater than the max timeout it could take to move, since we must have it on screen by then. * One alternative might be to check the result and if we are still not on screen, then just pin it to a row-height from the top or bottom. /----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------/ src/libide/tree/ide-tree-addin.c (108) /* ide_tree_addin_build_children_async() Since: 3.32 * This function is called when building the children of a node. * This happens when expanding an node that might have children, or building the root node. * You may want to use ide_tree_node_holds() to determine if the node contains an item that you are interested in. * This function will call the synchronous form of IdeTreeAddin.build_children() if no asynchronous form is available. src/libide/tree/ide-tree-addin.c (143) /* ide_tree_addin_build_children_finish() Since: 3.32 * Completes an asynchronous request to ide_tree_addin_build_children_async(). * Returns: %TRUE if successful; otherwise %FALSE and @error is set. src/libide/tree/ide-tree-addin.c (167) /* ide_tree_addin_build_node() Since: 3.32 * This function is called when preparing a node for display in the tree. * Addins should adjust any state on the node that makes sense based on the addin. * You may want to use ide_tree_node_holds() to determine if the node contains an item that you are interested in. src/libide/tree/ide-tree-addin.c (194) /* ide_tree_addin_activated() Since: 3.32 * This function is called when a node has been activated in the tree and allows for the addin to perform any necessary operations in response to that. * If the addin performs an action based on the activation request, then it should return %TRUE from this function so that no further addins may respond to the action. * Returns: %TRUE if the activation was handled, otherwise %FALSE /----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------/ src/libide/tree/ide-cell-renderer-status (29) #define CELL_HEIGHT 16, CELL_WIDTH 16, RPAD 8, LPAD 3 /----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------/ src/libide/gui/ide-cell-renderer-fancy.c (166) HACK: @width is the min_width returned in our get_preferred_width() function. That results in pretty bad values here, so we will do this by assuming we are the only widget in the tree view. * This makes this cell very much not usable for generic situations, but it does make it so we can do text wrapping without resorting to GtkListBox *for our exact usecase only*. * The problem here is that we require the widget to already be realized and allocated and that we are the only renderer within the only column (and also, in a treeview) without exotic styling. * If we get something absurdly small (like 50) that is because we are hitting our minimum size of (xpad * 2). * So this works around the issue and tries to get something reasonable with wrapping at the 200px mark (our ~default width for panels). * Furthermore, we need to queue a resize when the column size changes (as it will from resizing the widget). So the tree view must also call gtk_tree_view_column_queue_resize(). https://en.wikibooks.org/wiki/GTK%2B_By_Example/Tree_View/Custom_Models Working Example: Custom List Model Source Code Here is the complete source code for the custom list model presented above. Compile with: gcc -o customlist custom-list.c main.c `pkg-config --cflags --libs gtk+-2.0` * custom-list.h * custom-list.c * main.c https://blog.gtk.org/2020/06/07/scalable-lists-in-gtk-4/ https://docs.gtk.org/gtk4/section-list-widget.html A GtkListItemFactory creates widgets for the items taken from a GListModel. https://docs.gtk.org/gtk4/class.ListItemFactory.html GtkBuilderListItemFactory is a GtkListItemFactory that creates widgets by instantiating GtkBuilder UI templates. The templates must be extending GtkListItem, and typically use GtkExpressions to obtain data from the items in the model. https://docs.gtk.org/gtk4/class.BuilderListItemFactory.html GListModel is an interface that represents a mutable list of GObjects. Its main intention is as a model for various widgets in user interfaces, such as list views, but it can also be used as a convenient method of returning lists of data, with support for updates. https://docs.gtk.org/gio/iface.ListModel.html ---------------------------------------------------------------------------------------------------------------- https://docs.gtk.org/gtk4/getting_started.html https://docs.gtk.org/gtk4/overview.html https://flathub.org/apps/details/ar.xjuan.Cambalache https://github.com/Taiko2k/GTK4PythonTutorial https://github.com/ToshioCP/Gtk4-tutorial https://developer.gnome.org/documentation/tutorials/beginners/getting_started.html https://github.com/Taiko2k/GTK4PythonTutorial#readme ---------------------------------------------------------------------------------------------------------------- GTK Development Blog All things GTK Scalable lists in GTK 4 One of the last big missing pieces in GTK 4 is the infrastructure for new list and grid widgets. It has just been merged and is included in the 3.98.5 release. So it is time to take a closer look. History: tree views and list boxes Since ancient times (ie GTK 2), GtkTreeView has been the go-to data display widget in GTK. It uses a model-view pattern to keep the data separate from the display infrastructure. Over the years, it has grown a grid-display sibling (GtkIconView) and a selection cousin (GtkComboBox), using the same infrastructure (tree models and cell renderers). Unfortunately, the approach taken for rendering in GtkTreeView with cell renderers left us with a schism: widgets use one set of vfuncs and technologies for size allocation and rendering, and cell renderers use another. One of the unfortunate consequences of this split is that it is very hard to do animations in tree views (since cell renderers don’t keep state). Another is that most of the advances of the GTK CSS rendering machinery are unavailable in cell renderers. Therefore, we would really like to use widgets for displaying the data in lists. During the GTK 3 era, we have introduced a number of containers for this purpose: GtkListBox for lists, and GtkFlowBox for grids. They don’t use cell renderers, so the aforementioned limitations are not a concern. And they can even use list models to hold the data. But they generate a widget for each data item, and this severely limits their scalability. As a rule of thumb, GtkListBox can handle 1 000 items well, while GtkTreeView works fine for 100 000. Overcoming the scalability limitations, while still using widgets for all rendering has been on our roadmap for a long time. Scalability limits Widget Scalability GtkIconView 100 GtkListBox 1 000 GtkTreeView 100 000 GtkListView unlimited New infrastructure With list view family of widgets, we hope to finally achieve that. The goal is to handle unlimited numbers of items well. If you’ve worked with things like the Android recycler view, you will recognize the basic ideas behind list views: The data for items is provided in the form of a model (containing objects) Widgets are created just for the viewable range of items Widgets can be recycled by binding them to different items Avoid iterating over all items in the model as much as possible, and just deal with the items in the visible range which are bound to widgets Models For the model side of our model-view architecture, we’ve moved away from GtkTreeModel, and are now using GListModel. There are several reasons for this. One is that we want the items to be objects with properties, so we can use property bindings. Another one is that GtkTreeModel is not all that scalable in the first place (see e.g. this case of unintentional quadratic behavior). GTK 4 comes with a rich assortment of GListModel implementations, from various ways to combine or modify existing models to filtering and sorting. Filtering and sorting is supported by several GtkFilter and GtkSorter classes. Selections are also handled on the model side, with GtkSelectionModel and its subclasses. Finally, there are concrete models for the kinds of data that we are dealing with: GtkDirectoryList for files, PangoFontMap for fonts. APIs that have traditionally returns GLists of various items have been changed or supplemented with APIs returning a GListModel, for example gdk_display_get_monitors(), gtk_window_get_toplevels() and gtk_stack_get_pages(). Factories Since we are talking about automatically creating widgets on demand, there will be factories involved. GtkListItemFactory is the object that is tasked with creating widgets for the items in the model. There are different implementations of this factory. One of them, GtkBuilderListItemFactory, is using ui files as templates for the list item widgets. Here is a typical example: The full example can be found in gtk4-demo. Another list item factory implementation, GtkSignalListItemFactory, takes callbacks to setup, teardown, bind and unbind widgets from the items. static void setup_listitem_cb (GtkListItemFactory *factory, GtkListItem *list_item) { GtkWidget *image; image = gtk_image_new (); gtk_image_set_icon_size (GTK_IMAGE (image), GTK_ICON_SIZE_LARGE); gtk_list_item_set_child (list_item, image); } static void bind_listitem_cb (GtkListItemFactory *factory, GtkListItem *list_item) { GtkWidget *image; GAppInfo *app_info; image = gtk_list_item_get_child (list_item); app_info = gtk_list_item_get_item (list_item); gtk_image_set_from_gicon (GTK_IMAGE (image), g_app_info_get_icon (app_info)); } static void activate_cb (GtkListView *list, guint position, gpointer unused) { GListModel *model; GAppInfo *app_info; model = gtk_list_view_get_model (list); app_info = g_list_model_get_item (model, position); g_app_info_launch (app_info, NULL, NULL, NULL); g_object_unref (app_info); } ... factory = gtk_signal_list_item_factory_new (); g_signal_connect (factory, "setup", setup_listitem_cb, NULL); g_signal_connect (factory, "bind", bind_listitem_cb, NULL); list = gtk_list_view_new_with_factory (factory); g_signal_connect (list, "activate", activate_cb, NULL); model = create_application_list (); gtk_list_view_set_model (GTK_LIST_VIEW (list), model); g_object_unref (model); gtk_scrolled_window_set_child (GTK_SCROLLED_WINDOW (sw), list); The full example can be found here. Expressions To bind the widgets that are created by the factory to the data in your items, we need a flexible mechanism for binding properties. GObject’s GBinding mechanism goes in the right direction, but is not flexible enough to handle situations where you may need to bind properties of sub-objects or widgets deep inside the hierarchy of your widget, and where the objects in questions may not even exist at the time you are setting up the binding. To handle this, we’ve introduced GtkExpression as a more flexible binding system which can express things like: label = this->item->value where this is a GtkListItem, which has an item property (of type SettingsKey), whose value property we want to bind to the label property. Expressing the same in a GtkBuilder ui file looks a bit more unwieldy: GtkListItem New widgets GtkListView is a simple list, without columns or headers. An example where this kind of list is used is GtkFontChooser. One little way in which GtkListView breaks new ground is that it can be set up as a horizontal list, as well as the usual vertical orientation. GtkGridView puts the widgets in a reflowing grid, much like GtkFlowBox or GtkIconView. GtkColumnView is the equivalent of a full GtkTreeView, with multiple columns and headers, and features such as interactive resizing and reordering. Just like a GtkTreeView has GtkTreeViewColumns, a GtkColumnView has a list of GtkColumnViewColumns. Each column has a factory that produces a cell for each item. The cells are then combined into the row for the item. Examples Many of the lists in complex GTK dialogs (although not all yet) have been replaced with the new list widgets. For example, the font chooser is now using a GtkListView, and most of the lists in the GTK inspector use GtkColumnView. But gtk4-demo contains a number of examples for the new widgets. Here are a few: The clocks examples shows the advantages of having the full flexibility of widget rendering available. The colors example shows the a medium-size dataset rendered in various ways. The settings example shows that the column view more or less matches GtkTreeView, feature-wise. Summary This post gave an introduction to the new list widgets. There’s more that we haven’t touched on here, such as trees or the combo box replacement. One place to learn more about the new apis is the detailed introduction in the GTK documentation. We’ve merged the listview infrastructure to master now. That doesn’t mean that it is finished. But we think it is ready for some wider use, and we hope to get feedback from you on what works, what doesn’t and what is missing. And, to be clear, it also does not mean that we are removing treeviews and combo boxes from GTK 4—it is too late for that, and they are still used in many places inside GTK. That may be a GTK 5 goal.