Layout Containers#

While many GUI toolkits require you to precisely place widgets in a window, using absolute positioning, GTK uses a different approach. Rather than specifying the position and size of each widget in the window, you can arrange your widgets in rows, columns, and/or tables. The size of your window can be determined automatically, based on the sizes of the widgets it contains. And the sizes of the widgets are, in turn, determined by the amount of text they contain, or the minimum and maximum sizes that you specify, and/or how you have requested that the available space should be shared between sets of widgets. You can perfect your layout by specifying padding distance and centering values for each of your widgets. GTK then uses all this information to resize and reposition everything sensibly and smoothly when the user manipulates the window.

GTK widgets can parent other widgets hierarchically, and the way those widgets are displayed depend on the Gtk.LayoutManager set in the Gtk.Widget.props.layout_manager property. For ease of use, GTK provides “pre made” containers that have default layout managers for different needs. Most of these containers implement the Gtk.Orientable interface, it allows to set the widget orientation using Gtk.Orientable.props.orientation, you can either set Gtk.Orientation.HORIZONTAL or Gtk.Orientation.VERTICAL.

Some containers / layout managers like Gtk.Box allow you to influence the allocation of a child using the Gtk.Widget.props.halign, Gtk.Widget.props.valign, Gtk.Widget.props.hexpand and Gtk.Widget.props.vexpand properties.

The main container widgets are:

We are looking into each one in the following sections.

Boxes#

Boxes are invisible containers into which we can pack our widgets. When packing widgets into a horizontal box, the objects are inserted horizontally from left to right or right to left depending on whether Gtk.Box.prepend() or Gtk.Box.append() is used. You can also use the Gtk.Box.insert_child_after() or Gtk.Box.reorder_child_after() methods to insert a widget on a specific position. In a vertical box, widgets are packed from top to bottom or vice versa. You may use any combination of boxes inside or beside other boxes to create the desired effect.

Example#

Let’s take a look at a slightly modified version of the Extended Example with two buttons.

import gi

gi.require_version('Gtk', '4.0')
from gi.repository import Gtk


class MyWindow(Gtk.ApplicationWindow):
    def __init__(self, **kargs):
        super().__init__(**kargs, title='Hello World')

        box = Gtk.Box(spacing=6)
        self.set_child(box)

        button1 = Gtk.Button(label='Hello')
        button1.connect('clicked', self.on_button1_clicked)
        box.append(button1)

        button2 = Gtk.Button(label='Goodbye')
        button2.props.hexpand = True
        button2.connect('clicked', self.on_button2_clicked)
        box.append(button2)

    def on_button1_clicked(self, _widget):
        print('Hello')

    def on_button2_clicked(self, _widget):
        print('Goodbye')


def on_activate(app):
    # Create window
    win = MyWindow(application=app)
    win.present()


app = Gtk.Application(application_id='com.example.App')
app.connect('activate', on_activate)

app.run(None)

First, we create a horizontally orientated box container where 6 pixels are placed between children. This box becomes the child of the top-level window.

        box = Gtk.Box(spacing=6)
        self.set_child(box)

Subsequently, we add two different buttons to the box container.

        button1 = Gtk.Button(label='Hello')
        button1.connect('clicked', self.on_button1_clicked)
        box.append(button1)

        button2 = Gtk.Button(label='Goodbye')
        button2.props.hexpand = True
        button2.connect('clicked', self.on_button2_clicked)
        box.append(button2)

CenterBox#

Gtk.CenterBox arranges three children in a row or a column depending on its orientation, keeping the middle child centered as well as possible.

To add children you use Gtk.CenterBox.set_start_widget(), Gtk.CenterBox.set_center_widget(), and Gtk.CenterBox.set_end_widget().

Example#

import gi

gi.require_version('Gtk', '4.0')
from gi.repository import Gtk


class CenterBoxWindow(Gtk.ApplicationWindow):
    def __init__(self, **kargs):
        super().__init__(**kargs, default_width=400, title='CenterBox Example')

        box = Gtk.CenterBox()
        self.set_child(box)

        button1 = Gtk.Button(label='Start')
        box.set_start_widget(button1)

        label = Gtk.Label(label='Center')
        box.set_center_widget(label)

        button2 = Gtk.Button(label='End')
        box.set_end_widget(button2)


