You put the box inside another box…


Toga is a work in progress, and may not be consistent across all platforms.

Please check the Tutorial Issues label on Github to see what’s currently broken.

If you’ve done any GUI programming before, you will know that one of the biggest problems that any widget toolkit solves is how to put widgets on the screen in the right place. Different widget toolkits use different approaches - constraints, packing models, and grid-based models are all common. Toga’s Pack style engine borrows heavily from an approach that is new for widget toolkits, but well proven in computing: Cascading Style Sheets (CSS).

If you’ve done any design for the web, you will have come across CSS before as the mechanism that you use to lay out HTML on a web page. Although this is the reason CSS was developed, CSS itself is a general set of rules for laying out any “boxes” that are structured in a tree-like hierarchy. GUI widgets are an example of one such structure.

To see how this works in practice, lets look at a more complex example, involving layouts, scrollers, and containers inside other containers:


Here’s the source code:

import toga
from import COLUMN, Pack

def button_handler(widget):
    print('button handler')
    for i in range(0, 10):
        print("hello", i)
        yield 1
    print("done", i)

def action0(widget):
    print("action 0")

def action1(widget):
    print("action 1")

def action2(widget):
    print("action 2")

def action3(widget):
    print("action 3")

def build(app):
    brutus_icon = "icons/brutus"
    cricket_icon = "icons/cricket-72.png"

    data = [
        ('root%s' % i, 'value %s' % i)
        for i in range(1, 100)

    left_container = toga.Table(headings=['Hello', 'World'], data=data)

    right_content = toga.Box(
        style=Pack(direction=COLUMN, padding_top=50)

    for b in range(0, 10):
                'Hello world %s' % b,
                style=Pack(width=200, padding=20)

    right_container = toga.ScrollContainer(horizontal=False)

    right_container.content = right_content

    split = toga.SplitContainer()

    split.content = [left_container, right_container]

    things = toga.Group('Things')

    cmd0 = toga.Command(
        label='Action 0',
        tooltip='Perform action 0',
    cmd1 = toga.Command(
        label='Action 1',
        tooltip='Perform action 1',
    cmd2 = toga.Command(
        label='Action 2',
        tooltip='Perform action 2',
    cmd3 = toga.Command(
        label='Action 3',
        tooltip='Perform action 3',
        shortcut=toga.Key.MOD_1 + 'k',

    def action4(widget):
        print("CALLING Action 4")
        cmd3.enabled = not cmd3.enabled

    cmd4 = toga.Command(
        label='Action 4',
        tooltip='Perform action 4',

    app.commands.add(cmd1, cmd3, cmd4, cmd0)
    app.main_window.toolbar.add(cmd1, cmd2, cmd3, cmd4)

    return split

def main():
    return toga.App('First App', 'org.beeware.helloworld', startup=build)

if __name__ == '__main__':

In order to render the icons, you will need to move the icons folder into the same directory as your app file.

Here are the Icons

In this example, we see a couple of new Toga widgets - Table, SplitContainer, and ScrollContainer. You can also see that CSS styles can be added in the widget constructor. Lastly, you can see that windows can have toolbars.