Gtk.Grid

Example

Subclasses:

None

Methods

Inherited:

Gtk.Widget (181), GObject.Object (37), Gtk.Accessible (15), Gtk.Buildable (1), Gtk.Orientable (2)

Structs:

Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	new ()
	attach (child, column, row, width, height)
	attach_next_to (child, sibling, side, width, height)
	get_baseline_row ()
	get_child_at (column, row)
	get_column_homogeneous ()
	get_column_spacing ()
	get_row_baseline_position (row)
	get_row_homogeneous ()
	get_row_spacing ()
	insert_column (position)
	insert_next_to (sibling, side)
	insert_row (position)
	query_child (child)
	remove (child)
	remove_column (position)
	remove_row (position)
	set_baseline_row (row)
	set_column_homogeneous (homogeneous)
	set_column_spacing (spacing)
	set_row_baseline_position (row, pos)
	set_row_homogeneous (homogeneous)
	set_row_spacing (spacing)

Virtual Methods

Inherited:

Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9)

Properties

Inherited:

Gtk.Widget (34), Gtk.Accessible (1), Gtk.Orientable (1)

Name	Type	Flags	Short Description
baseline-row	int	r/w/en
column-homogeneous	bool	r/w/en
column-spacing	int	r/w/en
row-homogeneous	bool	r/w/en
row-spacing	int	r/w/en

Signals

Inherited:

Gtk.Widget (13), GObject.Object (1)

Fields

Inherited:

Gtk.Widget (13), GObject.Object (1)

Name	Type	Access	Description
parent_instance	Gtk.Widget	r

Class Details

class Gtk.Grid(**kwargs)

Bases:

Gtk.Widget, Gtk.Orientable

Abstract:

No

Structure:

Gtk.GridClass

GtkGrid is a container which arranges its child widgets in rows and columns.

An example Gtk.Grid

It supports arbitrary positions and horizontal/vertical spans.

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

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

Gtk.Grid as Gtk.Buildable

Every child in a GtkGrid has access to a custom [iface`Gtk`.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 [class`Gtk`.GridLayoutChild].

It is implemented by GtkWidget using [class`Gtk`.LayoutManager].

To showcase it, here is a simple example:

``xml <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.

classmethod new()

Returns:

the new GtkGrid

Return type:

Gtk.Widget

Creates a new grid widget.

attach(child, column, row, width, height)

Parameters:

• child (Gtk.Widget) – the widget to add

• column (int) – the column number to attach the left side of child to

• row (int) – the row number to attach the top side of child to

• width (int) – the number of columns that child will span

• height (int) – the number of rows that child will span

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.

attach_next_to(child, sibling, side, width, height)

Parameters:

• child (Gtk.Widget) – the widget to add

• sibling (Gtk.Widget or None) – the child of self that child will be placed next to, or None to place child at the beginning or end

• side (Gtk.PositionType) – the side of sibling that child is positioned next to

• width (int) – the number of columns that child will span

• height (int) – the number of rows that child will span

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].

get_baseline_row()

Returns:

the row index defining the global baseline

Return type:

int

Returns which row defines the global baseline of self.

get_child_at(column, row)

Parameters:

• column (int) – the left edge of the cell

• row (int) – the top edge of the cell

Returns:

the child at the given position

Return type:

Gtk.Widget or None

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

get_column_homogeneous()

Returns:

whether all columns of self have the same width.

Return type:

bool

Returns whether all columns of self have the same width.

get_column_spacing()

Returns:

the column spacing of self

Return type:

int

Returns the amount of space between the columns of self.

get_row_baseline_position(row)

Parameters:

row (int) – a row index

Returns:

the baseline position of row

Return type:

Gtk.BaselinePosition

Returns the baseline position of row.

See [method`Gtk`.Grid.set_row_baseline_position].

get_row_homogeneous()

Returns:

whether all rows of self have the same height.

Return type:

bool

Returns whether all rows of self have the same height.

get_row_spacing()

Returns:

the row spacing of self

Return type:

int

Returns the amount of space between the rows of self.

insert_column(position)

Parameters:

position (int) – the position to insert the column at

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.

insert_next_to(sibling, side)

Parameters:

• sibling (Gtk.Widget) – the child of self that the new row or column will be placed next to

• side (Gtk.PositionType) – the side of sibling that child is positioned next to

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 Gtk.PositionType.TOP or Gtk.PositionType.BOTTOM, a row is inserted. If side is Gtk.PositionType.LEFT of Gtk.PositionType.RIGHT, a column is inserted.

insert_row(position)

Parameters:

position (int) – the position to insert the row at

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.

query_child(child)

Parameters:

child (Gtk.Widget) – a GtkWidget child of self

Returns:

column:

the column used to attach the left side of child

row:

the row used to attach the top side of child

width:

the number of columns child spans

height:

the number of rows child spans

Return type:

(column: int, row: int, width: int, height: int)

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

remove(child)

Parameters:

child (Gtk.Widget) – the child widget to remove

Removes a child from self.

The child must have been added with [method`Gtk`.Grid.attach] or [method`Gtk`.Grid.attach_next_to].

remove_column(position)

Parameters:

position (int) – the position of the column to remove

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.

remove_row(position)

Parameters:

position (int) – the position of the row to remove

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.

set_baseline_row(row)

Parameters:

row (int) – the row index

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 self.

set_column_homogeneous(homogeneous)

Parameters:

homogeneous (bool) – True to make columns homogeneous

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

set_column_spacing(spacing)

Parameters:

spacing (int) – the amount of space to insert between columns

Sets the amount of space between columns of self.

set_row_baseline_position(row, pos)

Parameters:

• row (int) – a row index

• pos (Gtk.BaselinePosition) – a GtkBaselinePosition

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 Gtk.BaselinePosition.CENTER.

set_row_homogeneous(homogeneous)

Parameters:

homogeneous (bool) – True to make rows homogeneous

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

set_row_spacing(spacing)

Parameters:

spacing (int) – the amount of space to insert between rows

Sets the amount of space between rows of self.

Property Details

Gtk.Grid.props.baseline_row

Name:

baseline-row

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

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

Gtk.Grid.props.column_homogeneous

Name:

column-homogeneous

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

If True, the columns are all the same width.

Gtk.Grid.props.column_spacing

Name:

column-spacing

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The amount of space between two consecutive columns.

Gtk.Grid.props.row_homogeneous

Name:

row-homogeneous

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

If True, the rows are all the same height.

Gtk.Grid.props.row_spacing

Name:

row-spacing

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The amount of space between two consecutive rows.