gi-gtk4-4.0.12: Gtk 4.x bindings

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

GI.Gtk.Objects.ListBox

Contents

- Exported types
- Methods
  - append
  - bindModel
  - dragHighlightRow
  - dragUnhighlightRow
  - getActivateOnSingleClick
  - getAdjustment
  - getRowAtIndex
  - getRowAtY
  - getSelectedRow
  - getSelectedRows
  - getSelectionMode
  - getShowSeparators
  - getTabBehavior
  - insert
  - invalidateFilter
  - invalidateHeaders
  - invalidateSort
  - new
  - prepend
  - remove
  - removeAll
  - selectAll
  - selectRow
  - selectedForeach
  - setActivateOnSingleClick
  - setAdjustment
  - setFilterFunc
  - setHeaderFunc
  - setPlaceholder
  - setSelectionMode
  - setShowSeparators
  - setSortFunc
  - setTabBehavior
  - unselectAll
  - unselectRow
- Properties
  - acceptUnpairedRelease
  - activateOnSingleClick
  - selectionMode
  - showSeparators
  - tabBehavior
- Signals
  - activateCursorRow
  - moveCursor
  - rowActivated
  - rowSelected
  - selectAll
  - selectedRowsChanged
  - toggleCursorRow
  - unselectAll

Description

Shows a vertical list.

<picture> <source srcset="list-box-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkListBox" src="list-box.png"> </picture>

A `GtkListBox` only contains `GtkListBoxRow` children. These rows can by dynamically sorted and filtered, and headers can be added dynamically depending on the row content. It also allows keyboard and mouse navigation and selection like a typical list.

Using `GtkListBox` is often an alternative to `GtkTreeView`, especially when the list contents has a more complicated layout than what is allowed by a `GtkCellRenderer`, or when the contents is interactive (i.e. has a button in it).

Although a `GtkListBox` must have only `GtkListBoxRow` children, you can add any kind of widget to it via `listBoxPrepend`, `listBoxAppend` and `listBoxInsert` and a `GtkListBoxRow` widget will automatically be inserted between the list and the widget.

`GtkListBoxRows` can be marked as activatable or selectable. If a row is activatable, ListBox::rowActivated will be emitted for it when the user tries to activate it. If it is selectable, the row will be marked as selected when the user tries to select it.

# GtkListBox as GtkBuildable

The `GtkListBox` implementation of the `GtkBuildable` interface supports setting a child as the placeholder by specifying “placeholder” as the “type” attribute of a `<child>` element. See `listBoxSetPlaceholder` for info.

# Shortcuts and Gestures

The following signals have default keybindings:

- ListBox::moveCursor
- ListBox::selectAll
- ListBox::toggleCursorRow
- ListBox::unselectAll

# CSS nodes

    list[.separators][.rich-list][.navigation-sidebar][.boxed-list]
    ╰── row[.activatable]

`GtkListBox` uses a single CSS node named list. It may carry the .separators style class, when the ListBox:showSeparators property is set. Each `GtkListBoxRow` uses a single CSS node named row. The row nodes get the .activatable style class added when appropriate.

It may also carry the .boxed-list style class. In this case, the list will be automatically surrounded by a frame and have separators.

The main list node may also carry style classes to select the style of list presentation: .rich-list, .navigation-sidebar or .data-table.

# Accessibility

`GtkListBox` uses the `AccessibleRoleList` role and `GtkListBoxRow` uses the `AccessibleRoleListItem` role.

Synopsis

