0
# Container Widgets
1

2
Container widgets are used to organize and group other widgets within your application. They provide layout management and visual grouping of related interface elements.
3

4
## Capabilities
5

6
### Box Container
7

8
The Box widget is a general-purpose container for organizing other widgets. It can use automatic layout or grid-based positioning and provides visual grouping with optional borders.
9

10
```python { .api }
11
class Box:
12
    def __init__(self, master, layout="auto", grid=None, align=None, 
13
                 visible=True, enabled=None, width=None, height=None, 
14
                 border=None):
15
        """
16
        Create a container widget for organizing other widgets.
17
        
18
        Args:
19
            master: Parent widget (App, Window, or another container)
20
            layout (str): Layout manager ("auto" or "grid")
21
            grid (list): Grid position [x, y] for grid layout
22
            align (str): Alignment ("left", "right", "top", "bottom")
23
            visible (bool): Initial visibility state
24
            enabled (bool): Initial enabled state
25
            width (int): Container width in pixels
26
            height (int): Container height in pixels
27
            border (int): Border width in pixels
28
        """
29
        
30
    # Inherited properties from Container class
31
    @property
32
    def layout(self) -> str:
33
        """Get/set the layout manager ("auto" or "grid")."""
34
        
35
    @layout.setter
36
    def layout(self, value: str): ...
37
        
38
    @property
39
    def bg(self) -> str:
40
        """Get/set the background color."""
41
        
42
    @bg.setter
43
    def bg(self, value: str): ...
44
        
45
    @property
46
    def text_color(self) -> str:
47
        """Get/set the default text color for child widgets."""
48
        
49
    @text_color.setter
50
    def text_color(self, value: str): ...
51
        
52
    @property
53
    def text_size(self) -> int:
54
        """Get/set the default text size for child widgets."""
55
        
56
    @text_size.setter
57
    def text_size(self, value: int): ...
58
        
59
    @property
60
    def text_bold(self) -> bool:
61
        """Get/set default bold text for child widgets."""
62
        
63
    @text_bold.setter
64
    def text_bold(self, value: bool): ...
65
        
66
    @property
67
    def text_italic(self) -> bool:
68
        """Get/set default italic text for child widgets."""
69
        
70
    @text_italic.setter  
71
    def text_italic(self, value: bool): ...
72
```
73

74
#### Usage Example
75

76
```python
77
from guizero import App, Box, Text, PushButton
78

79
app = App()
80

81
# Create a box container with a border
82
main_box = Box(app, border=2, width=300, height=200)
83
main_box.bg = "lightgray"
84

85
# Add widgets to the box
86
Text(main_box, text="This is inside the box")
87
PushButton(main_box, text="Button in box")
88

89
# Create a box with grid layout
90
grid_box = Box(app, layout="grid")
91
Text(grid_box, text="Top left", grid=[0, 0])
92
Text(grid_box, text="Top right", grid=[1, 0])
93
Text(grid_box, text="Bottom left", grid=[0, 1])
94

95
app.display()
96
```
97

98
### TitleBox Container
99

100
The TitleBox widget is a container with a visible title/label that groups related widgets under a descriptive heading.
101

102
```python { .api }
103
class TitleBox:
104
    def __init__(self, master, text="TitleBox", layout="auto", grid=None, 
105
                 align=None, visible=True, enabled=None, width=None, 
106
                 height=None, border=None):
107
        """
108
        Create a titled container widget.
109
        
110
        Args:
111
            master: Parent widget (App, Window, or another container)
112
            text (str): Title text displayed at the top
113
            layout (str): Layout manager ("auto" or "grid")
114
            grid (list): Grid position [x, y] for grid layout
115
            align (str): Alignment ("left", "right", "top", "bottom")
116
            visible (bool): Initial visibility state
117
            enabled (bool): Initial enabled state
118
            width (int): Container width in pixels
119
            height (int): Container height in pixels
120
            border (int): Border width in pixels
121
        """
122
        
123
    @property
124
    def text(self) -> str:
125
        """Get/set the title text."""
126
        
127
    @text.setter
128
    def text(self, value: str): ...
129
        
130
    # Inherits all Container properties (layout, bg, text_color, etc.)
131
```
132

133
#### Usage Example
134

