A container that can display multiple labeled tabs of content.



import toga

pizza = toga.Box()
pasta = toga.Box()

container = toga.OptionContainer(
    content=[("Pizza", pizza), ("Pasta", pasta)]

# Add another tab of content
salad = toga.Box()
container.content.append("Salad", salad)

When retrieving or deleting items, or when specifying the currently selected item, you can specify an item using:

  • The index of the item in the list of content:

    # Insert a new second tab
    container.content.insert(1, "Soup", toga.Box())
    # Make the third tab the currently active tab
    container.current_tab = 2
    # Delete the second tab
    del container.content[1]
  • The string label of the tab:

    # Insert a tab at the index currently occupied by a tab labeled "Pasta"
    container.content.insert("Pasta", "Soup", toga.Box())
    # Make the tab labeled "Pasta" the currently active tab
    container.current_tab = "Pasta"
    # Delete tab labeled "Pasta"
    del container.content["Pasta"]
  • A reference to an OptionItem:

    # Get a reference to the "Pasta" tab
    pasta_tab = container.content["Pasta"]
    # Insert content at the index currently occupied by the pasta tab
    container.content.insert(pasta_tab, "Soup", toga.Box())
    # Make the pasta tab the currently active tab
    container.current_tab = pasta_tab
    # Delete the pasta tab
    del container.content[pasta_tab]


class toga.OptionContainer(id=None, style=None, content=None, on_select=None)#

Bases: Widget

Create a new OptionContainer.

  • id – The ID for the widget.

  • style – A style object. If no style is provided, a default style will be applied to the widget.

  • content (list[tuple[str, Widget]] | None) – The initial content to display in the OptionContainer. A list of 2-tuples, each of which is the title for the option, and the content widget to display for that title.

  • on_select (callable | None) – Initial on_select handler.

property content: OptionList#

The tabs of content currently managed by the OptionContainer.

property current_tab: OptionItem | None#

The currently selected tab of content, or None if there are no tabs.

This property can also be set with an int index, or a str label.

property enabled: bool#

Is the widget currently enabled? i.e., can the user interact with the widget?

OptionContainer widgets cannot be disabled; this property will always return True; any attempt to modify it will be ignored.


No-op; OptionContainer cannot accept input focus

property on_select: callable#

The callback to invoke when a new tab of content is selected.

class toga.widgets.optioncontainer.OptionList(interface)#

Same as remove.


Obtain a specific tab of content.

Return type:


append(text, widget, enabled=True)#

Add a new tab of content to the OptionContainer.

  • text (str) – The text label for the new tab

  • widget (Widget) – The content widget to use for the new tab.


Find the index of the tab that matches the given value.


value (str | int | OptionItem) – The value to look for. An integer is returned as-is; if an OptionItem is provided, that item’s index is returned; any other value will be converted into a string, and the first tab with a label matching that string will be returned.


ValueError – If no tab matching the value can be found.

insert(index, text, widget, enabled=True)#

Insert a new tab of content to the OptionContainer at the specified index.

  • index (int | str | OptionItem) – The index where the new tab should be inserted.

  • text (str) – The text label for the new tab.

  • widget (Widget) – The content widget to use for the new tab.

  • enabled (bool) – Should the new tab be enabled?


Remove the specified tab of content.

The currently selected item cannot be deleted.

class toga.widgets.optioncontainer.OptionItem(interface, widget, index)#

A tab of content in an OptionContainer.

property content: Widget#

The content widget displayed in this tab of the OptionContainer.

property enabled: bool#

Is the panel of content available for selection?

property index: int#

The index of the tab in the OptionContainer.

property text: str#

The label for the tab of content.