- newtype ListBox = ListBox (ManagedPtr ListBox)
- class (GObject o, IsDescendantOf ListBox o) => IsListBox o
- toListBox :: (MonadIO m, IsListBox o) => o -> m ListBox
- listBoxAppend :: (HasCallStack, MonadIO m, IsListBox a, IsWidget b) => a -> b -> m ()
- listBoxBindModel :: (HasCallStack, MonadIO m, IsListBox a, IsListModel b) => a -> Maybe b -> Maybe ListBoxCreateWidgetFunc -> m ()
- listBoxDragHighlightRow :: (HasCallStack, MonadIO m, IsListBox a, IsListBoxRow b) => a -> b -> m ()
- listBoxDragUnhighlightRow :: (HasCallStack, MonadIO m, IsListBox a) => a -> m ()
- listBoxGetActivateOnSingleClick :: (HasCallStack, MonadIO m, IsListBox a) => a -> m Bool
- listBoxGetAdjustment :: (HasCallStack, MonadIO m, IsListBox a) => a -> m (Maybe Adjustment)
- listBoxGetRowAtIndex :: (HasCallStack, MonadIO m, IsListBox a) => a -> Int32 -> m (Maybe ListBoxRow)
- listBoxGetRowAtY :: (HasCallStack, MonadIO m, IsListBox a) => a -> Int32 -> m (Maybe ListBoxRow)
- listBoxGetSelectedRow :: (HasCallStack, MonadIO m, IsListBox a) => a -> m (Maybe ListBoxRow)
- listBoxGetSelectedRows :: (HasCallStack, MonadIO m, IsListBox a) => a -> m [ListBoxRow]
- listBoxGetSelectionMode :: (HasCallStack, MonadIO m, IsListBox a) => a -> m SelectionMode
- listBoxGetShowSeparators :: (HasCallStack, MonadIO m, IsListBox a) => a -> m Bool
- listBoxGetTabBehavior :: (HasCallStack, MonadIO m, IsListBox a) => a -> m ListTabBehavior
- listBoxInsert :: (HasCallStack, MonadIO m, IsListBox a, IsWidget b) => a -> b -> Int32 -> m ()
- listBoxInvalidateFilter :: (HasCallStack, MonadIO m, IsListBox a) => a -> m ()
- listBoxInvalidateHeaders :: (HasCallStack, MonadIO m, IsListBox a) => a -> m ()
- listBoxInvalidateSort :: (HasCallStack, MonadIO m, IsListBox a) => a -> m ()
- listBoxNew :: (HasCallStack, MonadIO m) => m ListBox
- listBoxPrepend :: (HasCallStack, MonadIO m, IsListBox a, IsWidget b) => a -> b -> m ()
- listBoxRemove :: (HasCallStack, MonadIO m, IsListBox a, IsWidget b) => a -> b -> m ()
- listBoxRemoveAll :: (HasCallStack, MonadIO m, IsListBox a) => a -> m ()
- listBoxSelectAll :: (HasCallStack, MonadIO m, IsListBox a) => a -> m ()
- listBoxSelectRow :: (HasCallStack, MonadIO m, IsListBox a, IsListBoxRow b) => a -> Maybe b -> m ()
- listBoxSelectedForeach :: (HasCallStack, MonadIO m, IsListBox a) => a -> ListBoxForeachFunc -> m ()
- listBoxSetActivateOnSingleClick :: (HasCallStack, MonadIO m, IsListBox a) => a -> Bool -> m ()
- listBoxSetAdjustment :: (HasCallStack, MonadIO m, IsListBox a, IsAdjustment b) => a -> Maybe b -> m ()
- listBoxSetFilterFunc :: (HasCallStack, MonadIO m, IsListBox a) => a -> Maybe ListBoxFilterFunc -> m ()
- listBoxSetHeaderFunc :: (HasCallStack, MonadIO m, IsListBox a) => a -> Maybe ListBoxUpdateHeaderFunc -> m ()
- listBoxSetPlaceholder :: (HasCallStack, MonadIO m, IsListBox a, IsWidget b) => a -> Maybe b -> m ()
- listBoxSetSelectionMode :: (HasCallStack, MonadIO m, IsListBox a) => a -> SelectionMode -> m ()
- listBoxSetShowSeparators :: (HasCallStack, MonadIO m, IsListBox a) => a -> Bool -> m ()
- listBoxSetSortFunc :: (HasCallStack, MonadIO m, IsListBox a) => a -> Maybe ListBoxSortFunc -> m ()
- listBoxSetTabBehavior :: (HasCallStack, MonadIO m, IsListBox a) => a -> ListTabBehavior -> m ()
- listBoxUnselectAll :: (HasCallStack, MonadIO m, IsListBox a) => a -> m ()
- listBoxUnselectRow :: (HasCallStack, MonadIO m, IsListBox a, IsListBoxRow b) => a -> b -> m ()
- constructListBoxAcceptUnpairedRelease :: (IsListBox o, MonadIO m) => Bool -> m (GValueConstruct o)
- getListBoxAcceptUnpairedRelease :: (MonadIO m, IsListBox o) => o -> m Bool
- setListBoxAcceptUnpairedRelease :: (MonadIO m, IsListBox o) => o -> Bool -> m ()
- constructListBoxActivateOnSingleClick :: (IsListBox o, MonadIO m) => Bool -> m (GValueConstruct o)
- getListBoxActivateOnSingleClick :: (MonadIO m, IsListBox o) => o -> m Bool
- setListBoxActivateOnSingleClick :: (MonadIO m, IsListBox o) => o -> Bool -> m ()
- constructListBoxSelectionMode :: (IsListBox o, MonadIO m) => SelectionMode -> m (GValueConstruct o)
- getListBoxSelectionMode :: (MonadIO m, IsListBox o) => o -> m SelectionMode
- setListBoxSelectionMode :: (MonadIO m, IsListBox o) => o -> SelectionMode -> m ()
- constructListBoxShowSeparators :: (IsListBox o, MonadIO m) => Bool -> m (GValueConstruct o)
- getListBoxShowSeparators :: (MonadIO m, IsListBox o) => o -> m Bool
- setListBoxShowSeparators :: (MonadIO m, IsListBox o) => o -> Bool -> m ()
- constructListBoxTabBehavior :: (IsListBox o, MonadIO m) => ListTabBehavior -> m (GValueConstruct o)
- getListBoxTabBehavior :: (MonadIO m, IsListBox o) => o -> m ListTabBehavior
- setListBoxTabBehavior :: (MonadIO m, IsListBox o) => o -> ListTabBehavior -> m ()
- type ListBoxActivateCursorRowCallback = IO ()
- afterListBoxActivateCursorRow :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxActivateCursorRowCallback) -> m SignalHandlerId
- onListBoxActivateCursorRow :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxActivateCursorRowCallback) -> m SignalHandlerId
- type ListBoxMoveCursorCallback = MovementStep -> Int32 -> Bool -> Bool -> IO ()
- afterListBoxMoveCursor :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxMoveCursorCallback) -> m SignalHandlerId
- onListBoxMoveCursor :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxMoveCursorCallback) -> m SignalHandlerId
- type ListBoxRowActivatedCallback = ListBoxRow -> IO ()
- afterListBoxRowActivated :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxRowActivatedCallback) -> m SignalHandlerId
- onListBoxRowActivated :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxRowActivatedCallback) -> m SignalHandlerId
- type ListBoxRowSelectedCallback = Maybe ListBoxRow -> IO ()
- afterListBoxRowSelected :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxRowSelectedCallback) -> m SignalHandlerId
- onListBoxRowSelected :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxRowSelectedCallback) -> m SignalHandlerId
- type ListBoxSelectAllCallback = IO ()
- afterListBoxSelectAll :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxSelectAllCallback) -> m SignalHandlerId
- onListBoxSelectAll :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxSelectAllCallback) -> m SignalHandlerId
- type ListBoxSelectedRowsChangedCallback = IO ()
- afterListBoxSelectedRowsChanged :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxSelectedRowsChangedCallback) -> m SignalHandlerId
- onListBoxSelectedRowsChanged :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxSelectedRowsChangedCallback) -> m SignalHandlerId
- type ListBoxToggleCursorRowCallback = IO ()
- afterListBoxToggleCursorRow :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxToggleCursorRowCallback) -> m SignalHandlerId
- onListBoxToggleCursorRow :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxToggleCursorRowCallback) -> m SignalHandlerId
- type ListBoxUnselectAllCallback = IO ()
- afterListBoxUnselectAll :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxUnselectAllCallback) -> m SignalHandlerId
- onListBoxUnselectAll :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxUnselectAllCallback) -> m SignalHandlerId

