GI.Gtk.Objects.ListView

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 ListView:showSeparators 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 ListView:enableRubberband.

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:

c code

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 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 ListView:showSeparators property is set. Each child widget uses a single CSS node named row. If the 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 AccessibleRoleList role, and the list items use the AccessibleRoleListItem role.

Exported types

newtype ListView

Memory-managed wrapper type.

Constructors

ListView (ManagedPtr ListView)

Instances

Eq ListView

Defined in GI.Gtk.Objects.ListView

Methods

(==) :: ListView -> ListView -> Bool

(/=) :: ListView -> ListView -> Bool

GObject ListView

Defined in GI.Gtk.Objects.ListView

ManagedPtrNewtype ListView

Defined in GI.Gtk.Objects.ListView

Methods

toManagedPtr :: ListView -> ManagedPtr ListView

TypedObject ListView

Defined in GI.Gtk.Objects.ListView

Methods

glibType :: IO GType

HasParentTypes ListView

Defined in GI.Gtk.Objects.ListView

IsGValue (Maybe ListView)

Convert ListView to and from GValue. See toGValue and fromGValue.

Defined in GI.Gtk.Objects.ListView

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe ListView -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe ListView)

type ParentTypes ListView

Defined in GI.Gtk.Objects.ListView

type ParentTypes ListView = '[ListBase, Widget, Object, Accessible, Buildable, ConstraintTarget, Orientable, Scrollable]

class (GObject o, IsDescendantOf ListView o) => IsListView o

Type class for types which can be safely cast to ListView, for instance with toListView.

Instances

(GObject o, IsDescendantOf ListView o) => IsListView o

Defined in GI.Gtk.Objects.ListView

toListView :: (MonadIO m, IsListView o) => o -> m ListView

Cast to ListView, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

actionSetEnabled, activate, activateAction, activateDefault, addController, addCssClass, addMnemonicLabel, addTickCallback, allocate, announce, bindProperty, bindPropertyFull, childFocus, computeBounds, computeExpand, computePoint, computeTransform, contains, createPangoContext, createPangoLayout, disposeTemplate, dragCheckThreshold, errorBell, forceFloating, freezeNotify, getv, grabFocus, hasCssClass, hasDefault, hasFocus, hasVisibleFocus, hide, inDestruction, initTemplate, insertActionGroup, insertAfter, insertBefore, isAncestor, isDrawable, isFloating, isFocus, isSensitive, isVisible, keynavFailed, listMnemonicLabels, map, measure, mnemonicActivate, notify, notifyByPspec, observeChildren, observeControllers, pick, queueAllocate, queueDraw, queueResize, realize, ref, refSink, removeController, removeCssClass, removeMnemonicLabel, removeTickCallback, resetProperty, resetRelation, resetState, runDispose, scrollTo, shouldLayout, show, sizeAllocate, snapshotChild, stealData, stealQdata, thawNotify, translateCoordinates, triggerTooltipQuery, unmap, unparent, unrealize, unref, unsetStateFlags, updateNextAccessibleSibling, updateProperty, updateRelation, updateState, watchClosure.

Getters

getAccessibleParent, getAccessibleRole, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getAtContext, getBaseline, getBorder, getBounds, getBuildableId, getCanFocus, getCanTarget, getChildVisible, getClipboard, getColor, getCssClasses, getCssName, getCursor, getData, getDirection, getDisplay, getEnableRubberband, getFactory, getFirstAccessibleChild, getFirstChild, getFocusChild, getFocusOnClick, getFocusable, getFontMap, getFontOptions, getFrameClock, getHadjustment, getHalign, getHasTooltip, getHeaderFactory, getHeight, getHexpand, getHexpandSet, getHscrollPolicy, getLastChild, getLayoutManager, getMapped, getMarginBottom, getMarginEnd, getMarginStart, getMarginTop, getModel, getName, getNative, getNextAccessibleSibling, getNextSibling, getOpacity, getOrientation, getOverflow, getPangoContext, getParent, getPlatformState, getPreferredSize, getPrevSibling, getPrimaryClipboard, getProperty, getQdata, getRealized, getReceivesDefault, getRequestMode, getRoot, getScaleFactor, getSensitive, getSettings, getShowSeparators, getSingleClickActivate, getSize, getSizeRequest, getStateFlags, getStyleContext, getTabBehavior, getTemplateChild, getTooltipMarkup, getTooltipText, getVadjustment, getValign, getVexpand, getVexpandSet, getVisible, getVscrollPolicy, getWidth.

Setters

setAccessibleParent, setCanFocus, setCanTarget, setChildVisible, setCssClasses, setCursor, setCursorFromName, setData, setDataFull, setDirection, setEnableRubberband, setFactory, setFocusChild, setFocusOnClick, setFocusable, setFontMap, setFontOptions, setHadjustment, setHalign, setHasTooltip, setHeaderFactory, setHexpand, setHexpandSet, setHscrollPolicy, setLayoutManager, setMarginBottom, setMarginEnd, setMarginStart, setMarginTop, setModel, setName, setOpacity, setOrientation, setOverflow, setParent, setProperty, setReceivesDefault, setSensitive, setShowSeparators, setSingleClickActivate, setSizeRequest, setStateFlags, setTabBehavior, setTooltipMarkup, setTooltipText, setVadjustment, setValign, setVexpand, setVexpandSet, setVisible, setVscrollPolicy.

