Box

Usage

Box is the simplest container for other widgets, and the basic building block for laying out items in rows and columns.

An empty Box can be constructed without any children, with children added to the box after construction:

import toga

box = toga.Box()

label1 = toga.Label('Hello')
label2 = toga.Label('World')

box.add(label1)
box.add(label2)

Alternatively, children can be specified at the time the box is constructed:

import toga

label1 = toga.Label('Hello')
label2 = toga.Label('World')

box = toga.Box(children=[label1, label2])

In most apps, a layout is constructed by building a tree of boxes inside boxes, with concrete widgets (such as Label or Button) forming the leaf nodes of the tree. Style directives can be applied to enforce a margin around the outside of the box, direction of child stacking inside the box, and background color of the box.

Reference

Bases: Widget

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

class Box(Widget):
    _MIN_WIDTH = 0
    _MIN_HEIGHT = 0

    _USE_DEBUG_BACKGROUND = True

    def __init__(
        self,
        id: str | None = None,
        style: StyleT | None = None,
        children: Iterable[Widget] | None = None,
        **kwargs,
    ):
        """Create a new Box container widget.

        :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 children: An optional list of children for to add to the Box.
        :param kwargs: Initial style properties.
        """
        super().__init__(id, style, **kwargs)

        # Children need to be added *after* the impl has been created.
        self._children: list[Widget] = []
        if children is not None:
            self.add(*children)

    def _create(self):
        return self.factory.Box(interface=self)

    @property
    def enabled(self) -> bool:
        """Is the widget currently enabled? i.e., can the user interact with the widget?

        Box 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: bool) -> None:
        pass

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

enabled property writable

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

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

__init__(id=None, style=None, children=None, **kwargs)

Create a new Box container widget.

: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 children: An optional list of children for to add to the Box. :param kwargs: Initial style properties.

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

def __init__(
    self,
    id: str | None = None,
    style: StyleT | None = None,
    children: Iterable[Widget] | None = None,
    **kwargs,
):
    """Create a new Box container widget.

    :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 children: An optional list of children for to add to the Box.
    :param kwargs: Initial style properties.
    """
    super().__init__(id, style, **kwargs)

    # Children need to be added *after* the impl has been created.
    self._children: list[Widget] = []
    if children is not None:
        self.add(*children)

focus()

No-op; Box cannot accept input focus.

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

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

Shorthand for Box with its text-direction set to "row".

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

def Row(*args, **kwargs):
    """Shorthand for [`Box`][toga.Box] with its
    [text-direction][toga.style.pack.Pack.text_direction] set to "row".
    """
    return Box(*args, direction="row", **kwargs)

Shorthand for Box with its direction set to "column".

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

def Column(*args, **kwargs):
    """Shorthand for [`Box`][toga.Box] with its
    [direction][toga.style.pack.Pack.direction] set to "column".
    """
    return Box(*args, direction="column", **kwargs)