# Exported types

newtype ListBox Source #

Memory-managed wrapper type.

Constructors

ListBox (ManagedPtr ListBox) |

#### Instances

Instances details

Eq ListBox Source # |
Instance details Defined in GI.Gtk.Objects.ListBox Methods (==) :: ListBox -> ListBox -> Bool Source # (/=) :: ListBox -> ListBox -> Bool Source #
GObject ListBox Source # |
Instance details Defined in GI.Gtk.Objects.ListBox
ManagedPtrNewtype ListBox Source # |
Instance details Defined in GI.Gtk.Objects.ListBox Methods toManagedPtr :: ListBox -> ManagedPtr ListBox Source #
TypedObject ListBox Source # |
Instance details Defined in GI.Gtk.Objects.ListBox Methods glibType :: IO GType Source #
HasParentTypes ListBox Source # |
Instance details Defined in GI.Gtk.Objects.ListBox
IsGValue (Maybe ListBox) Source # | Convert `ListBox` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Objects.ListBox Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe ListBox -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe ListBox) Source #
type ParentTypes ListBox Source # |
Instance details Defined in GI.Gtk.Objects.ListBox type ParentTypes ListBox = '[Widget, Object, Accessible, Buildable, ConstraintTarget]

class (GObject o, IsDescendantOf ListBox o) => IsListBox o Source #

