GtkListView

GtkListView — A widget for displaying lists

Properties

gboolean enable-rubberband Read / Write
GtkListItemFactory * factory Read / Write
GListModel * model Read / Write
gboolean show-separators Read / Write
gboolean single-click-activate Read / Write

Signals

void activate Run Last

Actions

  list.activate-item u

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkListBase
                ╰── GtkListView

Implemented Interfaces

GtkListView implements AtkImplementorIface, GtkBuildable, GtkConstraintTarget, GtkOrientable and GtkScrollable.

Includes

#include <gtk/gtk.h>

Description

GtkListView is a widget to present a view into 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 “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. If the provided model is not a GtkSelectionModel, GtkListView will wrap it in a GtkSingleSelection. For models that allow multiple selected items, it is possible to turn on _rubberband selection_, using “enable-rubberband”.

If you need multiple columns with headers, see GtkColumnView.

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

An example of using GtkListView:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
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 (gtk_list_view_get_model (list), 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", G_CALLBACK (setup_listitem_cb), NULL);
  g_signal_connect (factory, "bind", G_CALLBACK (bind_listitem_cb), NULL);

  list = gtk_list_view_new_with_factory (factory);

  g_signal_connect (list, "activate", G_CALLBACK (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);

CSS nodes

1
2
3
4
5
6
7
listview[.separators]
├── row

├── row


╰── [rubberband]

GtkListView uses a single CSS node named listview. It may carry the .separators style class, when “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.

Functions

gtk_list_view_new ()

GtkWidget *
gtk_list_view_new (void);

Creates a new empty GtkListView.

You most likely want to call gtk_list_view_set_factory() to set up a way to map its items to widgets and gtk_list_view_set_model() to set a model to provide items next.

Returns

a new GtkListView


gtk_list_view_new_with_factory ()

GtkWidget *
gtk_list_view_new_with_factory (GtkListItemFactory *factory);

Creates a new GtkListView that uses the given factory for mapping items to widgets.

You most likely want to call gtk_list_view_set_model() to set a model next.

The function takes ownership of the argument, so you can write code like list_view = gtk_list_view_new_with_factory ( gtk_builder_list_item_factory_newfrom_resource ("/resource.ui"));

Parameters

factory

The factory to populate items with.

[transfer full]

Returns

a new GtkListView using the given factory


gtk_list_view_set_factory ()

void
gtk_list_view_set_factory (GtkListView *self,
                           GtkListItemFactory *factory);

Sets the GtkListItemFactory to use for populating list items.

Parameters

self

a GtkListView

 

factory

the factory to use or NULL for none.

[allow-none][transfer none]

gtk_list_view_get_factory ()

GtkListItemFactory *
gtk_list_view_get_factory (GtkListView *self);

Gets the factory that's currently used to populate list items.

Parameters

self

a GtkListView

 

Returns

The factory in use.

[nullable][transfer none]


gtk_list_view_set_model ()

void
gtk_list_view_set_model (GtkListView *self,
                         GListModel *model);

Sets the GListModel to use.

If the model is a GtkSelectionModel, it is used for managing the selection. Otherwise, self creates a GtkSingleSelection for the selection.

Parameters

self

a GtkListView

 

model

the model to use or NULL for none.

[allow-none][transfer none]

gtk_list_view_get_model ()

GListModel *
gtk_list_view_get_model (GtkListView *self);

Gets the model that's currently used to read the items displayed.

Parameters

self

a GtkListView

 

Returns

The model in use.

[nullable][transfer none]


gtk_list_view_set_show_separators ()

void
gtk_list_view_set_show_separators (GtkListView *self,
                                   gboolean show_separators);

Sets whether the list box should show separators between rows.

Parameters

self

a GtkListView

 

show_separators

TRUE to show separators

 

gtk_list_view_get_show_separators ()

gboolean
gtk_list_view_get_show_separators (GtkListView *self);

Returns whether the list box should show separators between rows.

Parameters

self

a GtkListView

 

Returns

TRUE if the list box shows separators


gtk_list_view_set_single_click_activate ()

void
gtk_list_view_set_single_click_activate
                               (GtkListView *self,
                                gboolean single_click_activate);

Sets whether rows should be activated on single click and selected on hover.

Parameters

self

a GtkListView

 

single_click_activate

TRUE to activate items on single click

 

gtk_list_view_get_single_click_activate ()

gboolean
gtk_list_view_get_single_click_activate
                               (GtkListView *self);

Returns whether rows will be activated on single click and selected on hover.

Parameters

self

a GtkListView

 

Returns

TRUE if rows are activated on single click


gtk_list_view_set_enable_rubberband ()

void
gtk_list_view_set_enable_rubberband (GtkListView *self,
                                     gboolean enable_rubberband);

Sets whether selections can be changed by dragging with the mouse.

Parameters

self

a GtkListView

 

enable_rubberband

TRUE to enable rubberband selection

 

gtk_list_view_get_enable_rubberband ()

gboolean
gtk_list_view_get_enable_rubberband (GtkListView *self);

Returns whether rows can be selected by dragging with the mouse.

Parameters

self

a GtkListView

 

Returns

TRUE if rubberband selection is enabled

Types and Values

GtkListView

typedef struct _GtkListView GtkListView;

GtkListView is the simple list implementation for GTK's list widgets.

Property Details

The “enable-rubberband” property

  “enable-rubberband”        gboolean

Allow rubberband selection

Owner: GtkListView

Flags: Read / Write

Default value: FALSE


The “factory” property

  “factory”                  GtkListItemFactory *

Factory for populating list items

Owner: GtkListView

Flags: Read / Write


The “model” property

  “model”                    GListModel *

Model for the items displayed

Owner: GtkListView

Flags: Read / Write


The “show-separators” property

  “show-separators”          gboolean

Show separators between rows

Owner: GtkListView

Flags: Read / Write

Default value: FALSE


The “single-click-activate” property

  “single-click-activate”    gboolean

Activate rows on single click and select them on hover

Owner: GtkListView

Flags: Read / Write

Default value: FALSE

Signal Details

The “activate” signal

void
user_function (GtkListView *self,
               guint        position,
               gpointer     user_data)

The ::activate 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 listview. See gtk_list_item_set_activatable() for details on how to use this signal.

Parameters

self

The GtkListView

 

position

position of item to activate

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Action Details

The “list.activate-item” action

Activates the item given in position by emitting the GtkListView::activate signal.

Parameter type: u

Parameters

position

position of item to activate

 

See Also

GListModel, GtkColumnView, GtkGridView