Gtk.Grid¶

class — extends Widget, Accessible, Buildable, ConstraintTarget, Orientable

Arranges its child widgets in rows and columns.

It supports arbitrary positions and horizontal/vertical spans.

Children are added using Grid.attach. They can span multiple rows or columns. It is also possible to add a child next to an existing child, using Grid.attach_next_to. To remove a child from the grid, use Grid.remove.

The behaviour of GtkGrid when several children occupy the same grid cell is undefined.

GtkGrid as GtkBuildable¶

Every child in a GtkGrid has access to a custom Buildable element, called <layout>. It can by used to specify a position in the grid and optionally spans. All properties that can be used in the <layout> element are implemented by GridLayoutChild.

It is implemented by GtkWidget using LayoutManager.

To showcase it, here is a simple example:

<object class="GtkGrid" id="my_grid">
  <child>
    <object class="GtkButton" id="button1">
      <property name="label">Button 1</property>
      <layout>
        <property name="column">0</property>
        <property name="row">0</property>
      </layout>
    </object>
  </child>
  <child>
    <object class="GtkButton" id="button2">
      <property name="label">Button 2</property>
      <layout>
        <property name="column">1</property>
        <property name="row">0</property>
      </layout>
    </object>
  </child>
  <child>
    <object class="GtkButton" id="button3">
      <property name="label">Button 3</property>
      <layout>
        <property name="column">2</property>
        <property name="row">0</property>
        <property name="row-span">2</property>
      </layout>
    </object>
  </child>
  <child>
    <object class="GtkButton" id="button4">
      <property name="label">Button 4</property>
      <layout>
        <property name="column">0</property>
        <property name="row">1</property>
        <property name="column-span">2</property>
      </layout>
    </object>
  </child>
</object>

It organizes the first two buttons side-by-side in one cell each. The third button is in the last column but spans across two rows. This is defined by the row-span property. The last button is located in the second row and spans across two columns, which is defined by the column-span property.

CSS nodes¶

GtkGrid uses a single CSS node with name grid.

Accessibility¶

Until GTK 4.10, GtkGrid used the AccessibleRole.group role.

Starting from GTK 4.12, GtkGrid uses the AccessibleRole.generic role.

Constructors¶

new¶

@classmethod
def new(cls) -> Widget

Creates a new grid widget.

Methods¶

attach¶

def attach(self, child: Widget, column: int, row: int, width: int, height: int) -> None

Adds a widget to the grid.

The position of child is determined by column and row. The number of “cells” that child will occupy is determined by width and height.

Parameters:

child — the widget to add
column — the column number to attach the left side of child to
row — the row number to attach the top side of child to
width — the number of columns that child will span
height — the number of rows that child will span

attach_next_to¶

def attach_next_to(self, child: Widget, sibling: Widget | None, side: PositionType | int, width: int, height: int) -> None

Adds a widget to the grid.

The widget is placed next to sibling, on the side determined by side. When sibling is None, the widget is placed in row (for left or right placement) or column 0 (for top or bottom placement), at the end indicated by side.

Attaching widgets labeled [1], [2], [3] with @sibling == %NULL and @side == %GTK_POS_LEFT yields a layout of [3][2][1].

Parameters:

child — the widget to add
sibling — the child of grid that child will be placed next to, or None to place child at the beginning or end
side — the side of sibling that child is positioned next to
width — the number of columns that child will span
height — the number of rows that child will span

get_baseline_row¶

def get_baseline_row(self) -> int

Returns which row defines the global baseline of grid.

get_child_at¶

def get_child_at(self, column: int, row: int) -> Widget | None

Gets the child of grid whose area covers the grid cell at column, row.

Parameters:

column — the left edge of the cell
row — the top edge of the cell

get_column_homogeneous¶

def get_column_homogeneous(self) -> bool

Returns whether all columns of grid have the same width.

get_column_spacing¶

def get_column_spacing(self) -> int

Returns the amount of space between the columns of grid.

get_row_baseline_position¶