Type class for types which can be safely cast to `ListBox`, for instance with `toListBox`.

#### Instances

Instances details

(GObject o, IsDescendantOf ListBox o) => IsListBox o Source # |
Instance details Defined in GI.Gtk.Objects.ListBox

toListBox :: (MonadIO m, IsListBox o) => o -> m ListBox Source #

Cast to `ListBox`, 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

#### Methods

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

#### Getters

getAccessibleId, getAccessibleParent, getAccessibleRole, getActivateOnSingleClick, getAdjustment, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getAtContext, getBaseline, getBounds, getBuildableId, getCanFocus, getCanTarget, getChildVisible, getClipboard, getColor, getCssClasses, getCssName, getCursor, getData, getDirection, getDisplay, getFirstAccessibleChild, getFirstChild, getFocusChild, getFocusOnClick, getFocusable, getFontMap, getFontOptions, getFrameClock, getHalign, getHasTooltip, getHeight, getHexpand, getHexpandSet, getLastChild, getLayoutManager, getLimitEvents, getMapped, getMarginBottom, getMarginEnd, getMarginStart, getMarginTop, getName, getNative, getNextAccessibleSibling, getNextSibling, getOpacity, getOverflow, getPangoContext, getParent, getPlatformState, getPreferredSize, getPrevSibling, getPrimaryClipboard, getProperty, getQdata, getRealized, getReceivesDefault, getRequestMode, getRoot, getRowAtIndex, getRowAtY, getScaleFactor, getSelectedRow, getSelectedRows, getSelectionMode, getSensitive, getSettings, getShowSeparators, getSize, getSizeRequest, getStateFlags, getStyleContext, getTabBehavior, getTemplateChild, getTooltipMarkup, getTooltipText, getValign, getVexpand, getVexpandSet, getVisible, getWidth.

#### Setters

setAccessibleParent, setActivateOnSingleClick, setAdjustment, setCanFocus, setCanTarget, setChildVisible, setCssClasses, setCursor, setCursorFromName, setData, setDataFull, setDirection, setFilterFunc, setFocusChild, setFocusOnClick, setFocusable, setFontMap, setFontOptions, setHalign, setHasTooltip, setHeaderFunc, setHexpand, setHexpandSet, setLayoutManager, setLimitEvents, setMarginBottom, setMarginEnd, setMarginStart, setMarginTop, setName, setOpacity, setOverflow, setParent, setPlaceholder, setProperty, setReceivesDefault, setSelectionMode, setSensitive, setShowSeparators, setSizeRequest, setSortFunc, setStateFlags, setTabBehavior, setTooltipMarkup, setTooltipText, setValign, setVexpand, setVexpandSet, setVisible.

## append

listBoxAppend Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a, IsWidget b) |
=> a | `box`: a `GtkListBox`
-> b | `child`: the `GtkWidget` to add
-> m () |

Append a widget to the list.

If a sort function is set, the widget will actually be inserted at the calculated position.

## bindModel

listBoxBindModel Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a, IsListModel b) |
=> a | `box`: a `GtkListBox`
-> Maybe b | `model`: the `GListModel` to be bound to `box`
-> Maybe ListBoxCreateWidgetFunc | `createWidgetFunc`: a function that creates widgets for items or `Nothing` in case you also passed `Nothing` as `model`
-> m () |

