Class ListView

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.gnome.gtk.Widget
org.gnome.gtk.ListBase
org.gnome.gtk.ListView
All Implemented Interfaces:
Accessible, Buildable, ConstraintTarget, Orientable, Scrollable, Proxy
@Generated("org.javagi.JavaGI") public class ListView extends ListBase implements Accessible, Buildable, ConstraintTarget, Orientable, Scrollable

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 Gtk.ListView: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 Gtk.ListView:enable-rubberband.

If you need multiple columns with headers, see ColumnView.

To learn more about the list widget framework, see the overview.

An example of using GtkListView:

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);

Actions

GtkListView defines a set of built-in actions:

  • list.activate-item activates the item at given position by emitting the Gtk.ListView::activate signal.

CSS nodes

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 Gtk.ListView:show-separators property is set. Each child widget uses a single CSS node named row. If the Gtk.ListItem: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 Gtk.AccessibleRole.list role, and the list items use the Gtk.AccessibleRole.list_item role.

  • Constructor Details

    • ListView

      public ListView(MemorySegment address)
      Create a ListView instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • ListView

      public ListView(@Nullable SelectionModel model, @Nullable ListItemFactory factory)

      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

      list_view = gtk_list_view_new (create_model (),
  gtk_builder_list_item_factory_new_from_resource ("/resource.ui"));
      Parameters:
      model - the model to use
      factory - The factory to populate items with

    • ListView

      public ListView()
      Create a new ListView.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the ListView class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected ListView asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class ListBase
      Returns:
      the instance as if it were its parent type

    • getEnableRubberband

      public boolean getEnableRubberband()
      Returns whether rows can be selected by dragging with the mouse.
      Returns:
      true if rubberband selection is enabled

    • getFactory

      public @Nullable ListItemFactory getFactory()
      Gets the factory that's currently used to populate list items.
      Returns:
      The factory in use

    • getHeaderFactory

      public @Nullable ListItemFactory getHeaderFactory()
      Gets the factory that's currently used to populate section headers.
      Returns:
      The factory in use
      Since:
      4.12

    • getModel

      public @Nullable SelectionModel getModel()
      Gets the model that's currently used to read the items displayed.
      Returns:
      The model in use

    • getShowSeparators

      public boolean getShowSeparators()
      Returns whether the listview should show separators between rows.
      Returns:
      true if the listview shows separators

    • getSingleClickActivate

      public boolean getSingleClickActivate()
      Returns whether rows will be activated on single click and selected on hover.
      Returns:
      true if rows are activated on single click

    • getTabBehavior

      public ListTabBehavior getTabBehavior()
      Gets the behavior set for the Tab key.
      Returns:
      The behavior of the Tab key
      Since:
      4.12

    • scrollTo

      public void scrollTo(int pos, Set<ListScrollFlags> flags, @Nullable ScrollInfo scroll)

      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.

      Parameters:
      pos - position of the item. Must be less than the number of items in the view.
      flags - actions to perform
      scroll - details of how to perform the scroll operation or null to scroll into view
      Since:
      4.12

    • scrollTo

      public void scrollTo(int pos, ListScrollFlags flags, @Nullable ScrollInfo scroll)

      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.

      Parameters:
      pos - position of the item. Must be less than the number of items in the view.
      flags - actions to perform
      scroll - details of how to perform the scroll operation or null to scroll into view
      Since:
      4.12

    • setEnableRubberband

      public void setEnableRubberband(boolean enableRubberband)
      Sets whether selections can be changed by dragging with the mouse.
      Parameters:
      enableRubberband - whether to enable rubberband selection

    • setFactory

      public void setFactory(@Nullable ListItemFactory factory)
      Sets the GtkListItemFactory to use for populating list items.
      Parameters:
      factory - the factory to use

    • setHeaderFactory

      public void setHeaderFactory(@Nullable ListItemFactory factory)

      Sets the GtkListItemFactory to use for populating the ListHeader objects used in section headers.

      If this factory is set to NULL, the list will not show section headers.

      Parameters:
      factory - the factory to use
      Since:
      4.12

    • setModel

      public void setModel(@Nullable SelectionModel model)

      Sets the model to use.

      This must be a SelectionModel to use.

      Parameters:
      model - the model to use

    • setShowSeparators

      public void setShowSeparators(boolean showSeparators)
      Sets whether the listview should show separators between rows.
      Parameters:
      showSeparators - whether to show separators

    • setSingleClickActivate

      public void setSingleClickActivate(boolean singleClickActivate)
      Sets whether rows should be activated on single click and selected on hover.
      Parameters:
      singleClickActivate - whether to activate items on single click

    • setTabBehavior

      public void setTabBehavior(ListTabBehavior tabBehavior)

      Sets the Tab key behavior.

      This influences how the Tab and Shift+Tab keys move the focus in the listview.

      Parameters:
      tabBehavior - The desired tab behavior
      Since:
      4.12

    • onActivate

      public SignalConnection<ListView.ActivateCallback> onActivate(ListView.ActivateCallback handler)

      Emitted when a row has been activated by the user.

      Activation usually happens via the list.activate-item action of the GtkListView.

      This allows for a convenient way to handle activation in a listview. See ListItem.setActivatable(boolean) for details on how to use this signal.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitActivate

      public void emitActivate(int position)
      Emits the "activate" signal. See onActivate(ListView.ActivateCallback).

    • builder

      public static ListView.Builder<? extends ListView.Builder> builder()
      A ListView.Builder object constructs a ListView with the specified properties. Use the various set...() methods to set properties, and finish construction with ListView.Builder.build().
      Returns:
      the builder object