135
```python
136
from guizero import App, TitleBox, CheckBox, Slider
137

138
app = App()
139

140
# Create a titled section for settings
141
settings_box = TitleBox(app, text="Settings")
142
settings_box.bg = "white"
143

144
# Add settings widgets to the titled box
145
CheckBox(settings_box, text="Enable notifications")
146
CheckBox(settings_box, text="Auto-save")
147
Slider(settings_box, start=0, end=100)
148

149
# Create another titled section
150
display_box = TitleBox(app, text="Display Options")
151
CheckBox(display_box, text="Dark mode")
152
CheckBox(display_box, text="Show toolbar")
153

154
app.display()
155
```
156

157
### ButtonGroup Container
158

159
The ButtonGroup widget creates a group of mutually exclusive radio buttons, where only one option can be selected at a time.
160

161
```python { .api }
162
class ButtonGroup:
163
    def __init__(self, master, options=[], selected=None, horizontal=True, 
164
                 command=None, grid=None, align=None, visible=True, 
165
                 enabled=None, width=None, height=None):
166
        """
167
        Create a group of mutually exclusive radio buttons.
168
        
169
        Args:
170
            master: Parent widget (App, Window, or container)
171
            options (list): List of option texts/values
172
            selected: Initially selected option
173
            horizontal (bool): True for horizontal layout, False for vertical
174
            command (function): Callback when selection changes
175
            grid (list): Grid position [x, y] for grid layout
176
            align (str): Alignment ("left", "right", "top", "bottom")
177
            visible (bool): Initial visibility state
178
            enabled (bool): Initial enabled state
179
            width (int): Widget width in pixels
180
            height (int): Widget height in pixels
181
        """
182
        
183
    @property
184
    def value(self):
185
        """Get/set the selected option value."""
186
        
187
    @value.setter
188
    def value(self, option): ...
189
        
190
    @property
191
    def value_text(self) -> str:
192
        """Get the text of the currently selected option."""
193
        
194
    # Event handler
195
    @property
196
    def when_clicked(self):
197
        """Callback function when selection changes."""
198
        
199
    @when_clicked.setter
200
    def when_clicked(self, callback): ...
201
```
202

203
#### Usage Example
204

205
```python
206
from guizero import App, ButtonGroup, Text
207

208
app = App()
209

210
# Create a button group for size selection
211
size_group = ButtonGroup(
212
    app, 
213
    options=["Small", "Medium", "Large"], 
214
    selected="Medium"
215
)
216

217
# Create a button group with horizontal layout
218
color_group = ButtonGroup(
219
    app,
220
    options=["Red", "Green", "Blue"],
221
    horizontal=True
222
)
223

224
# Display current selections
225
selection_text = Text(app)
226

227
def update_selection():
228
    selection_text.value = f"Size: {size_group.value}, Color: {color_group.value}"
229

230
size_group.when_clicked = update_selection
231
color_group.when_clicked = update_selection
232

233
# Initialize display
234
update_selection()
235

236
app.display()
237
```
238

239
## Container Layout Management
240

241
Containers support different layout approaches:
242

243
### Auto Layout
244
Default behavior where widgets are arranged automatically:
245
```python
246
box = Box(app)  # Uses auto layout by default
247
```
248

249
### Grid Layout
250
Explicit positioning using grid coordinates:
251
```python
252
box = Box(app, layout="grid")
253
Text(box, text="Widget 1", grid=[0, 0])
254
Text(box, text="Widget 2", grid=[1, 0])
255
```
256

257
### Container Styling
258

259
All containers support styling properties that can be inherited by child widgets:
260

261
```python
262
container.bg = "lightblue"           # Background color
263
container.text_color = "darkblue"    # Default text color for children
264
container.text_size = 12             # Default text size for children
265
container.text_bold = True           # Default bold text for children
266
container.text_italic = False        # Default italic text for children
267
```
268

269
## Nested Containers
270

271
Containers can be nested to create complex layouts:
272

273
```python
274
from guizero import App, Box, TitleBox, Text, PushButton
275

276
app = App()
277

278
# Main container
279
main_box = Box(app, border=1)
280

281
# Left section
282
left_section = TitleBox(main_box, text="Controls")
283
PushButton(left_section, text="Start")
284
PushButton(left_section, text="Stop")
285

286
# Right section  
287
right_section = TitleBox(main_box, text="Status")
288
Text(right_section, text="Ready")
289

290
app.display()
291
```