Binds `model` to `box`.

If `box` was already bound to a model, that previous binding is destroyed.

The contents of `box` are cleared and then filled with widgets that represent items from `model`. `box` is updated whenever `model` changes. If `model` is `Nothing`, `box` is left empty.

It is undefined to add or remove widgets directly (for example, with `listBoxInsert`) while `box` is bound to a model.

Note that using a model is incompatible with the filtering and sorting functionality in `GtkListBox`. When using a model, filtering and sorting should be implemented by the model.

## dragHighlightRow

listBoxDragHighlightRow Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a, IsListBoxRow b) |
=> a | `box`: a `GtkListBox`
-> b | `row`: a `GtkListBoxRow`
-> m () |

Add a drag highlight to a row.

This is a helper function for implementing DnD onto a `GtkListBox`. The passed in `row` will be highlighted by setting the `StateFlagsDropActive` state and any previously highlighted row will be unhighlighted.

The row will also be unhighlighted when the widget gets a drag leave event.

## dragUnhighlightRow

listBoxDragUnhighlightRow Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> m () |

If a row has previously been highlighted via `listBoxDragHighlightRow`, it will have the highlight removed.

## getActivateOnSingleClick

listBoxGetActivateOnSingleClick Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> m Bool | Returns: `True` if rows are activated on single click, `False` otherwise

Returns whether rows activate on single clicks.

## getAdjustment

listBoxGetAdjustment Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> m (Maybe Adjustment) | Returns: the adjustment

Gets the adjustment (if any) that the widget uses to for vertical scrolling.

## getRowAtIndex

listBoxGetRowAtIndex Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> Int32 | `index_`: the index of the row
-> m (Maybe ListBoxRow) | Returns: the child `GtkWidget`

Gets the n-th child in the list (not counting headers).

If `index_` is negative or larger than the number of items in the list, `Nothing` is returned.

## getRowAtY

listBoxGetRowAtY Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> Int32 | `y`: position
-> m (Maybe ListBoxRow) | Returns: the row

Gets the row at the `y` position.

## getSelectedRow

listBoxGetSelectedRow Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> m (Maybe ListBoxRow) | Returns: the selected row

Gets the selected row, or `Nothing` if no rows are selected.

Note that the box may allow multiple selection, in which case you should use `listBoxSelectedForeach` to find all selected rows.

## getSelectedRows

listBoxGetSelectedRows Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> m [ListBoxRow] | Returns: A `GList` containing the `GtkWidget` for each selected child. Free with `g_list_free()` when done.

Creates a list of all selected children.

## getSelectionMode

listBoxGetSelectionMode Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> m SelectionMode | Returns: a `GtkSelectionMode`

Gets the selection mode of the listbox.

## getShowSeparators

listBoxGetShowSeparators Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> m Bool | Returns: `True` if the list box shows separators

Returns whether the list box should show separators between rows.

## getTabBehavior

listBoxGetTabBehavior Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> m ListTabBehavior | Returns: the tab behavior

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

Since: 4.18

## insert

listBoxInsert Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a, IsWidget b) |
=> a | `box`: a `GtkListBox`
-> b | `child`: the `GtkWidget` to add
-> Int32 | `position`: the position to insert `child` in
-> m () |

Insert the `child` into the `box` at `position`.

If a sort function is set, the widget will actually be inserted at the calculated position.

If `position` is -1, or larger than the total number of items in the `box`, then the `child` will be appended to the end.

## invalidateFilter

listBoxInvalidateFilter Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> m () |

Update the filtering for all rows.

Call this when result of the filter function on the `box` is changed due to an external factor. For instance, this would be used if the filter function just looked for a specific search string and the entry with the search string has changed.

## invalidateHeaders

listBoxInvalidateHeaders Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> m () |

Update the separators for all rows.

Call this when result of the header function on the `box` is changed due to an external factor.

## invalidateSort

listBoxInvalidateSort Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> m () |

Update the sorting for all rows.

Call this when result of the sort function on the `box` is changed due to an external factor.

## new

listBoxNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m ListBox | Returns: a new `GtkListBox`

Creates a new `GtkListBox` container.