def get_row_baseline_position(self, row: int) -> BaselinePosition

Returns the baseline position of row.

See Grid.set_row_baseline_position.

Parameters:

row — a row index

get_row_homogeneous¶

def get_row_homogeneous(self) -> bool

Returns whether all rows of grid have the same height.

get_row_spacing¶

def get_row_spacing(self) -> int

Returns the amount of space between the rows of grid.

insert_column¶

def insert_column(self, position: int) -> None

Inserts a column at the specified position.

Children which are attached at or to the right of this position are moved one column to the right. Children which span across this position are grown to span the new column.

Parameters:

position — the position to insert the column at

insert_next_to¶

def insert_next_to(self, sibling: Widget, side: PositionType | int) -> None

Inserts a row or column at the specified position.

The new row or column is placed next to sibling, on the side determined by side. If side is PositionType.TOP or PositionType.BOTTOM, a row is inserted. If side is PositionType.LEFT of PositionType.RIGHT, a column is inserted.

Parameters:

sibling — the child of grid that the new row or column will be placed next to
side — the side of sibling that child is positioned next to

insert_row¶

def insert_row(self, position: int) -> None

Inserts a row at the specified position.

Children which are attached at or below this position are moved one row down. Children which span across this position are grown to span the new row.

Parameters:

position — the position to insert the row at

query_child¶

def query_child(self, child: Widget) -> tuple[int, int, int, int]

Queries the attach points and spans of child inside the given GtkGrid.

Parameters:

child — a GtkWidget child of grid

remove¶

def remove(self, child: Widget) -> None

Removes a child from grid.

The child must have been added with Grid.attach or Grid.attach_next_to.

Parameters:

child — the child widget to remove

remove_column¶

def remove_column(self, position: int) -> None

Removes a column from the grid.

Children that are placed in this column are removed, spanning children that overlap this column have their width reduced by one, and children after the column are moved to the left.

Parameters:

position — the position of the column to remove

remove_row¶

def remove_row(self, position: int) -> None

Removes a row from the grid.

Children that are placed in this row are removed, spanning children that overlap this row have their height reduced by one, and children below the row are moved up.

Parameters:

position — the position of the row to remove

set_baseline_row¶

def set_baseline_row(self, row: int) -> None

Sets which row defines the global baseline for the entire grid.

Each row in the grid can have its own local baseline, but only one of those is global, meaning it will be the baseline in the parent of the grid.

Parameters:

row — the row index

set_column_homogeneous¶

def set_column_homogeneous(self, homogeneous: bool) -> None

Sets whether all columns of grid will have the same width.

Parameters:

homogeneous — True to make columns homogeneous

set_column_spacing¶

def set_column_spacing(self, spacing: int) -> None

Sets the amount of space between columns of grid.

Parameters:

spacing — the amount of space to insert between columns

set_row_baseline_position¶

def set_row_baseline_position(self, row: int, pos: BaselinePosition | int) -> None

Sets how the baseline should be positioned on row of the grid, in case that row is assigned more space than is requested.

The default baseline position is BaselinePosition.CENTER.

Parameters:

row — a row index
pos — a GtkBaselinePosition

set_row_homogeneous¶

def set_row_homogeneous(self, homogeneous: bool) -> None

Sets whether all rows of grid will have the same height.

Parameters:

homogeneous — True to make rows homogeneous

set_row_spacing¶

def set_row_spacing(self, spacing: int) -> None

Sets the amount of space between rows of grid.

Parameters:

spacing — the amount of space to insert between rows

Properties¶

baseline_row¶

baseline_row: int  # read/write

The row to align to the baseline when valign is using baseline alignment.

column_homogeneous¶

column_homogeneous: bool  # read/write

If True, the columns are all the same width.

column_spacing¶

column_spacing: int  # read/write

The amount of space between two consecutive columns.

row_homogeneous¶

row_homogeneous: bool  # read/write

If True, the rows are all the same height.

row_spacing¶

row_spacing: int  # read/write

The amount of space between two consecutive rows.