:right-sidebar: True

Grid
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: Grid(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`, :class:`~gi.repository.Gtk.Orientable`



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


.. image:: https://docs.gtk.org/gtk4/grid.png


It supports arbitrary positions and horizontal/vertical spans.

Children are added using :obj:`~gi.repository.Gtk.Grid.attach`. They can span multiple
rows or columns. It is also possible to add a child next to an existing
child, using :obj:`~gi.repository.Gtk.Grid.attach_next_to`. To remove a child from the
grid, use :obj:`~gi.repository.Gtk.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 :obj:`~gi.repository.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 :obj:`~gi.repository.Gtk.GridLayoutChild`.

It is implemented by ``GtkWidget`` using :obj:`~gi.repository.Gtk.LayoutManager`.

To showcase it, here is a simple example:


.. code-block::
   :dedent:

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

.. rst-class:: interim-class

.. class:: Grid
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gtk.Widget

      Creates a new grid widget.














Methods
-------

.. rst-class:: interim-class

.. class:: Grid
   :no-index:


   .. method:: attach(child: ~gi.repository.Gtk.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``.







      :param child: the widget to add


      :param column: the column number to attach the left side of ``child`` to


      :param row: the row number to attach the top side of ``child`` to


      :param width: the number of columns that ``child`` will span


      :param height: the number of rows that ``child`` will span





   .. method:: attach_next_to(child: ~gi.repository.Gtk.Widget, sibling: ~gi.repository.Gtk.Widget | None, side: ~gi.repository.Gtk.PositionType, 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 :const:`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`` == :const:`None`` and
      ```side`` == :const:`~gi.repository.Gtk.PositionType.LEFT`` yields a layout of ``[3][2][1]``.







      :param child: the widget to add


      :param sibling: the child of ``grid`` that ``child`` will be placed
         next to, or :const:`None` to place ``child`` at the beginning or end


      :param side: the side of ``sibling`` that ``child`` is positioned next to


      :param width: the number of columns that ``child`` will span


      :param height: the number of rows that ``child`` will span





   .. method:: get_baseline_row() -> int

      Returns which row defines the global baseline of ``grid``.










   .. method:: get_child_at(column: int, row: int) -> ~gi.repository.Gtk.Widget | None

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







      :param column: the left edge of the cell


      :param row: the top edge of the cell





   .. method:: get_column_homogeneous() -> bool

      Returns whether all columns of ``grid`` have the same width.










   .. method:: get_column_spacing() -> int

      Returns the amount of space between the columns of ``grid``.










   .. method:: get_row_baseline_position(row: int) -> ~gi.repository.Gtk.BaselinePosition

      Returns the baseline position of ``row``.

      See :obj:`~gi.repository.Gtk.Grid.set_row_baseline_position`.







      :param row: a row index





   .. method:: get_row_homogeneous() -> bool

      Returns whether all rows of ``grid`` have the same height.










   .. method:: get_row_spacing() -> int

      Returns the amount of space between the rows of ``grid``.










   .. method:: 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.







      :param position: the position to insert the column at





   .. method:: insert_next_to(sibling: ~gi.repository.Gtk.Widget, side: ~gi.repository.Gtk.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 by ``side``. If ``side`` is :const:`~gi.repository.Gtk.PositionType.TOP` or :const:`~gi.repository.Gtk.PositionType.BOTTOM`,
      a row is inserted. If ``side`` is :const:`~gi.repository.Gtk.PositionType.LEFT` of :const:`~gi.repository.Gtk.PositionType.RIGHT`,
      a column is inserted.







      :param sibling: the child of ``grid`` that the new row or column will be
         placed next to


      :param side: the side of ``sibling`` that ``child`` is positioned next to





   .. method:: 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.







      :param position: the position to insert the row at





   .. method:: query_child(child: ~gi.repository.Gtk.Widget) -> tuple[int, int, int, int]

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







      :param child: a ``GtkWidget`` child of ``grid``





   .. method:: remove(child: ~gi.repository.Gtk.Widget) -> None

      Removes a child from ``grid``.

      The child must have been added with
      :obj:`~gi.repository.Gtk.Grid.attach` or :obj:`~gi.repository.Gtk.Grid.attach_next_to`.







      :param child: the child widget to remove





   .. method:: 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.







      :param position: the position of the column to remove





   .. method:: 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.







      :param position: the position of the row to remove





   .. method:: 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``.







      :param row: the row index





   .. method:: set_column_homogeneous(homogeneous: bool) -> None

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







      :param homogeneous: :const:`True` to make columns homogeneous





   .. method:: set_column_spacing(spacing: int) -> None

      Sets the amount of space between columns of ``grid``.







      :param spacing: the amount of space to insert between columns





   .. method:: set_row_baseline_position(row: int, pos: ~gi.repository.Gtk.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 :const:`~gi.repository.Gtk.BaselinePosition.CENTER`.







      :param row: a row index


      :param pos: a ``GtkBaselinePosition``





   .. method:: set_row_homogeneous(homogeneous: bool) -> None

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







      :param homogeneous: :const:`True` to make rows homogeneous





   .. method:: set_row_spacing(spacing: int) -> None

      Sets the amount of space between rows of ``grid``.







      :param spacing: the amount of space to insert between rows









Properties
----------

.. rst-class:: interim-class

.. class:: Grid
   :no-index:
   

   .. attribute:: props.baseline_row
      :type: int

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







   .. attribute:: props.column_homogeneous
      :type: bool

      If :const:`True`, the columns are all the same width.







   .. attribute:: props.column_spacing
      :type: int

      The amount of space between two consecutive columns.







   .. attribute:: props.row_homogeneous
      :type: bool

      If :const:`True`, the rows are all the same height.







   .. attribute:: props.row_spacing
      :type: int

      The amount of space between two consecutive rows.















Fields
------

.. rst-class:: interim-class

.. class:: Grid
   :no-index:
   

   .. attribute:: parent_instance