def on_activate(app):
    # Create window
    win = CenterBoxWindow(application=app)
    win.present()


app = Gtk.Application(application_id='com.example.App')
app.connect('activate', on_activate)

app.run(None)

HeaderBar#

A Gtk.HeaderBar is similar to a horizontal Gtk.CenterBox, it allows to place children at the start or the end. In addition, it allows a title to be displayed. The title will be centered with respect to the width of the box, even if the children at either side take up different amounts of space.

Gtk.HeaderBar is designed to be used as a window titlebar. This means that it can show typical window frame controls, such as minimize, maximize and close buttons, or the window icon. It is also draggable, meaning that you can move the parent window from it. You can use the Gtk.Window.set_titlebar() method to set it as so.

To add children you use Gtk.HeaderBar.pack_start(), Gtk.HeaderBar.pack_end(), and Gtk.HeaderBar.set_title_widget() for the center one. By default if no title_widget is set it will have a label with the window’s Gtk.Window.props.title.

Example#

import gi

gi.require_version('Gtk', '4.0')
from gi.repository import Gtk


class HeaderBarWindow(Gtk.ApplicationWindow):
    def __init__(self, **kargs):
        super().__init__(**kargs, default_width=400, title='HeaderBar Example')

        header_bar = Gtk.HeaderBar()
        self.set_titlebar(header_bar)

        button = Gtk.Button(label='Button')
        header_bar.pack_start(button)

        icon_button = Gtk.Button(icon_name='open-menu-symbolic')
        header_bar.pack_end(icon_button)


def on_activate(app):
    # Create window
    win = HeaderBarWindow(application=app)
    win.present()


app = Gtk.Application(application_id='com.example.App')
app.connect('activate', on_activate)

app.run(None)

Grid#

Gtk.Grid is a container which arranges its child widgets in rows and columns, but you do not need to specify the dimensions in the constructor. Children are added using Gtk.Grid.attach(). They can span multiple rows or columns. The Gtk.Grid.attach() method takes five parameters:

The child parameter is the Gtk.Widget to add.
left is the column number to attach the left side of child to.
top indicates the row number to attach the top side of child to.
width and height indicate the number of columns that the child will span, and the number of rows that the child will span, respectively.

It is also possible to add a child next to an existing child, using Gtk.Grid.attach_next_to(), which also takes five parameters:

child is the Gtk.Widget to add, as above.
sibling is an existing child widget of self (a Gtk.Grid instance) or None. The child widget will be placed next to sibling, or if sibling is None, at the beginning or end of the grid.
side is a Gtk.PositionType indicating the side of sibling that child is positioned next to.
width and height indicate the number of columns and rows the child widget will span, respectively.

Example#

import gi

gi.require_version('Gtk', '4.0')
from gi.repository import Gtk


class GridWindow(Gtk.ApplicationWindow):
    def __init__(self, **kargs):
        super().__init__(**kargs, title='Grid Example')

        button1 = Gtk.Button(label='Button 1')
        button2 = Gtk.Button(label='Button 2')
        button3 = Gtk.Button(label='Button 3')
        button4 = Gtk.Button(label='Button 4')
        button5 = Gtk.Button(label='Button 5')
        button6 = Gtk.Button(label='Button 6')

        grid = Gtk.Grid()
        grid.attach(button1, 0, 0, 1, 1)
        grid.attach(button2, 1, 0, 2, 1)
        grid.attach_next_to(button3, button1, Gtk.PositionType.BOTTOM, 1, 2)
        grid.attach_next_to(button4, button3, Gtk.PositionType.RIGHT, 2, 1)
        grid.attach(button5, 1, 2, 1, 1)
        grid.attach_next_to(button6, button5, Gtk.PositionType.RIGHT, 1, 1)

        self.set_child(grid)


def on_activate(app):
    # Create window
    win = GridWindow(application=app)
    win.present()


app = Gtk.Application(application_id='com.example.App')
app.connect('activate', on_activate)

app.run(None)

ListBox#

