OptionContainer¶

A container that can display multiple labeled tabs of content.

Usage¶

The content of an OptionContainer is a list of widgets that will form discrete tabs in the display. Each tab can be identified by a label, and, optionally, an icon. This list of content can be modified after initial construction:

import toga

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

# Create 2 initial tabs; one with an icon, and one without.
container = toga.OptionContainer(
    content=[("Pizza", pizza), ("Pasta", pasta, toga.Icon("pasta"))]
)

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

# Add another tab of content, with an icon
icecream = toga.Box()
container.content.append("Ice Cream", icecream, toga.Icon("icecream"))

OptionContainer content can also be specified by using toga.OptionItem instances instead of tuples. This enables you to be explicit when setting an icon or enabled status; it also allows you to set the initial enabled status without setting an icon:

import toga

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

# Create 2 initial tabs; one with an icon, and one without.
container = toga.OptionContainer(
    content=[`
      toga.OptionItem("Pizza", pizza),
      toga.OptionItem("Pasta", pasta, icon=toga.Icon("pasta"))
    ]
)

# Add another tab of content, initially disabled, without an icon.
salad = toga.Box()
container.content.append(toga.OptionItem("Salad", salad, enabled=False))

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 toga.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]

System requirements¶

Using OptionContainer on Android requires the Material package in your project's Gradle dependencies. Ensure your app declares a dependency on com.google.android.material:material:1.12.0 or later.

Notes¶

The use of icons on tabs varies between platforms. If the platform requires icons, and no icon is provided, a default icon will be used. If the platform does not support icons, any icon provided will be ignored, and requests to retrieve the icon will return None.
The behavior of disabled tabs varies between platforms. Some platforms will display the tab, but put it in an unselectable state; some will hide the tab. A hidden tab can still be referenced by index - the tab index refers to the logical order, not the visible order.
iOS can only display 5 tabs. If there are more than 5 visible tabs in an OptionContainer, the last item will be converted into a "More" option that will allow the user to select the additional items. While the "More" menu is displayed, the current tab will return as None.
Android can only display 5 tabs. The API will allow you to add more than 5 tabs, and will allow you to programmatically control tabs past the 5-item limit, but any tabs past the limit will not be displayed or be selectable by user interaction. If the OptionContainer has more than 5 tabs, and one of the visible tabs is removed, one of the previously unselectable tabs will become visible and selectable.
iOS allows the user to rearrange icons on an OptionContainer. When referring to tabs by index, user re-ordering is ignored; the logical order as configured in Toga itself is used to identify tabs.
Icons for iOS OptionContainer tabs should be 25x25px alpha masks.
Icons for Android OptionContainer tabs should be 24x24px alpha masks.

Reference¶

toga.OptionContainer ¶

OptionContainer(id=None, style=None, content=None, on_select=None, **kwargs)

Bases: Widget

Create a new OptionContainer.

PARAMETER	DESCRIPTION
`id`	The ID for the widget. TYPE: `str \| None` DEFAULT: `None`
`style`	A style object. If no style is provided, a default style will be applied to the widget. TYPE: `StyleT \| None` DEFAULT: `None`
`content`	The initial OptionContainer content to display in the OptionContainer. TYPE: `Iterable[OptionContainerContentT] \| None` DEFAULT: `None`
`on_select`	Initial `on_select` handler. TYPE: `OnSelectHandler \| None` DEFAULT: `None`
`kwargs`	Initial style properties. DEFAULT: `{}`

content `property` ¶

content

The tabs of content currently managed by the OptionContainer.

current_tab `property` `writable` ¶

current_tab

The currently selected tab of content, or None if there are no tabs, or the OptionContainer is in a state where no tab is currently selected.

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

enabled `property` `writable` ¶

enabled

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.

on_select `property` `writable` ¶

on_select

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

focus ¶

focus()

No-op; OptionContainer cannot accept input focus.

toga.OptionItem ¶

OptionItem(text, content, *, icon=None, enabled=True)

A tab of content in an OptionContainer.

PARAMETER	DESCRIPTION
`text`	The text label for the new tab. TYPE: `str`
`content`	The content widget to use for the new tab. TYPE: `Widget`
`icon`	The icon content to use to represent the tab. TYPE: `IconContentT \| None` DEFAULT: `None`
`enabled`	Should the new tab be enabled? TYPE: `bool` DEFAULT: `True`

content `property` ¶

content

The content widget displayed in this tab of the OptionContainer.

enabled `property` `writable` ¶

enabled

Is the panel of content available for selection?

icon `property` `writable` ¶

icon

The Icon for the tab of content.

Can be specified as any valid icon content.

If the platform does not support the display of icons, this property will return None regardless of any value provided.

index `property` ¶

index

The index of the tab in the OptionContainer.

Returns None if the tab isn't currently part of an OptionContainer.

interface `property` ¶

interface

The OptionContainer that contains this tab.

Returns None if the tab isn't currently part of an OptionContainer.

text `property` `writable` ¶

text

The label for the tab of content.

toga.widgets.optioncontainer.OptionList ¶

OptionList(interface)

delitem ¶

__delitem__(index)

Same as remove.

getitem ¶

__getitem__(index)

Obtain a specific tab of content.

len ¶

__len__()

The number of tabs of content in the OptionContainer.

append ¶

append(text_or_item: OptionItem) -> None

append(
    text_or_item: str,
    content: Widget,
    *,
    icon: IconContentT | None = None,
    enabled: bool | None = True,
) -> None

append(text_or_item, content=None, *, icon=None, enabled=None)

Add a new tab of content to the OptionContainer.

The new tab can be specified as an existing OptionItem instance, or by specifying the full details of the new tab of content. If an OptionItem is provided, specifying content, icon or enabled will raise an error.

PARAMETER	DESCRIPTION
`text_or_item`	An `OptionItem`; or, the text label for the new tab. TYPE: `str \| OptionItem`
`content`	The content widget to use for the new tab. TYPE: `Widget \| None` DEFAULT: `None`
`icon`	The icon content to use to represent the tab. TYPE: `IconContentT \| None` DEFAULT: `None`
`enabled`	Should the new tab be enabled? (Default: `True`) TYPE: `bool \| None` DEFAULT: `None`

index ¶

index(value)

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

PARAMETER	DESCRIPTION
`value`	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. TYPE: `str \| int \| OptionItem`

RAISES	DESCRIPTION
`ValueError`	If no tab matching the value can be found.

insert ¶

insert(index: int | str | OptionItem, text_or_item: OptionItem) -> None

insert(
    index: int | str | OptionItem,
    text_or_item: str,
    content: Widget,
    *,
    icon: IconContentT | None = None,
    enabled: bool | None = True,
) -> None

insert(index, text_or_item, content=None, *, icon=None, enabled=None)

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

The new tab can be specified as an existing OptionItem instance, or by specifying the full details of the new tab of content. If an OptionItem is provided, specifying content, icon or enabled will raise an error.

PARAMETER	DESCRIPTION
`index`	The index where the new tab should be inserted. TYPE: `int \| str \| OptionItem`
`text_or_item`	An `OptionItem`; or, the text label for the new tab. TYPE: `str \| OptionItem`
`content`	The content widget to use for the new tab. TYPE: `Widget \| None` DEFAULT: `None`
`icon`	The icon content to use to represent the tab. TYPE: `IconContentT \| None` DEFAULT: `None`
`enabled`	Should the new tab be enabled? (Default: `True`) TYPE: `bool \| None` DEFAULT: `None`

remove ¶

remove(index)

Remove the specified tab of content.

The currently selected item cannot be deleted.

PARAMETER	DESCRIPTION
`index`	The index where the new tab should be inserted. TYPE: `int \| str \| OptionItem`

toga.widgets.optioncontainer.OptionItem ¶

OptionItem(text, content, *, icon=None, enabled=True)

A tab of content in an OptionContainer.

PARAMETER	DESCRIPTION
`text`	The text label for the new tab. TYPE: `str`
`content`	The content widget to use for the new tab. TYPE: `Widget`
`icon`	The icon content to use to represent the tab. TYPE: `IconContentT \| None` DEFAULT: `None`
`enabled`	Should the new tab be enabled? TYPE: `bool` DEFAULT: `True`

content `property` ¶

content

The content widget displayed in this tab of the OptionContainer.

enabled `property` `writable` ¶

enabled

Is the panel of content available for selection?

icon `property` `writable` ¶

icon

The Icon for the tab of content.

Can be specified as any valid icon content.

If the platform does not support the display of icons, this property will return None regardless of any value provided.

index `property` ¶

index

The index of the tab in the OptionContainer.

Returns None if the tab isn't currently part of an OptionContainer.

interface `property` ¶

interface

The OptionContainer that contains this tab.

Returns None if the tab isn't currently part of an OptionContainer.

text `property` `writable` ¶

text

The label for the tab of content.

toga.widgets.optioncontainer.OnSelectHandler ¶

Bases: Protocol

call ¶

__call__(widget, **kwargs)

A handler that will be invoked when a new tab is selected in the OptionContainer.

PARAMETER	DESCRIPTION
`widget`	The OptionContainer that had a selection change. TYPE: `OptionContainer`
`kwargs`	Ensures compatibility with arguments added in future versions. TYPE: `Any` DEFAULT: `{}`

toga.widgets.optioncontainer.OptionContainerContentT `module-attribute` ¶

OptionContainerContentT

An item of content to add to an OptionContainer. This content can be:

a 2-tuple, containing the title for the tab, and the content widget;
a 3-tuple, containing the title, content widget, and icon for the tab;
a 4-tuple, containing the title, content widget, icon for the tab, and enabled status; or
an toga.OptionItem instance.

OptionContainer¶

Usage¶

System requirements¶

Notes¶

Reference¶

toga.OptionContainer ¶

content property ¶

current_tab property writable ¶

enabled property writable ¶

on_select property writable ¶

focus ¶

toga.OptionItem ¶

content property ¶

enabled property writable ¶

icon property writable ¶

index property ¶

interface property ¶

text property writable ¶

toga.widgets.optioncontainer.OptionList ¶

__delitem__ ¶

__getitem__ ¶

__len__ ¶

append ¶

index ¶

insert ¶

remove ¶

toga.widgets.optioncontainer.OptionItem ¶

content property ¶

enabled property writable ¶

icon property writable ¶

index property ¶

interface property ¶

text property writable ¶

toga.widgets.optioncontainer.OnSelectHandler ¶

__call__ ¶

toga.widgets.optioncontainer.OptionContainerContentT module-attribute ¶

content `property` ¶

current_tab `property` `writable` ¶

enabled `property` `writable` ¶

on_select `property` `writable` ¶

content `property` ¶

enabled `property` `writable` ¶

icon `property` `writable` ¶

index `property` ¶

interface `property` ¶

text `property` `writable` ¶

delitem ¶

getitem ¶

len ¶

content `property` ¶

enabled `property` `writable` ¶

icon `property` `writable` ¶

index `property` ¶

interface `property` ¶

text `property` `writable` ¶

call ¶

toga.widgets.optioncontainer.OptionContainerContentT `module-attribute` ¶