## prepend

listBoxPrepend Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a, IsWidget b) |
=> a | `box`: a `GtkListBox`
-> b | `child`: the `GtkWidget` to add
-> m () |

Prepend a widget to the list.

If a sort function is set, the widget will actually be inserted at the calculated position.

## remove

listBoxRemove Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a, IsWidget b) |
=> a | `box`: a `GtkListBox`
-> b | `child`: the child to remove
-> m () |

Removes a child from `box`.

## removeAll

listBoxRemoveAll Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> m () |

Removes all rows from `box`.

This function does nothing if `box` is backed by a model.

Since: 4.12

## selectAll

listBoxSelectAll Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> m () |

Select all children of `box`, if the selection mode allows it.

## selectRow

listBoxSelectRow Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a, IsListBoxRow b) |
=> a | `box`: a `GtkListBox`
-> Maybe b | `row`: The row to select
-> m () |

Make `row` the currently selected row.

## selectedForeach

listBoxSelectedForeach Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> ListBoxForeachFunc | `func`: the function to call for each selected child
-> m () |

Calls a function for each selected child.

Note that the selection cannot be modified from within this function.

## setActivateOnSingleClick

listBoxSetActivateOnSingleClick Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> Bool | `single`: a boolean
-> m () |

If `single` is `True`, rows will be activated when you click on them, otherwise you need to double-click.

## setAdjustment

listBoxSetAdjustment Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a, IsAdjustment b) |
=> a | `box`: a `GtkListBox`
-> Maybe b | `adjustment`: the adjustment
-> m () |

Sets the adjustment (if any) that the widget uses to for vertical scrolling.

For instance, this is used to get the page size for PageUp/Down key handling.

In the normal case when the `box` is packed inside a `GtkScrolledWindow` the adjustment from that will be picked up automatically, so there is no need to manually do that.

## setFilterFunc

listBoxSetFilterFunc Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> Maybe ListBoxFilterFunc | `filterFunc`: callback that lets you filter which rows to show
-> m () |

By setting a filter function on the `box` one can decide dynamically which of the rows to show.

For instance, to implement a search function on a list that filters the original list to only show the matching rows.

The `filterFunc` will be called for each row after the call, and it will continue to be called each time a row changes (via `listBoxRowChanged`) or when `listBoxInvalidateFilter` is called.

Note that using a filter function is incompatible with using a model (see `listBoxBindModel`).

## setHeaderFunc

listBoxSetHeaderFunc Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> Maybe ListBoxUpdateHeaderFunc | `updateHeader`: callback that lets you add row headers
-> m () |

Sets a header function.

By setting a header function on the `box` one can dynamically add headers in front of rows, depending on the contents of the row and its position in the list.

For instance, one could use it to add headers in front of the first item of a new kind, in a list sorted by the kind.

The `updateHeader` can look at the current header widget using `listBoxRowGetHeader` and either update the state of the widget as needed, or set a new one using `listBoxRowSetHeader`. If no header is needed, set the header to `Nothing`.

Note that you may get many calls `updateHeader` to this for a particular row when e.g. changing things that don’t affect the header. In this case it is important for performance to not blindly replace an existing header with an identical one.

The `updateHeader` function will be called for each row after the call, and it will continue to be called each time a row changes (via `listBoxRowChanged`) and when the row before changes (either by `listBoxRowChanged` on the previous row, or when the previous row becomes a different row). It is also called for all rows when `listBoxInvalidateHeaders` is called.

## setPlaceholder

listBoxSetPlaceholder Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a, IsWidget b) |
=> a | `box`: a `GtkListBox`
-> Maybe b | `placeholder`: a `GtkWidget`
-> m () |

Sets the placeholder widget that is shown in the list when it doesn't display any visible children.

## setSelectionMode

listBoxSetSelectionMode Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> SelectionMode | `mode`: The `GtkSelectionMode`
-> m () |

Sets how selection works in the listbox.

## setShowSeparators

listBoxSetShowSeparators Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> Bool | `showSeparators`: `True` to show separators
-> m () |

Sets whether the list box should show separators between rows.

## setSortFunc

listBoxSetSortFunc Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> Maybe ListBoxSortFunc | `sortFunc`: the sort function
-> m () |