A Gtk.ListBox is a vertical container that contains Gtk.ListBoxRow children. These rows can be dynamically sorted and filtered, and headers can be added dynamically depending on the row content. It also allows keyboard and mouse navigation and selection like a typical list.

Although a Gtk.ListBox must have only Gtk.ListBoxRow children, you can add any kind of widget to it via Gtk.ListBox.append() or Gtk.ListBox.insert() and a Gtk.ListBoxRow widget will automatically be inserted between the list and the widget.

Gtk.ListBox allows activating and selecting its children. Selection can be configured with Gtk.ListBox.props.selection_mode, selection modes are Gtk.SelectionMode.NONE (not selection at all), Gtk.SelectionMode.SINGLE (one or none elements can be selected), Gtk.SelectionMode.BROWSE (user can’t deselect a currently selected element except by selecting another element) and Gtk.SelectionMode.MULTIPLE (any number of elements may be selected).

It will emit the row-activated signal when a row is activated in any form, and row-selected when a row is selected.

Example#

import gi

gi.require_version('Gtk', '4.0')
from gi.repository import Gtk


class ListBoxRowWithData(Gtk.ListBoxRow):
    def __init__(self, data):
        super().__init__()
        self.data = data
        self.set_child(Gtk.Label(label=data))


class ListBoxWindow(Gtk.ApplicationWindow):
    def __init__(self, **kargs):
        super().__init__(**kargs, default_width=400, title='ListBox Demo')

        # Main box of out window
        box_outer = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=24)
        box_outer.props.margin_start = 24
        box_outer.props.margin_end = 24
        box_outer.props.margin_top = 24
        box_outer.props.margin_bottom = 24
        self.set_child(box_outer)

        # Let's create our first ListBox
        listbox = Gtk.ListBox()
        listbox.props.selection_mode = Gtk.SelectionMode.NONE
        listbox.props.show_separators = True
        box_outer.append(listbox)

        # Let's create our first ListBoxRow
        row = Gtk.ListBoxRow()
        hbox = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=24)
        row.set_child(hbox)  # We set the Box as the ListBoxRow child
        vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
        hbox.append(vbox)
        label1 = Gtk.Label(label='Automatic Date & Time', xalign=0)
        label2 = Gtk.Label(label='Requires internet access', xalign=0)
        vbox.append(label1)
        vbox.append(label2)

        switch = Gtk.Switch()
        switch.props.hexpand = (
            True  # Lets make the Switch expand to the window width
        )
        switch.props.halign = Gtk.Align.END  # Horizontally aligned to the end
        switch.props.valign = (
            Gtk.Align.CENTER
        )  # Vertically aligned to the center
        hbox.append(switch)

        listbox.append(row)  # Add the row to the list

        # Our second row. We will omit the ListBoxRow and directly append a Box
        hbox = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=24)
        label = Gtk.Label(label='Enable Automatic Update', xalign=0)
        check = Gtk.CheckButton()
        check.props.hexpand = True
        check.props.halign = Gtk.Align.END
        hbox.append(label)
        hbox.append(check)
        listbox.append(hbox)  # Add the second row to the list

        # Let's create a second ListBox
        listbox_2 = Gtk.ListBox()
        box_outer.append(listbox_2)
        items = 'This is a sorted ListBox Fail'.split()

        # Populate the list
        for item in items:
            listbox_2.append(ListBoxRowWithData(item))

        # Set sorting and filter functions
        listbox_2.set_sort_func(self.sort_func)
        listbox_2.set_filter_func(self.filter_func)

        # Connect to "row-activated" signal
        listbox_2.connect('row-activated', self.on_row_activated)

    def sort_func(self, row_1, row_2):
        return row_1.data.lower() > row_2.data.lower()

    def filter_func(self, row):
        return False if row.data == 'Fail' else True

    def on_row_activated(self, _listbox, row):
        print(row.data)


def on_activate(app):
    # Create window
    win = ListBoxWindow(application=app)
    win.present()


app = Gtk.Application(application_id='com.example.App')
app.connect('activate', on_activate)

app.run(None)

FlowBox#

A Gtk.FlowBox is a container that positions child widgets in sequence according to its orientation.

