Grid#
Superclasses: Widget
, InitiallyUnowned
, Object
Implemented Interfaces: Accessible
, Buildable
, ConstraintTarget
, Orientable
GtkGrid
is a container which arranges its child widgets in
rows and columns.
It supports arbitrary positions and horizontal/vertical spans.
Children are added using attach
. They can span multiple
rows or columns. It is also possible to add a child next to an existing
child, using attach_next_to
. To remove a child from the
grid, use 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 GTK_ACCESSIBLE_ROLE_GROUP
role.
Starting from GTK 4.12, GtkGrid
uses the GTK_ACCESSIBLE_ROLE_GENERIC
role.
Constructors#
Methods#
- class Grid
- attach(child: Widget, column: int, row: int, width: int, height: int) None #
Adds a widget to the grid.
The position of
child
is determined bycolumn
androw
. The number of “cells” thatchild
will occupy is determined bywidth
andheight
.- Parameters:
child – the widget to add
column – the column number to attach the left side of
child
torow – the row number to attach the top side of
child
towidth – the number of columns that
child
will spanheight – the number of rows that
child
will span
- attach_next_to(child: Widget, sibling: Widget | None, side: PositionType, width: int, height: int) None #
Adds a widget to the grid.
The widget is placed next to
sibling
, on the side determined byside
. Whensibling
isNone
, the widget is placed in row (for left or right placement) or column 0 (for top or bottom placement), at the end indicated byside
.Attaching widgets labeled
[1]
,[2]
,[3]
with`sibling
==None`
and`side
==LEFT`
yields a layout of[3][2][1]
.- Parameters:
child – the widget to add
sibling – the child of
grid
thatchild
will be placed next to, orNone
to placechild
at the beginning or endside – the side of
sibling
thatchild
is positioned next towidth – the number of columns that
child
will spanheight – the number of rows that
child
will span
- get_child_at(column: int, row: int) Widget | None #
Gets the child of
grid
whose area covers the grid cell atcolumn
,row
.- Parameters:
column – the left edge of the cell
row – the top edge of the cell
- get_row_baseline_position(row: int) BaselinePosition #
Returns the baseline position of
row
.See
set_row_baseline_position
.- Parameters:
row – a row index
- insert_column(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(sibling: Widget, side: PositionType) None #
Inserts a row or column at the specified position.
The new row or column is placed next to
sibling
, on the side determined byside
. Ifside
isTOP
orBOTTOM
, a row is inserted. Ifside
isLEFT
ofRIGHT
, a column is inserted.- Parameters:
sibling – the child of
grid
that the new row or column will be placed next toside – the side of
sibling
thatchild
is positioned next to
- insert_row(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(child: Widget) tuple[int, int, int, int] #
Queries the attach points and spans of
child
inside the givenGtkGrid
.- Parameters:
child – a
GtkWidget
child ofgrid
- remove(child: Widget) None #
Removes a child from
grid
.The child must have been added with
attach
orattach_next_to
.- Parameters:
child – the child widget to remove
- remove_column(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(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(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(homogeneous: bool) None #
Sets whether all columns of
grid
will have the same width.- Parameters:
homogeneous –
True
to make columns homogeneous
- set_column_spacing(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(row: int, pos: BaselinePosition) 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
CENTER
.- Parameters:
row – a row index
pos – a
GtkBaselinePosition
Properties#
- class Grid
Fields#
- class Grid
- parent_instance#