getEnableRubberband

listViewGetEnableRubberband

Arguments

:: (HasCallStack, MonadIO m, IsListView a)

=> a

self: a GtkListView

-> m Bool

Returns: True if rubberband selection is enabled

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

getFactory

listViewGetFactory

Arguments

:: (HasCallStack, MonadIO m, IsListView a)

=> a

self: a GtkListView

-> m (Maybe ListItemFactory)

Returns: The factory in use

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

getHeaderFactory

listViewGetHeaderFactory

Arguments

:: (HasCallStack, MonadIO m, IsListView a)

=> a

self: a GtkListView

-> m (Maybe ListItemFactory)

Returns: The factory in use

Gets the factory that's currently used to populate section headers.

Since: 4.12

getModel

listViewGetModel

Arguments

:: (HasCallStack, MonadIO m, IsListView a)

=> a

self: a GtkListView

-> m (Maybe SelectionModel)

Returns: The model in use

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

getShowSeparators

listViewGetShowSeparators

Arguments

:: (HasCallStack, MonadIO m, IsListView a)

=> a

self: a GtkListView

-> m Bool

Returns: True if the list box shows separators

Returns whether the list box should show separators between rows.

getSingleClickActivate

listViewGetSingleClickActivate

Arguments

:: (HasCallStack, MonadIO m, IsListView a)

=> a

self: a GtkListView

-> m Bool

Returns: True if rows are activated on single click

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

getTabBehavior

listViewGetTabBehavior

Arguments

:: (HasCallStack, MonadIO m, IsListView a)

=> a

self: a GtkListView

-> m ListTabBehavior

Returns: The behavior of the <kbd>Tab</kbd> key

Gets the behavior set for the <kbd>Tab</kbd> key.

Since: 4.12

new

listViewNew

Arguments

:: (HasCallStack, MonadIO m, IsSelectionModel a, IsListItemFactory b)

=> Maybe a

model: the model to use

-> Maybe b

factory: The factory to populate items with

-> m ListView

Returns: a new GtkListView using the given model and 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

c code

list_view = gtk_list_view_new (create_model (),
  gtk_builder_list_item_factory_new_from_resource ("/resource.ui"));

scrollTo

listViewScrollTo

Arguments

:: (HasCallStack, MonadIO m, IsListView a)

=> a

self: The listview to scroll in

-> Word32

pos: position of the item. Must be less than the number of items in the view.

-> [ListScrollFlags]

flags: actions to perform

-> Maybe ScrollInfo

scroll: details of how to perform the scroll operation or Nothing to scroll into view

-> m ()

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.

Since: 4.12

setEnableRubberband

listViewSetEnableRubberband

Arguments

:: (HasCallStack, MonadIO m, IsListView a)

=> a

self: a GtkListView

-> Bool

enableRubberband: True to enable rubberband selection

-> m ()

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

setFactory

listViewSetFactory

Arguments

:: (HasCallStack, MonadIO m, IsListView a, IsListItemFactory b)

=> a

self: a GtkListView

-> Maybe b

factory: the factory to use

-> m ()

Sets the GtkListItemFactory to use for populating list items.

setHeaderFactory

listViewSetHeaderFactory

Arguments

:: (HasCallStack, MonadIO m, IsListView a, IsListItemFactory b)

=> a

self: a GtkListView

-> Maybe b

factory: the factory to use

-> m ()

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

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

Since: 4.12

setModel

listViewSetModel

Arguments

:: (HasCallStack, MonadIO m, IsListView a, IsSelectionModel b)

=> a

self: a GtkListView

-> Maybe b

model: the model to use

-> m ()

Sets the model to use.

This must be a SelectionModel to use.

setShowSeparators

listViewSetShowSeparators

Arguments

:: (HasCallStack, MonadIO m, IsListView a)

=> a

self: a GtkListView

-> Bool

showSeparators: True to show separators

-> m ()

Sets whether the list box should show separators between rows.

setSingleClickActivate

listViewSetSingleClickActivate

Arguments

:: (HasCallStack, MonadIO m, IsListView a)

=> a

self: a GtkListView

-> Bool

singleClickActivate: True to activate items on single click

-> m ()

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

setTabBehavior

listViewSetTabBehavior

Arguments

:: (HasCallStack, MonadIO m, IsListView a)

=> a

self: a GtkListView

-> ListTabBehavior

tabBehavior: The desired tab behavior

-> m ()

Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys.

Since: 4.12

Properties

enableRubberband

Allow rubberband selection.