For instance, with the horizontal orientation, the widgets will be arranged from left to right, starting a new row under the previous row when necessary. Reducing the width in this case will require more rows, so a larger height will be requested.

Likewise, with the vertical orientation, the widgets will be arranged from top to bottom, starting a new column to the right when necessary. Reducing the height will require more columns, so a larger width will be requested.

Gtk.FlowBox behaves similar to Gtk.ListBox, we could say that is its “grid” counterpart. Just like Gtk.ListBox, the children of a Gtk.FlowBox can be dynamically sorted and filtered, and also activated and selected.

Although a Gtk.FlowBox must have only Gtk.FlowBoxChild children, you can add any kind of widget to it via Gtk.FlowBox.append() or Gtk.FlowBox.insert(), and a Gtk.FlowBoxChild widget will automatically be inserted between the box and the widget.

Example#

import gi

gi.require_version('Gtk', '4.0')
from gi.repository import Gtk, Gdk


class FlowBoxWindow(Gtk.ApplicationWindow):
    def __init__(self, **kargs):
        super().__init__(**kargs, title='FlowBox Demo')

        self.set_default_size(300, 250)

        header = Gtk.HeaderBar()
        self.set_titlebar(header)

        scrolled = Gtk.ScrolledWindow()
        scrolled.set_policy(Gtk.PolicyType.NEVER, Gtk.PolicyType.AUTOMATIC)
        self.set_child(scrolled)

        flowbox = Gtk.FlowBox()
        flowbox.props.valign = Gtk.Align.START
        flowbox.props.max_children_per_line = 30
        flowbox.props.selection_mode = Gtk.SelectionMode.NONE
        scrolled.set_child(flowbox)

        self.create_flowbox(flowbox)

    def draw_button_color(self, area, cr, width, height, rgba):
        context = area.get_style_context()

        Gtk.render_background(context, cr, 0, 0, width, height)

        cr.set_source_rgba(rgba.red, rgba.green, rgba.blue, rgba.alpha)
        cr.rectangle(0, 0, width, height)
        cr.fill()

    def color_swatch_new(self, str_color):
        rgba = Gdk.RGBA()
        rgba.parse(str_color)

        button = Gtk.Button()

        area = Gtk.DrawingArea()
        area.set_size_request(24, 24)
        area.set_draw_func(self.draw_button_color, rgba)

        button.set_child(area)

        return button

    def create_flowbox(self, flowbox):
        colors = [
            'AliceBlue',
            'AntiqueWhite',
            'AntiqueWhite1',
            'AntiqueWhite2',
            'AntiqueWhite3',
            'AntiqueWhite4',
            'aqua',
            'aquamarine',
            'aquamarine1',
            'aquamarine2',
            'aquamarine3',
            'aquamarine4',
            'azure',
            'azure1',
            'azure2',
            'azure3',
            'azure4',
            'beige',
            'bisque',
            'bisque1',
            'bisque2',
            'bisque3',
            'bisque4',
            'black',
            'BlanchedAlmond',
            'blue',
            'blue1',
            'blue2',
            'blue3',
            'blue4',
            'BlueViolet',
            'brown',
            'brown1',
            'brown2',
            'brown3',
            'brown4',
            'burlywood',
            'burlywood1',
            'burlywood2',
            'burlywood3',
            'burlywood4',
            'CadetBlue',
            'CadetBlue1',
            'CadetBlue2',
            'CadetBlue3',
            'CadetBlue4',
            'chartreuse',
            'chartreuse1',
            'chartreuse2',
            'chartreuse3',
            'chartreuse4',
            'chocolate',
            'chocolate1',
            'chocolate2',
            'chocolate3',
            'chocolate4',
            'coral',
            'coral1',
            'coral2',
            'coral3',
            'coral4',
        ]

        for color in colors:
            button = self.color_swatch_new(color)
            button.props.tooltip_text = color
            flowbox.append(button)


def on_activate(app):
    # Create window
    win = FlowBoxWindow(application=app)
    win.present()


app = Gtk.Application(application_id='com.example.App')
app.connect('activate', on_activate)

app.run(None)

Stack and StackSwitcher#

