OptionContainer#

A container that can display multiple labeled tabs of content.

Usage#

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]

Reference#

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

Bases: Widget

Create a new OptionContainer.

Parameters:

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.

focus()#: 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)#

__delitem__(index)#: Same as remove.

__getitem__(index)#

Obtain a specific tab of content.

Return type:: OptionItem

append(text, widget, enabled=True)#

Add a new tab of content to the OptionContainer.

Parameters:

text (str) – The text label for the new tab
widget (Widget) – The content widget to use for the new tab.

index(value)#

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

Parameters:: 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.
Raises:: 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.

Parameters:

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(index)#

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.