Sets a sort function.

By setting a sort function on the `box` one can dynamically reorder the rows of the list, based on the contents of the rows.

The `sortFunc` will be called for each row after the call, and will continue to be called each time a row changes (via `listBoxRowChanged`) and when `listBoxInvalidateSort` is called.

Note that using a sort function is incompatible with using a model (see `listBoxBindModel`).

## setTabBehavior

listBoxSetTabBehavior Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> ListTabBehavior | `behavior`: the tab behavior
-> m () |

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

Since: 4.18

## unselectAll

listBoxUnselectAll Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a) |
=> a | `box`: a `GtkListBox`
-> m () |

Unselect all children of `box`, if the selection mode allows it.

## unselectRow

listBoxUnselectRow Source #

Arguments

:: (HasCallStack, MonadIO m, IsListBox a, IsListBoxRow b) |
=> a | `box`: a `GtkListBox`
-> b | `row`: the row to unselect
-> m () |

Unselects a single row of `box`, if the selection mode allows it.

# Properties

## acceptUnpairedRelease

Whether to accept unpaired release events.

constructListBoxAcceptUnpairedRelease :: (IsListBox o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

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

getListBoxAcceptUnpairedRelease :: (MonadIO m, IsListBox o) => o -> m Bool Source #

Get the value of the “`accept-unpaired-release`” property. When overloading is enabled, this is equivalent to

    get listBox #acceptUnpairedRelease

setListBoxAcceptUnpairedRelease :: (MonadIO m, IsListBox o) => o -> Bool -> m () Source #

Set the value of the “`accept-unpaired-release`” property. When overloading is enabled, this is equivalent to

    set listBox [ #acceptUnpairedRelease := value ]

## activateOnSingleClick

Determines whether children can be activated with a single click, or require a double-click.

constructListBoxActivateOnSingleClick :: (IsListBox o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

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

getListBoxActivateOnSingleClick :: (MonadIO m, IsListBox o) => o -> m Bool Source #

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

    get listBox #activateOnSingleClick

setListBoxActivateOnSingleClick :: (MonadIO m, IsListBox o) => o -> Bool -> m () Source #

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

    set listBox [ #activateOnSingleClick := value ]

## selectionMode

The selection mode used by the list box.

constructListBoxSelectionMode :: (IsListBox o, MonadIO m) => SelectionMode -> m (GValueConstruct o) Source #

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

getListBoxSelectionMode :: (MonadIO m, IsListBox o) => o -> m SelectionMode Source #

Get the value of the “`selection-mode`” property. When overloading is enabled, this is equivalent to

    get listBox #selectionMode

setListBoxSelectionMode :: (MonadIO m, IsListBox o) => o -> SelectionMode -> m () Source #

Set the value of the “`selection-mode`” property. When overloading is enabled, this is equivalent to

    set listBox [ #selectionMode := value ]

## showSeparators

Whether to show separators between rows.

constructListBoxShowSeparators :: (IsListBox 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`.

getListBoxShowSeparators :: (MonadIO m, IsListBox o) => o -> m Bool Source #

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

    get listBox #showSeparators

setListBoxShowSeparators :: (MonadIO m, IsListBox o) => o -> Bool -> m () Source #

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

    set listBox [ #showSeparators := value ]

## tabBehavior

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

Since: 4.18

constructListBoxTabBehavior :: (IsListBox 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`.

getListBoxTabBehavior :: (MonadIO m, IsListBox o) => o -> m ListTabBehavior Source #

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

    get listBox #tabBehavior

setListBoxTabBehavior :: (MonadIO m, IsListBox o) => o -> ListTabBehavior -> m () Source #

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

    set listBox [ #tabBehavior := value ]

# Signals

## activateCursorRow

type ListBoxActivateCursorRowCallback = IO () Source #

Emitted when the cursor row is activated.

afterListBoxActivateCursorRow :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxActivateCursorRowCallback) -> m SignalHandlerId Source #

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

    after listBox #activateCursorRow 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.

onListBoxActivateCursorRow :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxActivateCursorRowCallback) -> m SignalHandlerId Source #

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

    on listBox #activateCursorRow callback

## moveCursor

type ListBoxMoveCursorCallback Source #

Arguments

= MovementStep | `step`: the granularity of the move, as a `GtkMovementStep`
-> Int32 | `count`: the number of `step` units to move
-> Bool | `extend`: whether to extend the selection
-> Bool | `modify`: whether to modify the selection
-> IO () |

Emitted when the user initiates a cursor movement.

The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifier does not. There are too many key combinations to list them all here.

- <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> move by individual children
- <kbd>Home</kbd>, <kbd>End</kbd> move to the ends of the box
- <kbd>PgUp</kbd>, <kbd>PgDn</kbd> move vertically by pages

afterListBoxMoveCursor :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxMoveCursorCallback) -> m SignalHandlerId Source #

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

    after listBox #moveCursor 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.

onListBoxMoveCursor :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxMoveCursorCallback) -> m SignalHandlerId Source #

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

    on listBox #moveCursor callback

## rowActivated

type ListBoxRowActivatedCallback Source #

Arguments

= ListBoxRow | `row`: the activated row
-> IO () |

Emitted when a row has been activated by the user.

afterListBoxRowActivated :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxRowActivatedCallback) -> m SignalHandlerId Source #

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

    after listBox #rowActivated 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.

onListBoxRowActivated :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxRowActivatedCallback) -> m SignalHandlerId Source #

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

    on listBox #rowActivated callback

## rowSelected

type ListBoxRowSelectedCallback Source #

Arguments

= Maybe ListBoxRow | `row`: the selected row
-> IO () |

Emitted when a new row is selected, or (with a `Nothing` `row`) when the selection is cleared.

When the `box` is using `SelectionModeMultiple`, this signal will not give you the full picture of selection changes, and you should use the ListBox::selectedRowsChanged signal instead.

afterListBoxRowSelected :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxRowSelectedCallback) -> m SignalHandlerId Source #

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

    after listBox #rowSelected 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.

