Copyright	Will Thompson and Iñaki García Etxebarria
License	LGPL-2.1
Maintainer	Iñaki García Etxebarria
Safe Haskell	Safe-Inferred
Language	Haskell2010

GI.Gtk.Objects.ListView

Contents

Exported types
Methods
Properties
Signals
- activate

Description

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

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.

Synopsis

newtype ListView = ListView (ManagedPtr ListView)
class (GObject o, IsDescendantOf ListView o) => IsListView o
toListView :: (MonadIO m, IsListView o) => o -> m ListView
listViewGetEnableRubberband :: (HasCallStack, MonadIO m, IsListView a) => a -> m Bool
listViewGetFactory :: (HasCallStack, MonadIO m, IsListView a) => a -> m (Maybe ListItemFactory)
listViewGetHeaderFactory :: (HasCallStack, MonadIO m, IsListView a) => a -> m (Maybe ListItemFactory)
listViewGetModel :: (HasCallStack, MonadIO m, IsListView a) => a -> m (Maybe SelectionModel)
listViewGetShowSeparators :: (HasCallStack, MonadIO m, IsListView a) => a -> m Bool
listViewGetSingleClickActivate :: (HasCallStack, MonadIO m, IsListView a) => a -> m Bool
listViewGetTabBehavior :: (HasCallStack, MonadIO m, IsListView a) => a -> m ListTabBehavior
listViewNew :: (HasCallStack, MonadIO m, IsSelectionModel a, IsListItemFactory b) => Maybe a -> Maybe b -> m ListView
listViewScrollTo :: (HasCallStack, MonadIO m, IsListView a) => a -> Word32 -> [ListScrollFlags] -> Maybe ScrollInfo -> m ()
listViewSetEnableRubberband :: (HasCallStack, MonadIO m, IsListView a) => a -> Bool -> m ()
listViewSetFactory :: (HasCallStack, MonadIO m, IsListView a, IsListItemFactory b) => a -> Maybe b -> m ()
listViewSetHeaderFactory :: (HasCallStack, MonadIO m, IsListView a, IsListItemFactory b) => a -> Maybe b -> m ()
listViewSetModel :: (HasCallStack, MonadIO m, IsListView a, IsSelectionModel b) => a -> Maybe b -> m ()
listViewSetShowSeparators :: (HasCallStack, MonadIO m, IsListView a) => a -> Bool -> m ()
listViewSetSingleClickActivate :: (HasCallStack, MonadIO m, IsListView a) => a -> Bool -> m ()
listViewSetTabBehavior :: (HasCallStack, MonadIO m, IsListView a) => a -> ListTabBehavior -> m ()
constructListViewEnableRubberband :: (IsListView o, MonadIO m) => Bool -> m (GValueConstruct o)
getListViewEnableRubberband :: (MonadIO m, IsListView o) => o -> m Bool
setListViewEnableRubberband :: (MonadIO m, IsListView o) => o -> Bool -> m ()
clearListViewFactory :: (MonadIO m, IsListView o) => o -> m ()
constructListViewFactory :: (IsListView o, MonadIO m, IsListItemFactory a) => a -> m (GValueConstruct o)
getListViewFactory :: (MonadIO m, IsListView o) => o -> m (Maybe ListItemFactory)
setListViewFactory :: (MonadIO m, IsListView o, IsListItemFactory a) => o -> a -> m ()
clearListViewHeaderFactory :: (MonadIO m, IsListView o) => o -> m ()
constructListViewHeaderFactory :: (IsListView o, MonadIO m, IsListItemFactory a) => a -> m (GValueConstruct o)
getListViewHeaderFactory :: (MonadIO m, IsListView o) => o -> m (Maybe ListItemFactory)
setListViewHeaderFactory :: (MonadIO m, IsListView o, IsListItemFactory a) => o -> a -> m ()
clearListViewModel :: (MonadIO m, IsListView o) => o -> m ()
constructListViewModel :: (IsListView o, MonadIO m, IsSelectionModel a) => a -> m (GValueConstruct o)
getListViewModel :: (MonadIO m, IsListView o) => o -> m (Maybe SelectionModel)
setListViewModel :: (MonadIO m, IsListView o, IsSelectionModel a) => o -> a -> m ()
constructListViewShowSeparators :: (IsListView o, MonadIO m) => Bool -> m (GValueConstruct o)
getListViewShowSeparators :: (MonadIO m, IsListView o) => o -> m Bool
setListViewShowSeparators :: (MonadIO m, IsListView o) => o -> Bool -> m ()
constructListViewSingleClickActivate :: (IsListView o, MonadIO m) => Bool -> m (GValueConstruct o)
getListViewSingleClickActivate :: (MonadIO m, IsListView o) => o -> m Bool
setListViewSingleClickActivate :: (MonadIO m, IsListView o) => o -> Bool -> m ()
constructListViewTabBehavior :: (IsListView o, MonadIO m) => ListTabBehavior -> m (GValueConstruct o)
getListViewTabBehavior :: (MonadIO m, IsListView o) => o -> m ListTabBehavior
setListViewTabBehavior :: (MonadIO m, IsListView o) => o -> ListTabBehavior -> m ()
type ListViewActivateCallback = Word32 -> IO ()
afterListViewActivate :: (IsListView a, MonadIO m) => a -> ((?self :: a) => ListViewActivateCallback) -> m SignalHandlerId
onListViewActivate :: (IsListView a, MonadIO m) => a -> ((?self :: a) => ListViewActivateCallback) -> m SignalHandlerId

