Skip to content

Gtk.GridView

class — extends ListBase, Accessible, Buildable, ConstraintTarget, Orientable, Scrollable

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 GridView.enable-rubberband.

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

Actions

GtkGridView defines a set of built-in actions:

  • list.activate-item activates the item at given position by emitting the the GridView.activate signal.

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 ListItem.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 AccessibleRole.grid role, and the items use the AccessibleRole.grid_cell role.

Constructors

new

@classmethod
def new(cls, model: SelectionModel | None = ..., factory: ListItemFactory | 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

get_enable_rubberband

def get_enable_rubberband(self) -> bool

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

get_factory

def get_factory(self) -> ListItemFactory | None

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

get_max_columns

def get_max_columns(self) -> int

Gets the maximum number of columns that the grid will use.

get_min_columns

def get_min_columns(self) -> int

Gets the minimum number of columns that the grid will use.

get_model

def get_model(self) -> SelectionModel | None

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

get_single_click_activate

def get_single_click_activate(self) -> bool

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

get_tab_behavior

def get_tab_behavior(self) -> ListTabBehavior

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

scroll_to

def scroll_to(self, pos: int, flags: ListScrollFlags | int, scroll: ScrollInfo | 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.

Parameters:

  • pos — position of the item. Must be less than the number of items in the view.
  • flags — actions to perform
  • scroll — details of how to perform the scroll operation or None to scroll into view

set_enable_rubberband

def set_enable_rubberband(self, 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

def set_factory(self, factory: ListItemFactory | None = ...) -> None

Sets the GtkListItemFactory to use for populating list items.

Parameters:

  • factory — the factory to use

set_max_columns

def set_max_columns(self, 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 GridView.set_min_columns, that value is used instead.

Parameters:

  • max_columns — The maximum number of columns

set_min_columns

def set_min_columns(self, 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 GridView.set_max_columns, that value is ignored.

Parameters:

  • min_columns — The minimum number of columns

set_model

def set_model(self, model: SelectionModel | None = ...) -> None

Sets the model to use.

This must be a SelectionModel.

Parameters:

  • model — the model to use

set_single_click_activate

def set_single_click_activate(self, 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

def set_tab_behavior(self, tab_behavior: ListTabBehavior | int) -> None

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

Parameters:

  • tab_behavior — The desired tab behavior

Properties

enable_rubberband

enable_rubberband: bool  # read/write

Allow rubberband selection.

factory

factory: ListItemFactory  # read/write

Factory for populating list items.

The factory must be for configuring ListItem objects.

max_columns

max_columns: int  # read/write

Maximum number of columns per row.

If this number is smaller than GridView.min-columns, that value is used instead.

min_columns

min_columns: int  # read/write

Minimum number of columns per row.

model

model: SelectionModel  # read/write

Model for the items displayed.

single_click_activate

single_click_activate: bool  # read/write

Activate rows on single click and select them on hover.

tab_behavior

tab_behavior: ListTabBehavior | int  # read/write

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

Signals

activate

def on_activate(self, 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 ListItem.activatable for details on how to use this signal.