The
gtk:list-view widget is a widget to present a view into a large
dynamic list of items. The
gtk:list-view widget uses its factory to generate one row widget
for each visible item and shows them in a linear display, either vertically or horizontally. The
show-separators property offers a
simple way to display separators between the rows.
The
gtk:list-view widget allows the user to select items according to
the selection characteristics of the model. For models that allow multiple
selected items, it is possible to turn on rubberband selection, using the
enable-rubberband property.
If you need multiple columns with headers, see the
gtk:column-view
widget.
To learn more about the list widget framework, see the List Widget Overview
section.
Examples
This is a complete example of how to use the
gtk:list-view widget.
The example is included in the GTK 4 demo, which comes with the
cl-cffi-gtk4 library.
(defun create-application-list ()
(let ((store (g:list-store-new "GAppInfo"))
(apps (g:app-info-all)))
(dolist (app apps)
(g:list-store-append store app))
store))
(defun do-list-view-applauncher (&optional application)
(let* ((factory (gtk:signal-list-item-factory-new))
(model (create-application-list))
(listview (gtk:list-view-new (gtk:single-selection-new model) factory))
(scrolled (gtk:scrolled-window-new))
(window (make-instance 'gtk:window
:title "Application launcher"
:application application
:child scrolled
:default-width 600
:default-height 380)))
(g:signal-connect factory "setup"
(lambda (factory item)
(declare (ignore factory))
(let ((box (gtk:box-new :horizontal 12))
(image (make-instance 'gtk:image
:icon-size :large)))
(gtk:box-append box image)
(gtk:box-append box (gtk:label-new ""))
(setf (gtk:list-item-child item) box))))
(g:signal-connect factory "bind"
(lambda (factory item)
(declare (ignore factory))
(let* ((image (gtk:widget-first-child (gtk:list-item-child item)))
(label (gtk:widget-next-sibling image))
(appinfo (gtk:list-item-item item)))
(gtk:image-set-from-gicon image (g:app-info-icon appinfo))
(setf (gtk:label-label label)
(g:app-info-display-name appinfo)))))
(g:signal-connect listview "activate"
(lambda (listview pos)
(let* ((model (gtk:list-view-model listview))
(appinfo (g:list-model-item model pos))
(display (gtk:widget-display listview))
(context (gdk:display-app-launch-context display)))
(unless (g:app-info-launch appinfo nil context)
(let* ((message (format nil "Could not launch ~a"
(g:app-info-display-name appinfo)))
(dialog (make-instance 'gtk:alert-dialog
:message message)))
(gtk:alert-dialog-show dialog (gtk:widget-root listview)))))))
(setf (gtk:scrolled-window-child scrolled) listview)
(gtk:window-present window))) Actions
The
gtk:list-view implementation defines a set of built-in actions:
- list.activate-item
- Activates the item at given position by emitting the GtkListView::activate signal.
CSS nodes
listview[.separators][.rich-list][.navigation-sidebar][.data-table]
├── row[.activatable]
│
├── row[.activatable]
│
┊
╰── [rubberband]
The
gtk:list-view implementation uses a single CSS node named
listview. It may carry the
.separators style class, when the
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
.rich-list,
.navigation-sidebar or
.data-table style
classes to select the style of list presentation.
Accessibility
The
gtk:list-view implementation uses the
:list role, and the list items use the
:list-item role of the
gtk:accessible-role enumeration.
Signal Details
The "activate" signal
lambda (listview position) :run-last
- listview
- The gtk:list-view widget.
- position
- The unsigned integer with the position of the item to activate.
The signal is emitted when a row has been activated by the user, usually via activating the
GtkListView::list.activate-item action. This
allows for a convenient way to handle activation in a list view. See the
gtk:list-item-activatable function for details on how to use this
signal.