Quick search

Grid Layout

_images/gridlayout.gif

New in version 1.0.4.

GridLayout arranges children in a matrix. It takes the available space and divides it into columns and rows, then adds widgets to the resulting “cells”.

New in version 1.0.7: The implementation has changed to use widget size_hint for calculating column/row sizes. uniform_width and uniform_height have been removed, and others properties have added to give you more control.

Background

Unlike many other toolkits, you cannot explicitly place a widget at a specific column/row. Each child is automatically assigned a position, depending on the layout configuration and the child’s index in the children list.

A GridLayout must always have at least one input constraint: GridLayout.cols or GridLayout.rows. If you do not specify cols or rows, the Layout will throw an exception.

Column Width and Row Height

The column width/row height are determined in 3 steps:

  • The initial size is given by the col_default_width and row_default_height properties. To customize the size of a single column or row, use cols_minimum or rows_minimum.
  • Then the size_hint_x/size_hint_y of the child are taken into account. If no widgets have a size hint, the maximum size is used for all children.
  • You can force the default size by setting the col_force_default or row_force_default property. This will force the layout to ignore the width and size_hint properties of children and use the default size.

Usage of GridLayout

In the example below, all widgets will get an equal size. By default, size_hint is (1, 1), so a Widget will take the full size of the parent:

layout = GridLayout(cols=2)
layout.add_widget(Button(text='Hello 1'))
layout.add_widget(Button(text='World 1'))
layout.add_widget(Button(text='Hello 2'))
layout.add_widget(Button(text='World 2'))
_images/gridlayout_1.jpg

Now, let’s fix the size of Hello buttons to 100px instead of using size_hint 1:

layout = GridLayout(cols=2)
layout.add_widget(Button(text='Hello 1', size_hint_x=None, width=100))
layout.add_widget(Button(text='World 1'))
layout.add_widget(Button(text='Hello 2', size_hint_x=None, width=100))
layout.add_widget(Button(text='World 2'))
_images/gridlayout_2.jpg

Next, let’s fix the row height to a specific size:

layout = GridLayout(cols=2, row_force_default=True, row_default_height=40)
layout.add_widget(Button(text='Hello 1', size_hint_x=None, width=100))
layout.add_widget(Button(text='World 1'))
layout.add_widget(Button(text='Hello 2', size_hint_x=None, width=100))
layout.add_widget(Button(text='World 2'))
_images/gridlayout_3.jpg
class kivy.uix.gridlayout.GridLayout(**kwargs)

Bases: kivy.uix.layout.Layout

Grid layout class. See module documentation for more information.

col_default_width

Default minimum size to use for column.

New in version 1.0.7.

col_default_width is a NumericProperty, default to 0.

col_force_default

If True, ignore the width and size_hint_x of the child, and use the default column width.

New in version 1.0.7.

col_force_default is a BooleanProperty, default to False.

cols

Number of columns in the grid.

New in version 1.0.8.

cols is a NumericProperty, default to 0.

cols_minimum

List of minimum size for each column.

New in version 1.0.7.

cols_minimum is a DictProperty, default to {}

minimum_height

Minimum height needed to contain all children.

New in version 1.0.8.

minimum_height is a kivy.properties.NumericProperty, default to 0.

minimum_size

Minimum size needed to contain all children.

New in version 1.0.8.

minimum_size is a ReferenceListProperty of (minimum_width, minimum_height) properties.

minimum_width

Minimum width needed to contain all children.

New in version 1.0.8.

minimum_width is a kivy.properties.NumericProperty, default to 0.

padding

Padding between layout box and children: [padding_left, padding_top, padding_right, padding_bottom].

padding also accepts a two argument form [padding_horizontal, padding_vertical] and a one argument form [padding].

Changed in version 1.7.0.

Replaced NumericProperty with VariableListProperty.

padding is a VariableListProperty, default to [0, 0, 0, 0].

row_default_height

Default minimum size to use for row.

New in version 1.0.7.

row_default_height is a NumericProperty, default to 0.

row_force_default

If True, ignore the height and size_hint_y of the child, and use the default row height.

New in version 1.0.7.

row_force_default is a BooleanProperty, default to False.

rows

Number of rows in the grid.

New in version 1.0.8.

rows is a NumericProperty, default to 0.

rows_minimum

List of minimum size for each row.

New in version 1.0.7.

rows_minimum is a DictProperty, default to {}

spacing

Spacing between children: [spacing_horizontal, spacing_vertical].

spacing also accepts a one argument form [spacing].

spacing is a VariableListProperty, default to [0, 0].

class kivy.uix.gridlayout.GridLayoutException

Bases: exceptions.Exception

Exception for errors in the grid layout manipulation.