constructListViewEnableRubberband :: (IsListView o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “enable-rubberband” property. This is rarely needed directly, but it is used by new.

getListViewEnableRubberband :: (MonadIO m, IsListView o) => o -> m Bool

Get the value of the “enable-rubberband” property. When overloading is enabled, this is equivalent to

get listView #enableRubberband

setListViewEnableRubberband :: (MonadIO m, IsListView o) => o -> Bool -> m ()

Set the value of the “enable-rubberband” property. When overloading is enabled, this is equivalent to

set listView [ #enableRubberband := value ]

factory

Factory for populating list items.

The factory must be for configuring ListItem objects.

clearListViewFactory :: (MonadIO m, IsListView o) => o -> m ()

Set the value of the “factory” property to Nothing. When overloading is enabled, this is equivalent to

clear #factory

constructListViewFactory :: (IsListView o, MonadIO m, IsListItemFactory a) => a -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “factory” property. This is rarely needed directly, but it is used by new.

getListViewFactory :: (MonadIO m, IsListView o) => o -> m (Maybe ListItemFactory)

Get the value of the “factory” property. When overloading is enabled, this is equivalent to

get listView #factory

setListViewFactory :: (MonadIO m, IsListView o, IsListItemFactory a) => o -> a -> m ()

Set the value of the “factory” property. When overloading is enabled, this is equivalent to

set listView [ #factory := value ]

headerFactory

Factory for creating header widgets.

The factory must be for configuring ListHeader objects.

Since: 4.12

clearListViewHeaderFactory :: (MonadIO m, IsListView o) => o -> m ()

Set the value of the “header-factory” property to Nothing. When overloading is enabled, this is equivalent to

clear #headerFactory

constructListViewHeaderFactory :: (IsListView o, MonadIO m, IsListItemFactory a) => a -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “header-factory” property. This is rarely needed directly, but it is used by new.

getListViewHeaderFactory :: (MonadIO m, IsListView o) => o -> m (Maybe ListItemFactory)

Get the value of the “header-factory” property. When overloading is enabled, this is equivalent to

get listView #headerFactory

setListViewHeaderFactory :: (MonadIO m, IsListView o, IsListItemFactory a) => o -> a -> m ()

Set the value of the “header-factory” property. When overloading is enabled, this is equivalent to

set listView [ #headerFactory := value ]

model

Model for the items displayed.

clearListViewModel :: (MonadIO m, IsListView o) => o -> m ()

Set the value of the “model” property to Nothing. When overloading is enabled, this is equivalent to

clear #model

constructListViewModel :: (IsListView o, MonadIO m, IsSelectionModel a) => a -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “model” property. This is rarely needed directly, but it is used by new.

getListViewModel :: (MonadIO m, IsListView o) => o -> m (Maybe SelectionModel)

Get the value of the “model” property. When overloading is enabled, this is equivalent to

get listView #model

setListViewModel :: (MonadIO m, IsListView o, IsSelectionModel a) => o -> a -> m ()

Set the value of the “model” property. When overloading is enabled, this is equivalent to

set listView [ #model := value ]

showSeparators

Show separators between rows.

constructListViewShowSeparators :: (IsListView o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “show-separators” property. This is rarely needed directly, but it is used by new.

getListViewShowSeparators :: (MonadIO m, IsListView o) => o -> m Bool

Get the value of the “show-separators” property. When overloading is enabled, this is equivalent to

get listView #showSeparators

setListViewShowSeparators :: (MonadIO m, IsListView o) => o -> Bool -> m ()

Set the value of the “show-separators” property. When overloading is enabled, this is equivalent to

set listView [ #showSeparators := value ]

singleClickActivate

Activate rows on single click and select them on hover.

constructListViewSingleClickActivate :: (IsListView o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “single-click-activate” property. This is rarely needed directly, but it is used by new.

getListViewSingleClickActivate :: (MonadIO m, IsListView o) => o -> m Bool

Get the value of the “single-click-activate” property. When overloading is enabled, this is equivalent to

get listView #singleClickActivate

setListViewSingleClickActivate :: (MonadIO m, IsListView o) => o -> Bool -> m ()

Set the value of the “single-click-activate” property. When overloading is enabled, this is equivalent to

set listView [ #singleClickActivate := value ]

tabBehavior

Behavior of the <kbd>Tab</kbd> key

Since: 4.12

constructListViewTabBehavior :: (IsListView o, MonadIO m) => ListTabBehavior -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “tab-behavior” property. This is rarely needed directly, but it is used by new.

getListViewTabBehavior :: (MonadIO m, IsListView o) => o -> m ListTabBehavior

Get the value of the “tab-behavior” property. When overloading is enabled, this is equivalent to

get listView #tabBehavior

setListViewTabBehavior :: (MonadIO m, IsListView o) => o -> ListTabBehavior -> m ()

Set the value of the “tab-behavior” property. When overloading is enabled, this is equivalent to

set listView [ #tabBehavior := value ]

Signals

activate

type ListViewActivateCallback

Arguments

 = Word32

position: position of item to activate

-> IO ()

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 listItemSetActivatable for details on how to use this signal.

afterListViewActivate :: (IsListView a, MonadIO m) => a -> ((?self :: a) => ListViewActivateCallback) -> m SignalHandlerId

Connect a signal handler for the activate signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after listView #activate callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onListViewActivate :: (IsListView a, MonadIO m) => a -> ((?self :: a) => ListViewActivateCallback) -> m SignalHandlerId

Connect a signal handler for the activate signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on listView #activate callback