gtk:widget, gobject:initially-unowned, gtk:accessible, gtk:buildable, gtk:constraint-target, gtk:orientable, gobject:object, common-lisp:standard-object, common-lisp:t

None

The gtk:grid widget is a container which arranges its child widgets in rows and columns, with arbitrary positions and horizontal/vertical spans.


Figure: GtkGrid

Children are added using the gtk:grid-attach function. They can span multiple rows or columns. It is also possible to add a child widget next to an existing child widget, using the gtk:grid-attach-next-to function. To remove a child widget from the grid, use the gtk:grid-remove function. The behaviour of the gtk:grid widget when several children occupy the same grid cell is undefined. Every child in a gtk:grid widget has access to a custom 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 the gtk:grid-layout-child class.

It is implemented by the gtk:widget class using the gtk:layout-manager class.

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. The gtk:grid implementation uses a single CSS node with name grid. Until GTK 4.10, the gtk:grid implementation used the :group role of the gtk:accessible-role enumeration. Starting from GTK 4.12, it uses the :generic role.