Box#
The box is a generic container for widgets, allowing you to construct layouts.
Usage#
A box can be instantiated with no children and the children added later:
import toga
box = toga.Box('box1')
button = toga.Button('Hello world', on_press=button_handler)
box.add(button)
To create boxes within boxes, use the children argument:
import toga
box_a = toga.Box('box_a')
box_b = toga.Box('box_b')
box = toga.Box('box', children=[box_a, box_b])
Box Styling#
Styling of boxes can be done during instantiation of the Box:
import toga
from toga.style import Pack
from toga.style.pack import COLUMN
box = toga.Box(id='box', style=Pack(direction=COLUMN, padding_top=10))
Styles can be also be updated on an existing instance:
import toga
from toga.style import Pack
from toga.style.pack import COLUMN
box = toga.Box(id='box', style=Pack(direction=COLUMN))
box.style.update(padding_top=10)
Reference#
- class toga.widgets.box.Box(id=None, style=None, children=None, factory=None)#
This is a Widget that contains other widgets, but has no rendering or interaction of its own.
- Parameters:
id (str) – An identifier for this widget.
( (style) – class:~colosseum.CSSNode`): An optional style object. If no style is provided then a new one will be created for the widget.
children (
list
ofWidget
) – An optional list of child Widgets that will be in this box.
- add(*children)#
Add the provided widgets as children of this widget.
If a node already has a different parent, it will be moved over. This does nothing if a node already is a child of this node.
Raises
ValueError
if this widget cannot have children.- Parameters:
children – The widgets to add as children of this widget.
- property app#
The App to which this widget belongs.
When setting the app for a widget, all children of this widget will be recursively assigned to the same app.
Raises
ValueError
if the widget is already associated with another app.
- property can_have_children#
Determine if the node can have children.
This does not resolve whether there actually are any children; it only confirms whether children are theoretically allowed.
- property children#
The children of this node. This always returns a list, even if the node is a leaf and cannot have children.
- Returns:
A list of the children for this widget.
- property enabled#
Is the widget currently enabled? i.e., can the user interact with the widget?
- focus()#
Set this widget to have the current input focus.
- property id#
The node identifier. This id can be used to target styling directives.
- insert(index, child)#
Insert a widget as a child of this widget.
If the node already has a parent, ownership of the widget will be transferred.
Raises
ValueError
if this node cannot have children.- Parameters:
index – The position in the list of children where the new widget should be added.
child – The child to insert as a child of this node.
- property parent#
The parent of this node.
- Returns:
The parent of this node. Returns None if this node is the root node.
- refresh()#
Refresh the layout and appearance of the tree this node is contained in.
- refresh_sublayouts()#
- remove(*children)#
Remove the provided widgets as children of this node.
This does nothing if a given node is not a child of this node.
Raises
ValueError
if this node is a leaf, and cannot have children.- Parameters:
children – The child nodes to remove.
- property root#
The root of the tree containing this node.
- Returns:
The root node. Returns self if this node is the root node.
- property tab_index#
The position of the widget in the focus chain for the window.
- property window#
The window to which this widget belongs.
When setting the window for a widget, all children of this widget will be recursively assigned to the same window.