OptionContainer

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.
• On iOS and Android, OptionContainer should only be used as the root content of a Window. Toga's API will allow the creation of an OptionContainer anywhere in a layout; but the behavior of the OptionContainer in those layouts is undefined. This includes adding an OptionContainer as a child of a Box, and nesting an OptionContainer inside another OptionContainer.
• On iOS:
  • OptionContainer 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.
  • The user can 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 OptionContainer tabs should be 25x25px alpha masks.
• On Android:
  • OptionContainer 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.
  • Icons for Android OptionContainer tabs should be 24x24px alpha masks.

Reference

Bases: Widget

Source code in core/src/toga/widgets/optioncontainer.py

class OptionContainer(Widget):
    _USE_DEBUG_BACKGROUND = True

    def __init__(
        self,
        id: str | None = None,
        style: StyleT | None = None,
        content: Iterable[OptionContainerContentT] | None = None,
        on_select: toga.widgets.optioncontainer.OnSelectHandler | None = None,
        **kwargs,
    ):
        """Create a new OptionContainer.

        :param id: The ID for the widget.
        :param style: A style object. If no style is provided, a default style will be
            applied to the widget.
        :param content: The initial
            [OptionContainer content][toga.widgets.optioncontainer.OptionContainerContentT]
            to display in the OptionContainer.
        :param on_select: Initial [`on_select`][toga.OptionContainer.on_select] handler.
        :param kwargs: Initial style properties.
        """  # noqa: E501
        self._content = OptionList(self)
        self.on_select = None

        super().__init__(id, style, **kwargs)

        if content is not None:
            for item in content:
                match item:
                    case OptionItem():
                        self.content.append(item)
                        continue
                    case text, widget:
                        icon = None
                        enabled = True
                    case text, widget, icon:
                        enabled = True
                    case text, widget, icon, enabled:
                        pass
                    case _:
                        raise ValueError(
                            "Content items must be an OptionItem instance, or "
                            "tuples of (title, widget), (title, widget, icon), or "
                            "(title, widget, icon, enabled)"
                        )

                self.content.append(text, widget, enabled=enabled, icon=icon)

        self.on_select = on_select

    def _create(self) -> Any:
        return self.factory.OptionContainer(interface=self)

    @property
    def enabled(self) -> 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.
        """
        return True

    @enabled.setter
    def enabled(self, value: object) -> None:
        pass

    def focus(self) -> None:
        """No-op; OptionContainer cannot accept input focus."""

    @property
    def content(self) -> OptionList:
        """The tabs of content currently managed by the OptionContainer."""
        return self._content

    @property
    def current_tab(self) -> OptionItem | None:
        """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.
        """
        index = self._impl.get_current_tab_index()
        if index is None:
            return None
        return self._content[index]

    @current_tab.setter
    def current_tab(self, value: OptionItem | str | int) -> None:
        index = self._content.index(value)
        if not self._impl.is_option_enabled(index):
            raise ValueError("A disabled tab cannot be made the current tab.")

        self._impl.set_current_tab_index(index)

    @Widget.app.setter
    def app(self, app) -> None:
        # Invoke the superclass property setter
        Widget.app.fset(self, app)

        # Also assign the app to the content in the container
        for item in self._content:
            item._content.app = app

    @Widget.window.setter
    def window(self, window) -> None:
        # Invoke the superclass property setter
        Widget.window.fset(self, window)

        # Also assign the window to the content in the container
        for item in self._content:
            item._content.window = window

    @property
    def on_select(self) -> OnSelectHandler:
        """The callback to invoke when a new tab of content is selected."""
        return self._on_select

    @on_select.setter
    def on_select(self, handler: toga.widgets.optioncontainer.OnSelectHandler) -> None:
        self._on_select = wrapped_handler(self, handler)

content property

The tabs of content currently managed by the OptionContainer.

current_tab property writable

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

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

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

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

Create a new OptionContainer.

:param id: The ID for the widget. :param style: A style object. If no style is provided, a default style will be applied to the widget. :param content: The initial OptionContainer content to display in the OptionContainer. :param on_select: Initial on_select handler. :param kwargs: Initial style properties.

Source code in core/src/toga/widgets/optioncontainer.py

def __init__(
    self,
    id: str | None = None,
    style: StyleT | None = None,
    content: Iterable[OptionContainerContentT] | None = None,
    on_select: toga.widgets.optioncontainer.OnSelectHandler | None = None,
    **kwargs,
):
    """Create a new OptionContainer.

    :param id: The ID for the widget.
    :param style: A style object. If no style is provided, a default style will be
        applied to the widget.
    :param content: The initial
        [OptionContainer content][toga.widgets.optioncontainer.OptionContainerContentT]
        to display in the OptionContainer.
    :param on_select: Initial [`on_select`][toga.OptionContainer.on_select] handler.
    :param kwargs: Initial style properties.
    """  # noqa: E501
    self._content = OptionList(self)
    self.on_select = None

    super().__init__(id, style, **kwargs)

    if content is not None:
        for item in content:
            match item:
                case OptionItem():
                    self.content.append(item)
                    continue
                case text, widget:
                    icon = None
                    enabled = True
                case text, widget, icon:
                    enabled = True
                case text, widget, icon, enabled:
                    pass
                case _:
                    raise ValueError(
                        "Content items must be an OptionItem instance, or "
                        "tuples of (title, widget), (title, widget, icon), or "
                        "(title, widget, icon, enabled)"
                    )

            self.content.append(text, widget, enabled=enabled, icon=icon)

    self.on_select = on_select

focus()

No-op; OptionContainer cannot accept input focus.

Source code in core/src/toga/widgets/optioncontainer.py

def focus(self) -> None:
    """No-op; OptionContainer cannot accept input focus."""

Source code in core/src/toga/widgets/optioncontainer.py

class OptionItem:
    def __init__(
        self,
        text: str,
        content: Widget,
        *,
        icon: IconContentT | None = None,
        enabled: bool = True,
    ):
        """A tab of content in an OptionContainer.

        :param text: The text label for the new tab.
        :param content: The content widget to use for the new tab.
        :param icon: The [icon content][toga.icons.IconContentT] to use to represent the
            tab.
        :param enabled: Should the new tab be enabled?
        """
        if content is None:
            raise ValueError("Content widget cannot be None.")

        self._content = content
        # These properties only exist while the item is in construction. Once the tab is
        # actual content, these attributes will be deleted and the native implementation
        # will become the source of truth. Initially prime the attributes with None (so
        # that the attribute exists), then use the setter to enforce validation on the
        # provided values.
        self._text: str = None
        self._icon: toga.Icon = None
        self._enabled: bool = None

        self.text = text
        self.icon = icon
        self.enabled = enabled

        # Prime the attributes for properties that will be set when the OptionItem is
        # set as content.
        self._interface: OptionContainer = None
        self._index: int = None

    @property
    def interface(self) -> OptionContainer:
        """The OptionContainer that contains this tab.

        Returns `None` if the tab isn't currently part of an OptionContainer.
        """
        return self._interface

    @property
    def enabled(self) -> bool:
        """Is the panel of content available for selection?"""
        try:
            return self._enabled
        except AttributeError:
            return self._interface._impl.is_option_enabled(self.index)

    @enabled.setter
    def enabled(self, value: object) -> None:
        enable = bool(value)
        if hasattr(self, "_enabled"):
            self._enabled = enable
        else:
            if (
                not enable
                and self.index == self._interface._impl.get_current_tab_index()
            ):
                raise ValueError("The currently selected tab cannot be disabled.")

            self._interface._impl.set_option_enabled(self.index, enable)

    @property
    def text(self) -> str:
        """The label for the tab of content."""
        try:
            return self._text
        except AttributeError:
            return self._interface._impl.get_option_text(self.index)

    @text.setter
    def text(self, value: object) -> None:
        if value is None:
            raise ValueError("Item text cannot be None")

        text = str(value)
        if not text:
            raise ValueError("Item text cannot be blank")

        if hasattr(self, "_text"):
            self._text = text
        else:
            self._interface._impl.set_option_text(self.index, text)

    @property
    def icon(self) -> toga.Icon:
        """The Icon for the tab of content.

        Can be specified as any valid [icon content][toga.icons.IconContentT].

        If the platform does not support the display of icons, this property
        will return `None` regardless of any value provided.
        """
        try:
            return self._icon
        except AttributeError:
            return self._interface._impl.get_option_icon(self.index)

    @icon.setter
    def icon(self, icon_or_name: IconContentT | None) -> None:
        if get_factory().OptionContainer.uses_icons:
            match icon_or_name:
                case toga.Icon() | None as icon:
                    pass
                case _:
                    icon = toga.Icon(icon_or_name)

            if hasattr(self, "_icon"):
                self._icon = icon
            else:
                self._interface._impl.set_option_icon(self.index, icon)

    @property
    def index(self) -> int | None:
        """The index of the tab in the OptionContainer.

        Returns `None` if the tab isn't currently part of an OptionContainer.
        """
        return self._index

    @property
    def content(self) -> Widget:
        """The content widget displayed in this tab of the OptionContainer."""
        return self._content

    def _preserve_option(self) -> None:
        # Move the ground truth back to the OptionItem instance
        self._text = self.text
        self._icon = self.icon
        self._enabled = self.enabled

        # Clear
        self._index = None
        self._interface = None

    def _add_as_option(self, index: int, interface: OptionContainer) -> None:
        text = self._text
        del self._text

        icon = self._icon
        del self._icon

        enabled = self._enabled
        del self._enabled

        self._content.app = interface.app
        self._content.window = interface.window

        self._index = index
        self._interface = interface
        interface._impl.add_option(index, text, self.content._impl, icon)

        # The option now exists on the implementation; finalize the display properties
        # that can't be resolved until the implementation exists.
        interface.refresh()
        self.enabled = enabled

content property

The content widget displayed in this tab of the OptionContainer.

enabled property writable

Is the panel of content available for selection?

icon property writable

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

The index of the tab in the OptionContainer.

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

interface property

The OptionContainer that contains this tab.

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

text property writable

The label for the tab of content.

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

A tab of content in an OptionContainer.

:param text: The text label for the new tab. :param content: The content widget to use for the new tab. :param icon: The icon content to use to represent the tab. :param enabled: Should the new tab be enabled?

Source code in core/src/toga/widgets/optioncontainer.py

def __init__(
    self,
    text: str,
    content: Widget,
    *,
    icon: IconContentT | None = None,
    enabled: bool = True,
):
    """A tab of content in an OptionContainer.

    :param text: The text label for the new tab.
    :param content: The content widget to use for the new tab.
    :param icon: The [icon content][toga.icons.IconContentT] to use to represent the
        tab.
    :param enabled: Should the new tab be enabled?
    """
    if content is None:
        raise ValueError("Content widget cannot be None.")

    self._content = content
    # These properties only exist while the item is in construction. Once the tab is
    # actual content, these attributes will be deleted and the native implementation
    # will become the source of truth. Initially prime the attributes with None (so
    # that the attribute exists), then use the setter to enforce validation on the
    # provided values.
    self._text: str = None
    self._icon: toga.Icon = None
    self._enabled: bool = None

    self.text = text
    self.icon = icon
    self.enabled = enabled

    # Prime the attributes for properties that will be set when the OptionItem is
    # set as content.
    self._interface: OptionContainer = None
    self._index: int = None

Source code in core/src/toga/widgets/optioncontainer.py

class OptionList:
    def __init__(self, interface: Any):
        self.interface = interface
        self._options: list[OptionItem] = []

    def __repr__(self) -> str:
        items = ", ".join(repr(option.text) for option in self)
        return f"<OptionList {items}>"

    def __getitem__(self, index: int | str | OptionItem) -> OptionItem:
        """Obtain a specific tab of content."""
        return self._options[self.index(index)]

    def __delitem__(self, index: int | str | OptionItem) -> None:
        """Same as [`remove`][toga.widgets.optioncontainer.OptionList.remove]."""
        self.remove(index)

    def remove(self, index: int | str | OptionItem) -> None:
        """Remove the specified tab of content.

        The currently selected item cannot be deleted.

        :param index: The index where the new tab should be inserted.
        """
        index = self.index(index)
        if index == self.interface._impl.get_current_tab_index():
            raise ValueError("The currently selected tab cannot be deleted.")

        # Ensure that the current ground truth of the item to be deleted is preserved as
        # attributes on the item
        deleted_item = self._options[index]
        deleted_item._preserve_option()
        deleted_item._content.window = None
        deleted_item._content.app = None

        self.interface._impl.remove_option(index)
        del self._options[index]
        # Update the index for each of the options
        # after the one that was removed.
        for option in self._options[index:]:
            option._index -= 1

        # Refresh the widget
        self.interface.refresh()

    def __len__(self) -> int:
        """The number of tabs of content in the OptionContainer."""
        return len(self._options)

    def index(self, value: str | int | OptionItem) -> int:
        """Find the index of the tab that matches the given value.

        :param value: The value to look for. An integer is returned as-is;
            if an [`OptionItem`][toga.widgets.optioncontainer.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.
        """
        match value:
            case int():
                return value
            case OptionItem():
                return value.index
            case _:
                try:
                    return next(tab for tab in self if tab.text == str(value)).index
                except StopIteration as exc:
                    raise ValueError(f"No tab named {value!r}") from exc

    @overload
    def append(
        self,
        text_or_item: OptionItem,
    ) -> None: ...

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

    def append(
        self,
        text_or_item: str | OptionItem,
        content: Widget | None = None,
        *,
        icon: IconContentT | None = None,
        enabled: bool | None = None,
    ) -> None:
        """Add a new tab of content to the OptionContainer.

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

        :param text_or_item: An [`OptionItem`][toga.widgets.optioncontainer.OptionItem];
            or, the text label for the new tab.
        :param content: The content widget to use for the new tab.
        :param icon: The [icon content][toga.icons.IconContentT] to use to represent the
            tab.
        :param enabled: Should the new tab be enabled? (Default: `True`)
        """
        self.insert(len(self), text_or_item, content, icon=icon, enabled=enabled)

    @overload
    def insert(
        self,
        index: int | str | OptionItem,
        text_or_item: OptionItem,
    ) -> None: ...

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

    def insert(
        self,
        index: int | str | OptionItem,
        text_or_item: str | OptionItem,
        content: Widget | None = None,
        *,
        icon: IconContentT | None = None,
        enabled: bool | None = None,
    ) -> None:
        """Insert a new tab of content to the OptionContainer at the specified index.

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

        :param index: The index where the new tab should be inserted.
        :param text_or_item: An [`OptionItem`][toga.widgets.optioncontainer.OptionItem];
            or, the text label for the new tab.
        :param content: The content widget to use for the new tab.
        :param icon: The [icon content][toga.icons.IconContentT] to use to represent the
            tab.
        :param enabled: Should the new tab be enabled? (Default: `True`)
        """
        if isinstance(text_or_item, OptionItem):
            if content is not None:
                raise ValueError(
                    "Cannot specify content if using an OptionItem instance."
                )
            if icon is not None:
                raise ValueError("Cannot specify icon if using an OptionItem instance.")
            if enabled is not None:
                raise ValueError(
                    "Cannot specify enabled if using an OptionItem instance."
                )
            item = text_or_item
        else:
            # Create an interface wrapper for the option.
            item = OptionItem(
                text_or_item,
                content,
                icon=icon,
                enabled=enabled if enabled is not None else True,
            )

        # Convert the index into an integer, and assign to the item.
        index = self.index(index)

        # Add the option to the list maintained on the interface,
        # and increment the index of all items after the one that was added.
        self._options.insert(index, item)
        for option in self._options[index + 1 :]:
            option._index += 1

        # Add the content to the implementation.
        # This will cause the native implementation to be created.
        item._add_as_option(index, self.interface)

__delitem__(index)

Same as remove.

Source code in core/src/toga/widgets/optioncontainer.py

def __delitem__(self, index: int | str | OptionItem) -> None:
    """Same as [`remove`][toga.widgets.optioncontainer.OptionList.remove]."""
    self.remove(index)

__getitem__(index)

Obtain a specific tab of content.

Source code in core/src/toga/widgets/optioncontainer.py

def __getitem__(self, index: int | str | OptionItem) -> OptionItem:
    """Obtain a specific tab of content."""
    return self._options[self.index(index)]

__len__()

The number of tabs of content in the OptionContainer.

Source code in core/src/toga/widgets/optioncontainer.py

def __len__(self) -> int:
    """The number of tabs of content in the OptionContainer."""
    return len(self._options)

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

append(text_or_item: OptionItem) -> None

append(
    text_or_item: str,
    content: Widget,
    *,
    icon: IconContentT | None = None,
    enabled: bool | None = True,
) -> 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.

:param text_or_item: An OptionItem; or, the text label for the new tab. :param content: The content widget to use for the new tab. :param icon: The icon content to use to represent the tab. :param enabled: Should the new tab be enabled? (Default: True)

Source code in core/src/toga/widgets/optioncontainer.py

def append(
    self,
    text_or_item: str | OptionItem,
    content: Widget | None = None,
    *,
    icon: IconContentT | None = None,
    enabled: bool | None = None,
) -> None:
    """Add a new tab of content to the OptionContainer.

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

    :param text_or_item: An [`OptionItem`][toga.widgets.optioncontainer.OptionItem];
        or, the text label for the new tab.
    :param content: The content widget to use for the new tab.
    :param icon: The [icon content][toga.icons.IconContentT] to use to represent the
        tab.
    :param enabled: Should the new tab be enabled? (Default: `True`)
    """
    self.insert(len(self), text_or_item, content, icon=icon, enabled=enabled)

index(value)

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

:param 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. :raises ValueError: If no tab matching the value can be found.

Source code in core/src/toga/widgets/optioncontainer.py

def index(self, value: str | int | OptionItem) -> int:
    """Find the index of the tab that matches the given value.

    :param value: The value to look for. An integer is returned as-is;
        if an [`OptionItem`][toga.widgets.optioncontainer.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.
    """
    match value:
        case int():
            return value
        case OptionItem():
            return value.index
        case _:
            try:
                return next(tab for tab in self if tab.text == str(value)).index
            except StopIteration as exc:
                raise ValueError(f"No tab named {value!r}") from exc

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

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

:param index: The index where the new tab should be inserted. :param text_or_item: An OptionItem; or, the text label for the new tab. :param content: The content widget to use for the new tab. :param icon: The icon content to use to represent the tab. :param enabled: Should the new tab be enabled? (Default: True)

Source code in core/src/toga/widgets/optioncontainer.py

def insert(
    self,
    index: int | str | OptionItem,
    text_or_item: str | OptionItem,
    content: Widget | None = None,
    *,
    icon: IconContentT | None = None,
    enabled: bool | None = None,
) -> None:
    """Insert a new tab of content to the OptionContainer at the specified index.

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

    :param index: The index where the new tab should be inserted.
    :param text_or_item: An [`OptionItem`][toga.widgets.optioncontainer.OptionItem];
        or, the text label for the new tab.
    :param content: The content widget to use for the new tab.
    :param icon: The [icon content][toga.icons.IconContentT] to use to represent the
        tab.
    :param enabled: Should the new tab be enabled? (Default: `True`)
    """
    if isinstance(text_or_item, OptionItem):
        if content is not None:
            raise ValueError(
                "Cannot specify content if using an OptionItem instance."
            )
        if icon is not None:
            raise ValueError("Cannot specify icon if using an OptionItem instance.")
        if enabled is not None:
            raise ValueError(
                "Cannot specify enabled if using an OptionItem instance."
            )
        item = text_or_item
    else:
        # Create an interface wrapper for the option.
        item = OptionItem(
            text_or_item,
            content,
            icon=icon,
            enabled=enabled if enabled is not None else True,
        )

    # Convert the index into an integer, and assign to the item.
    index = self.index(index)

    # Add the option to the list maintained on the interface,
    # and increment the index of all items after the one that was added.
    self._options.insert(index, item)
    for option in self._options[index + 1 :]:
        option._index += 1

    # Add the content to the implementation.
    # This will cause the native implementation to be created.
    item._add_as_option(index, self.interface)

remove(index)

Remove the specified tab of content.

The currently selected item cannot be deleted.

:param index: The index where the new tab should be inserted.

Source code in core/src/toga/widgets/optioncontainer.py

def remove(self, index: int | str | OptionItem) -> None:
    """Remove the specified tab of content.

    The currently selected item cannot be deleted.

    :param index: The index where the new tab should be inserted.
    """
    index = self.index(index)
    if index == self.interface._impl.get_current_tab_index():
        raise ValueError("The currently selected tab cannot be deleted.")

    # Ensure that the current ground truth of the item to be deleted is preserved as
    # attributes on the item
    deleted_item = self._options[index]
    deleted_item._preserve_option()
    deleted_item._content.window = None
    deleted_item._content.app = None

    self.interface._impl.remove_option(index)
    del self._options[index]
    # Update the index for each of the options
    # after the one that was removed.
    for option in self._options[index:]:
        option._index -= 1

    # Refresh the widget
    self.interface.refresh()

Source code in core/src/toga/widgets/optioncontainer.py

class OptionItem:
    def __init__(
        self,
        text: str,
        content: Widget,
        *,
        icon: IconContentT | None = None,
        enabled: bool = True,
    ):
        """A tab of content in an OptionContainer.

        :param text: The text label for the new tab.
        :param content: The content widget to use for the new tab.
        :param icon: The [icon content][toga.icons.IconContentT] to use to represent the
            tab.
        :param enabled: Should the new tab be enabled?
        """
        if content is None:
            raise ValueError("Content widget cannot be None.")

        self._content = content
        # These properties only exist while the item is in construction. Once the tab is
        # actual content, these attributes will be deleted and the native implementation
        # will become the source of truth. Initially prime the attributes with None (so
        # that the attribute exists), then use the setter to enforce validation on the
        # provided values.
        self._text: str = None
        self._icon: toga.Icon = None
        self._enabled: bool = None

        self.text = text
        self.icon = icon
        self.enabled = enabled

        # Prime the attributes for properties that will be set when the OptionItem is
        # set as content.
        self._interface: OptionContainer = None
        self._index: int = None

    @property
    def interface(self) -> OptionContainer:
        """The OptionContainer that contains this tab.

        Returns `None` if the tab isn't currently part of an OptionContainer.
        """
        return self._interface

    @property
    def enabled(self) -> bool:
        """Is the panel of content available for selection?"""
        try:
            return self._enabled
        except AttributeError:
            return self._interface._impl.is_option_enabled(self.index)

    @enabled.setter
    def enabled(self, value: object) -> None:
        enable = bool(value)
        if hasattr(self, "_enabled"):
            self._enabled = enable
        else:
            if (
                not enable
                and self.index == self._interface._impl.get_current_tab_index()
            ):
                raise ValueError("The currently selected tab cannot be disabled.")

            self._interface._impl.set_option_enabled(self.index, enable)

    @property
    def text(self) -> str:
        """The label for the tab of content."""
        try:
            return self._text
        except AttributeError:
            return self._interface._impl.get_option_text(self.index)

    @text.setter
    def text(self, value: object) -> None:
        if value is None:
            raise ValueError("Item text cannot be None")

        text = str(value)
        if not text:
            raise ValueError("Item text cannot be blank")

        if hasattr(self, "_text"):
            self._text = text
        else:
            self._interface._impl.set_option_text(self.index, text)

    @property
    def icon(self) -> toga.Icon:
        """The Icon for the tab of content.

        Can be specified as any valid [icon content][toga.icons.IconContentT].

        If the platform does not support the display of icons, this property
        will return `None` regardless of any value provided.
        """
        try:
            return self._icon
        except AttributeError:
            return self._interface._impl.get_option_icon(self.index)

    @icon.setter
    def icon(self, icon_or_name: IconContentT | None) -> None:
        if get_factory().OptionContainer.uses_icons:
            match icon_or_name:
                case toga.Icon() | None as icon:
                    pass
                case _:
                    icon = toga.Icon(icon_or_name)

            if hasattr(self, "_icon"):
                self._icon = icon
            else:
                self._interface._impl.set_option_icon(self.index, icon)

    @property
    def index(self) -> int | None:
        """The index of the tab in the OptionContainer.

        Returns `None` if the tab isn't currently part of an OptionContainer.
        """
        return self._index

    @property
    def content(self) -> Widget:
        """The content widget displayed in this tab of the OptionContainer."""
        return self._content

    def _preserve_option(self) -> None:
        # Move the ground truth back to the OptionItem instance
        self._text = self.text
        self._icon = self.icon
        self._enabled = self.enabled

        # Clear
        self._index = None
        self._interface = None

    def _add_as_option(self, index: int, interface: OptionContainer) -> None:
        text = self._text
        del self._text

        icon = self._icon
        del self._icon

        enabled = self._enabled
        del self._enabled

        self._content.app = interface.app
        self._content.window = interface.window

        self._index = index
        self._interface = interface
        interface._impl.add_option(index, text, self.content._impl, icon)

        # The option now exists on the implementation; finalize the display properties
        # that can't be resolved until the implementation exists.
        interface.refresh()
        self.enabled = enabled

content property

The content widget displayed in this tab of the OptionContainer.

enabled property writable

Is the panel of content available for selection?

icon property writable

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

The index of the tab in the OptionContainer.

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

interface property

The OptionContainer that contains this tab.

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

text property writable

The label for the tab of content.

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

A tab of content in an OptionContainer.

:param text: The text label for the new tab. :param content: The content widget to use for the new tab. :param icon: The icon content to use to represent the tab. :param enabled: Should the new tab be enabled?

Source code in core/src/toga/widgets/optioncontainer.py

def __init__(
    self,
    text: str,
    content: Widget,
    *,
    icon: IconContentT | None = None,
    enabled: bool = True,
):
    """A tab of content in an OptionContainer.

    :param text: The text label for the new tab.
    :param content: The content widget to use for the new tab.
    :param icon: The [icon content][toga.icons.IconContentT] to use to represent the
        tab.
    :param enabled: Should the new tab be enabled?
    """
    if content is None:
        raise ValueError("Content widget cannot be None.")

    self._content = content
    # These properties only exist while the item is in construction. Once the tab is
    # actual content, these attributes will be deleted and the native implementation
    # will become the source of truth. Initially prime the attributes with None (so
    # that the attribute exists), then use the setter to enforce validation on the
    # provided values.
    self._text: str = None
    self._icon: toga.Icon = None
    self._enabled: bool = None

    self.text = text
    self.icon = icon
    self.enabled = enabled

    # Prime the attributes for properties that will be set when the OptionItem is
    # set as content.
    self._interface: OptionContainer = None
    self._index: int = None

Bases: Protocol

Source code in core/src/toga/widgets/optioncontainer.py

class OnSelectHandler(Protocol):
    def __call__(self, widget: OptionContainer, **kwargs: Any) -> None:
        """A handler that will be invoked when a new tab is selected
        in the OptionContainer.

        :param widget: The OptionContainer that had a selection change.
        :param kwargs: Ensures compatibility with arguments added in future versions.
        """

__call__(widget, **kwargs)

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

:param widget: The OptionContainer that had a selection change. :param kwargs: Ensures compatibility with arguments added in future versions.

Source code in core/src/toga/widgets/optioncontainer.py

def __call__(self, widget: OptionContainer, **kwargs: Any) -> None:
    """A handler that will be invoked when a new tab is selected
    in the OptionContainer.

    :param widget: The OptionContainer that had a selection change.
    :param kwargs: Ensures compatibility with arguments added in future versions.
    """

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.