A Gtk.Stack is a container which only shows one of its children at a time. In contrast to Gtk.Notebook, Gtk.Stack does not provide a means for users to change the visible child. Instead, the Gtk.StackSwitcher widget can be used with Gtk.Stack to provide this functionality.

Transitions between pages can be animated as slides or fades. This can be controlled with Gtk.Stack.props.transition_type. These animations respect the gtk-enable-animations setting.

Transition speed can be adjusted with Gtk.Stack.props.transition_duration.

The Gtk.StackSwitcher widget acts as a controller for a Gtk.Stack; it shows a row of buttons to switch between the various pages of the associated stack widget.

Gtk.Stack uses the auxiliary Gtk.StackPage object. Gtk.Stack will return a Gtk.StackPage every time you add a new children, either with Gtk.Stack.add_child(), Gtk.Stack.add_named() or Gtk.Stack.add_titled(). Gtk.StackPage holds important properties for the stack’s children, like the name, the title to display, or if the page needs attention, then this data can be used for example by Gtk.StackSwitcher.

It is possible to associate multiple Gtk.StackSwitcher widgets with the same Gtk.Stack widget.

Example#

import gi

gi.require_version('Gtk', '4.0')
from gi.repository import Gtk, GObject


class StackWindow(Gtk.ApplicationWindow):
    def __init__(self, **kargs):
        super().__init__(**kargs, title='Stack Demo')

        self.set_default_size(300, 250)

        header = Gtk.HeaderBar()
        self.set_titlebar(header)

        stack = Gtk.Stack()
        stack.props.transition_type = Gtk.StackTransitionType.SLIDE_LEFT_RIGHT
        stack.props.transition_duration = 1000
        self.set_child(stack)

        checkbutton = Gtk.CheckButton(label='Click me!')
        checkbutton.props.hexpand = True
        checkbutton.props.halign = Gtk.Align.CENTER
        page1 = stack.add_titled(checkbutton, 'check', 'Check Button')
        checkbutton.bind_property(
            'active', page1, 'needs-attention', GObject.BindingFlags.DEFAULT
        )

        label = Gtk.Label()
        label.set_markup('<big>A fancy label</big>')
        stack.add_titled(label, 'label', 'A label')

        stack_switcher = Gtk.StackSwitcher()
        stack_switcher.set_stack(stack)
        header.set_title_widget(stack_switcher)

        # Let's start in the second page
        stack.set_visible_child_name('label')


def on_activate(app):
    # Create window
    win = StackWindow(application=app)
    win.present()


app = Gtk.Application(application_id='com.example.App')
app.connect('activate', on_activate)

app.run(None)

Notebook#

The Gtk.Notebook is a container whose children are pages switched between using tabs.

There are many configuration options for GtkNotebook. Among other things, you can choose on which edge the tabs appear (see Gtk.Notebook.set_tab_pos()), whether, if there are too many tabs to fit the notebook should be made bigger or scrolling arrows added (see Gtk.Notebook.set_scrollable()), and whether there will be a popup menu allowing the users to switch pages (see Gtk.Notebook.popup_enable(), Gtk.Notebook.popup_disable()).

You can add children with Gtk.Notebook.append_page(), it takes two widgets, the first is the widget to show as a page, and the second is the widget to show as the tab content.

Example#

import gi

gi.require_version('Gtk', '4.0')
from gi.repository import Gtk


class NotebookWindow(Gtk.Window):
    def __init__(self, **kargs):
        super().__init__(**kargs, title='Simple Notebook Example')

        notebook = Gtk.Notebook()
        self.set_child(notebook)

        page1 = Gtk.Box()
        page1.append(Gtk.Label(label='Default Page!'))
        notebook.append_page(page1, Gtk.Label(label='Plain Title'))

        page2 = Gtk.Box()
        page2.append(Gtk.Label(label='A page with an image for a Title.'))
        notebook.append_page(page2, Gtk.Image(icon_name='help-about'))


def on_activate(app):
    # Create window
    win = NotebookWindow(application=app)
    win.present()


app = Gtk.Application(application_id='com.example.App')
app.connect('activate', on_activate)

app.run(None)