Exported types

newtype ListView Source #

Memory-managed wrapper type.

Constructors

ListView (ManagedPtr ListView)

Instances

Instances details

Eq ListView Source #
Instance details Defined in GI.Gtk.Objects.ListView Methods (==) :: ListView -> ListView -> Bool # (/=) :: ListView -> ListView -> Bool #
GObject ListView Source #
Instance details Defined in GI.Gtk.Objects.ListView
ManagedPtrNewtype ListView Source #
Instance details Defined in GI.Gtk.Objects.ListView Methods toManagedPtr :: ListView -> ManagedPtr ListView
TypedObject ListView Source #
Instance details Defined in GI.Gtk.Objects.ListView Methods glibType :: IO GType
HasParentTypes ListView Source #
Instance details Defined in GI.Gtk.Objects.ListView
IsGValue (Maybe ListView) Source #	Convert `ListView` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details 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 Source #
Instance details 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 Source #

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

Instances

Instances details

(GObject o, IsDescendantOf ListView o) => IsListView o Source #
Instance details Defined in GI.Gtk.Objects.ListView

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

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

Expand

getEnableRubberband

listViewGetEnableRubberband Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m, IsListView a)
=> a	`self`: The listview to scroll in
-> Word32	`pos`: position of the item
-> [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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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) Source #

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 Source #

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 () Source #

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.

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

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) Source #

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) Source #

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 () Source #

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.

Since: 4.12

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

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) Source #

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) Source #

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 () Source #

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 () Source #

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) Source #

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) Source #

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 () Source #

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) Source #

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 Source #

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 () Source #

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) Source #

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 Source #

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 () Source #

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) Source #

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 Source #

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 () Source #

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

set listView [ #tabBehavior := value ]

Signals

activate

type ListViewActivateCallback Source #

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 Source #

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 Source #

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

c code

CSS nodes

Accessibility

Exported types

Instances

Instances

Methods

Click to display all available methods, including inherited ones

Methods

Getters

Setters

getEnableRubberband

getFactory

getHeaderFactory

getModel

getShowSeparators

getSingleClickActivate

getTabBehavior

new

c code

scrollTo

setEnableRubberband

setFactory

setHeaderFactory

setModel

setShowSeparators

setSingleClickActivate

setTabBehavior

Properties

enableRubberband

factory

headerFactory

model

showSeparators

singleClickActivate

tabBehavior

Signals

activate