onListBoxRowSelected :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxRowSelectedCallback) -> m SignalHandlerId Source #

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

    on listBox #rowSelected callback

## selectAll

type ListBoxSelectAllCallback = IO () Source #

Emitted to select all children of the box, if the selection mode permits it.

This is a keybinding signal.

The default binding for this signal is <kbd>Ctrl</kbd>-<kbd>a</kbd>.

afterListBoxSelectAll :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxSelectAllCallback) -> m SignalHandlerId Source #

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

    after listBox #selectAll 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.

onListBoxSelectAll :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxSelectAllCallback) -> m SignalHandlerId Source #

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

    on listBox #selectAll callback

## selectedRowsChanged

type ListBoxSelectedRowsChangedCallback = IO () Source #

Emitted when the set of selected rows changes.

afterListBoxSelectedRowsChanged :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxSelectedRowsChangedCallback) -> m SignalHandlerId Source #

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

    after listBox #selectedRowsChanged 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.

onListBoxSelectedRowsChanged :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxSelectedRowsChangedCallback) -> m SignalHandlerId Source #

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

    on listBox #selectedRowsChanged callback

## toggleCursorRow

type ListBoxToggleCursorRowCallback = IO () Source #

Emitted when the cursor row is toggled.

The default bindings for this signal is <kbd>Ctrl</kbd>+<kbd>␣</kbd>.

afterListBoxToggleCursorRow :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxToggleCursorRowCallback) -> m SignalHandlerId Source #

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

    after listBox #toggleCursorRow 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.

onListBoxToggleCursorRow :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxToggleCursorRowCallback) -> m SignalHandlerId Source #

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

    on listBox #toggleCursorRow callback

## unselectAll

type ListBoxUnselectAllCallback = IO () Source #

Emitted to unselect all children of the box, if the selection mode permits it.

This is a keybinding signal.

The default binding for this signal is <kbd>Ctrl</kbd>-<kbd>Shift</kbd>-<kbd>a</kbd>.

afterListBoxUnselectAll :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxUnselectAllCallback) -> m SignalHandlerId Source #

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

    after listBox #unselectAll 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.

onListBoxUnselectAll :: (IsListBox a, MonadIO m) => a -> ((?self :: a) => ListBoxUnselectAllCallback) -> m SignalHandlerId Source #

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

    on listBox #unselectAll callback