:right-sidebar: True ListView =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: ListView(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.ListBase`, :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`, :class:`~gi.repository.Gtk.Orientable`, :class:`~gi.repository.Gtk.Scrollable` ``GtkListView`` presents a large dynamic list of items. ``GtkListView`` uses its factory to generate one row widget for each visible item and shows them in a linear display, either vertically or horizontally. The :obj:`~gi.repository.Gtk.ListView.props.show_separators` property offers a simple way to display separators between the rows. ``GtkListView`` 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 :obj:`~gi.repository.Gtk.ListView.props.enable_rubberband`. If you need multiple columns with headers, see :obj:`~gi.repository.Gtk.ColumnView`. To learn more about the list widget framework, see the `overview `_. An example of using ``GtkListView``: .. code-block:: :dedent: 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) { GAppInfo *app_info; app_info = g_list_model_get_item (G_LIST_MODEL (gtk_list_view_get_model (list)), position); g_app_info_launch (app_info, NULL, NULL, NULL); g_object_unref (app_info); } ... model = create_application_list (); factory = gtk_signal_list_item_factory_new (); g_signal_connect (factory, "setup", G_CALLBACK (setup_listitem_cb), NULL); g_signal_connect (factory, "bind", G_CALLBACK (bind_listitem_cb), NULL); list = gtk_list_view_new (GTK_SELECTION_MODEL (gtk_single_selection_new (model)), factory); g_signal_connect (list, "activate", G_CALLBACK (activate_cb), NULL); gtk_scrolled_window_set_child (GTK_SCROLLED_WINDOW (sw), list); CSS nodes --------- .. code-block:: :dedent: listview[.separators][.rich-list][.navigation-sidebar][.data-table] ├── row[.activatable] │ ├── row[.activatable] │ ┊ ╰── [rubberband] ``GtkListView`` uses a single CSS node named ``listview``. It may carry the ``.separators`` style class, when :obj:`~gi.repository.Gtk.ListView.props.show_separators` property is set. Each child widget uses a single CSS node named ``row``. If the :obj:`~gi.repository.Gtk.ListItem.props.activatable` property is set, the corresponding row will have the ``.activatable`` style class. 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 `_: .rich-list, .navigation-sidebar or .data-table. Accessibility ------------- ``GtkListView`` uses the :const:`~gi.repository.Gtk.AccessibleRole.LIST` role, and the list items use the :const:`~gi.repository.Gtk.AccessibleRole.LIST_ITEM` role. Constructors ------------ .. rst-class:: interim-class .. class:: ListView :no-index: .. classmethod:: new(model: ~gi.repository.Gtk.SelectionModel | None = None, factory: ~gi.repository.Gtk.ListItemFactory | None = None) -> ~gi.repository.Gtk.Widget Creates a new ``GtkListView`` that uses the given ``factory`` for mapping items to widgets. The function takes ownership of the arguments, so you can write code like .. code-block:: :dedent: list_view = gtk_list_view_new (create_model (), gtk_builder_list_item_factory_new_from_resource ("/resource.ui")); :param model: the model to use :param factory: The factory to populate items with Methods ------- .. rst-class:: interim-class .. class:: ListView :no-index: .. method:: get_enable_rubberband() -> bool Returns whether rows can be selected by dragging with the mouse. .. method:: get_factory() -> ~gi.repository.Gtk.ListItemFactory | None Gets the factory that's currently used to populate list items. .. method:: get_header_factory() -> ~gi.repository.Gtk.ListItemFactory | None Gets the factory that's currently used to populate section headers. .. versionadded:: 4.12 .. method:: get_model() -> ~gi.repository.Gtk.SelectionModel | None Gets the model that's currently used to read the items displayed. .. method:: get_show_separators() -> bool Returns whether the list box should show separators between rows. .. method:: get_single_click_activate() -> bool Returns whether rows will be activated on single click and selected on hover. .. method:: get_tab_behavior() -> ~gi.repository.Gtk.ListTabBehavior Gets the behavior set for the :kbd:`Tab` key. .. versionadded:: 4.12 .. method:: scroll_to(pos: int, flags: ~gi.repository.Gtk.ListScrollFlags, scroll: ~gi.repository.Gtk.ScrollInfo | None = None) -> None Scrolls to the item at the given position and performs the actions specified in ``flags``. This function works no matter if the listview is shown or focused. If it isn't, then the changes will take effect once that happens. .. versionadded:: 4.12 :param pos: position of the item :param flags: actions to perform :param scroll: details of how to perform the scroll operation or :const:`None` to scroll into view .. method:: set_enable_rubberband(enable_rubberband: bool) -> None Sets whether selections can be changed by dragging with the mouse. :param enable_rubberband: :const:`True` to enable rubberband selection .. method:: set_factory(factory: ~gi.repository.Gtk.ListItemFactory | None = None) -> None Sets the ``GtkListItemFactory`` to use for populating list items. :param factory: the factory to use .. method:: set_header_factory(factory: ~gi.repository.Gtk.ListItemFactory | None = None) -> None Sets the ``GtkListItemFactory`` to use for populating the :obj:`~gi.repository.Gtk.ListHeader` objects used in section headers. If this factory is set to :const:`None`, the list will not show section headers. .. versionadded:: 4.12 :param factory: the factory to use .. method:: set_model(model: ~gi.repository.Gtk.SelectionModel | None = None) -> None Sets the model to use. This must be a :obj:`~gi.repository.Gtk.SelectionModel` to use. :param model: the model to use .. method:: set_show_separators(show_separators: bool) -> None Sets whether the list box should show separators between rows. :param show_separators: :const:`True` to show separators .. method:: set_single_click_activate(single_click_activate: bool) -> None Sets whether rows should be activated on single click and selected on hover. :param single_click_activate: :const:`True` to activate items on single click .. method:: set_tab_behavior(tab_behavior: ~gi.repository.Gtk.ListTabBehavior) -> None Sets the behavior of the :kbd:`Tab` and :kbd:`Shift`+:kbd:`Tab` keys. .. versionadded:: 4.12 :param tab_behavior: The desired tab behavior Properties ---------- .. rst-class:: interim-class .. class:: ListView :no-index: .. attribute:: props.enable_rubberband :type: bool Allow rubberband selection. .. attribute:: props.factory :type: ~gi.repository.Gtk.ListItemFactory Factory for populating list items. .. attribute:: props.header_factory :type: ~gi.repository.Gtk.ListItemFactory Factory for creating header widgets. .. versionadded:: 4.12 .. attribute:: props.model :type: ~gi.repository.Gtk.SelectionModel Model for the items displayed. .. attribute:: props.show_separators :type: bool Show separators between rows. .. attribute:: props.single_click_activate :type: bool Activate rows on single click and select them on hover. .. attribute:: props.tab_behavior :type: ~gi.repository.Gtk.ListTabBehavior Behavior of the :kbd:`Tab` key .. versionadded:: 4.12 Signals ------- .. rst-class:: interim-class .. class:: ListView.signals :no-index: .. method:: activate(position: int) -> None 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 listview. See :obj:`~gi.repository.Gtk.ListItem.set_activatable` for details on how to use this signal. :param position: position of item to activate