GridView

class GridView(**properties: Any)

Superclasses: ListBase, Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Buildable, ConstraintTarget, Orientable, Scrollable

GtkGridView presents a large dynamic grid of items.

GtkGridView uses its factory to generate one child widget for each visible item and shows them in a grid. The orientation of the grid view determines if the grid reflows vertically or horizontally.

GtkGridView 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 enable_rubberband.

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

CSS nodes

gridview
├── child[.activatable]
│
├── child[.activatable]
│
┊
╰── [rubberband]

GtkGridView uses a single CSS node with name gridview. Each child uses a single CSS node with name child. If the activatable property is set, the corresponding row will have the .activatable style class. For rubberband selection, a subnode with name rubberband is used.

Accessibility

GtkGridView uses the GRID role, and the items use the GRID_CELL role.

Constructors

class GridView

classmethod new(model: SelectionModel | None = None, factory: ListItemFactory | None = None) → Widget

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

The function takes ownership of the arguments, so you can write code like

grid_view = gtk_grid_view_new (create_model (),
  gtk_builder_list_item_factory_new_from_resource ("/resource.ui"));

Parameters:

model – the model to use
factory – The factory to populate items with

Methods

class GridView

get_enable_rubberband() → bool: Returns whether rows can be selected by dragging with the mouse.

get_factory() → ListItemFactory | None: Gets the factory that’s currently used to populate list items.

get_max_columns() → int: Gets the maximum number of columns that the grid will use.

get_min_columns() → int: Gets the minimum number of columns that the grid will use.

get_model() → SelectionModel | None: Gets the model that’s currently used to read the items displayed.

get_single_click_activate() → bool: Returns whether items will be activated on single click and selected on hover.

get_tab_behavior() → ListTabBehavior: Gets the behavior set for the Tab key.

Added in version 4.12.

scroll_to(pos: int, flags: ListScrollFlags, scroll: ScrollInfo | None = None) → None

Scrolls to the item at the given position and performs the actions specified in flags.

This function works no matter if the gridview is shown or focused. If it isn’t, then the changes will take effect once that happens.

Added in version 4.12.

Parameters:

pos – position of the item
flags – actions to perform
scroll – details of how to perform the scroll operation or None to scroll into view

set_enable_rubberband(enable_rubberband: bool) → None

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

Parameters:: enable_rubberband – True to enable rubberband selection

set_factory(factory: ListItemFactory | None = None) → None

Sets the GtkListItemFactory to use for populating list items.

Parameters:: factory – the factory to use

set_max_columns(max_columns: int) → None

Sets the maximum number of columns to use.

This number must be at least 1.

If max_columns is smaller than the minimum set via set_min_columns, that value is used instead.

Parameters:: max_columns – The maximum number of columns

set_min_columns(min_columns: int) → None

Sets the minimum number of columns to use.

This number must be at least 1.

If min_columns is smaller than the minimum set via set_max_columns, that value is ignored.

Parameters:: min_columns – The minimum number of columns

set_model(model: SelectionModel | None = None) → None

Sets the model to use.

This must be a SelectionModel.

Parameters:: model – the model to use

set_single_click_activate(single_click_activate: bool) → None

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

Parameters:: single_click_activate – True to activate items on single click

set_tab_behavior(tab_behavior: ListTabBehavior) → None

Sets the behavior of the Tab and Shift`+:kbd:`Tab keys.

Added in version 4.12.

Parameters:: tab_behavior – The desired tab behavior

Properties

class GridView

props.enable_rubberband: bool: Allow rubberband selection.

props.factory: ListItemFactory: Factory for populating list items.

props.max_columns: int

Maximum number of columns per row.

If this number is smaller than min_columns, that value is used instead.

props.min_columns: int: Minimum number of columns per row.

props.model: SelectionModel: Model for the items displayed.

props.single_click_activate: bool: Activate rows on single click and select them on hover.

props.tab_behavior: ListTabBehavior: Behavior of the Tab key

Added in version 4.12.

Signals

class GridView.signals

activate(position: int) → None

Emitted when a cell has been activated by the user, usually via activating the GtkGridView|list.activate-item action.

This allows for a convenient way to handle activation in a gridview. See activatable for details on how to use this signal.

Parameters:: position – position of item to activate