0
# guizero
1

2
A Python 3 GUI library designed specifically for educational purposes and new learners to create simple graphical user interfaces. Built on top of the standard Python Tkinter library, it abstracts away complex concepts like StringVar objects and provides an accessible widget naming system that helps beginners build mental models of GUI development. The library generates helpful error messages for learners and requires no additional dependencies beyond Python's standard installation.
3

4
## Package Information
5

6
- **Package Name**: guizero
7
- **Language**: Python
8
- **Installation**: `pip install guizero`
9

10
## Core Imports
11

12
```python
13
import guizero
14
```
15

16
For commonly used widgets and dialogs:
17

18
```python
19
from guizero import App, Box, Text, TextBox, PushButton, CheckBox
20
```
21

22
All widgets and dialogs:
23

24
```python
25
from guizero import *
26
```
27

28
## Basic Usage
29

30
```python
31
from guizero import App, Text, TextBox, PushButton
32

33
# Create main application window
34
app = App(title="My First GUI", width=300, height=200)
35

36
# Add widgets to the app
37
message = Text(app, text="Hello World!")
38
name_box = TextBox(app)
39

40
def say_hello():
41
    message.value = f"Hello {name_box.value}!"
42

43
hello_button = PushButton(app, text="Say Hello", command=say_hello)
44

45
# Run the application
46
app.display()
47
```
48

49
## Architecture
50

51
guizero follows a hierarchical widget architecture:
52

53
- **App**: Root application window that contains all other widgets
54
- **Containers**: Box, TitleBox, ButtonGroup - widgets that can contain other widgets
55
- **Input Widgets**: PushButton, CheckBox, RadioButton, Slider, TextBox, Combo, ListBox - interactive widgets for user input
56
- **Display Widgets**: Text, Picture, Drawing, Waffle - widgets for displaying information
57
- **Dialogs**: Functions for showing message boxes and file/color selection dialogs
58
- **Secondary Windows**: Window class for creating additional windows
59

60
All widgets inherit common properties for styling (color, size, font) and behavior (enabled, visible, events). The library uses automatic layout management by default but supports grid-based positioning for precise control.
61

62
## Capabilities
63

64
### Application Management
65

66
Core application window functionality including creating the main app window, secondary windows, and handling the application lifecycle.
67

68
```python { .api }
69
class App:
70
    def __init__(self, title="guizero", width=500, height=500, layout="auto", 
71
                 bg=None, visible=True): ...
72
    def display(self): ...
73
    def destroy(self): ...
74

75
class Window:
76
    def __init__(self, master, title="guizero", width=500, height=500, 
77
                 layout="auto", bg=None, visible=True): ...
78
    def show(self): ...
79
    def hide(self): ...
80
```
81

82
[Application Management](./application.md)
83

84
### Container Widgets
85

86
Layout containers for organizing and grouping other widgets including boxes, titled frames, and button groups.
87

88
```python { .api }
89
class Box:
90
    def __init__(self, master, layout="auto", grid=None, align=None, 
91
                 visible=True, enabled=None, width=None, height=None, 
92
                 border=None): ...
93

94
class TitleBox:
95
    def __init__(self, master, text="TitleBox", layout="auto", grid=None, 
96
                 align=None, visible=True, enabled=None, width=None, 
97
                 height=None, border=None): ...
98

99
class ButtonGroup:
100
    def __init__(self, master, options=[], selected=None, horizontal=True, 
101
                 command=None, grid=None, align=None, visible=True, 
102
                 enabled=None, width=None, height=None): ...
103
```
104

105
[Container Widgets](./containers.md)
106

107
### Input Widgets
108

109
Interactive widgets for user input including buttons, text entry, checkboxes, sliders, and selection widgets.
110

111
```python { .api }
112
class PushButton:
113
    def __init__(self, master, command=None, args=None, text="Button", 
114
                 image=None, pady=10, padx=10, grid=None, align=None, 
115
                 icon=None, visible=True, enabled=None, width=None, 
116
                 height=None): ...
117

118
class TextBox:
119
    def __init__(self, master, text="", width=10, height=1, multiline=False, 
120
                 scrollbar=False, command=None, grid=None, align=None, 
121
                 visible=True, enabled=None, hide_text=False): ...
122

123
class CheckBox:
124
    def __init__(self, master, text="", command=None, grid=None, align=None, 
125
                 visible=True, enabled=None, width=None, height=None): ...
126

127
class Slider:
128
    def __init__(self, master, start=0, end=100, horizontal=True, command=None, 
129
                 grid=None, align=None, visible=True, enabled=None, 
130
                 width=None, height=None): ...
131

132
class Combo:
133
    def __init__(self, master, options=[], selected=None, command=None, 
134
                 grid=None, align=None, visible=True, enabled=None, 
135
                 width=None, height=None): ...
136

137
class ListBox:
138
    def __init__(self, master, items=[], selected=None, command=None, 
139
                 multiselect=False, scrollbar=False, grid=None, align=None, 
140
                 visible=True, enabled=None, width=None, height=None): ...
141
```
142

143
[Input Widgets](./input-widgets.md)
144

145
### Display Widgets
146

147
Widgets for displaying text, images, and graphics including text labels, pictures, drawing canvas, and pixel grids.
148

149
```python { .api }
150
class Text:
151
    def __init__(self, master, text="", size=None, color=None, bg=None, 
152
                 font=None, grid=None, align=None, visible=True, 
153
                 enabled=None, width=None, height=None): ...
154

155
class Picture:
156
    def __init__(self, master, image=None, grid=None, align=None, 
157
                 visible=True, enabled=None, width=None, height=None): ...
158

159
class Drawing:
160
    def __init__(self, master, width=400, height=400, grid=None, align=None, 
161
                 visible=True, enabled=None): ...
162

163
class Waffle:
164
    def __init__(self, master, height=3, width=3, dim=20, pad=5, 
165
                 color="white", dotty=False, grid=None, align=None, 
166
                 visible=True, enabled=None, remember=True, command=None): ...
167
```
168

169
[Display Widgets](./display-widgets.md)
170

171
### Dialog Functions
172

173
Message boxes and file/color selection dialogs for user interaction including warnings, information, questions, and file operations.
174

175
```python { .api }
176
def warn(title, text, master=None): ...
177
def info(title, text, master=None): ...
178
def error(title, text, master=None): ...
179
def yesno(title, text, master=None): ...
180
def question(title, question, initial_value=None, master=None): ...
181
def select_file(title="Select file", folder=".", filetypes=[["All files", "*.*"]], 
182
                save=False, master=None, filename=""): ...
183
def select_folder(title="Select folder", folder=".", master=None): ...
184
def select_color(color=None, master=None): ...
185
```
186

187
[Dialog Functions](./dialogs.md)
188

189
### Menu System
190

191
Menu bar functionality for creating application menus and menu items.
192

193
```python { .api }
194
class MenuBar:
195
    def __init__(self, master, toplevel=[], options=[]): ...
196
```
197

198
[Menu System](./menus.md)
199

200
## Common Widget Properties
201

202
All guizero widgets share common properties and methods:
203

204
```python { .api }
205
# Common properties available on all widgets
206
widget.master          # Parent widget
207
widget.tk              # Underlying tkinter object
208
widget.enabled         # Enable/disable state (bool)
209
widget.visible         # Show/hide state (bool)
210
widget.width           # Widget width
211
widget.height          # Widget height
212
widget.bg              # Background color
213
widget.text_color      # Text color (for text-containing widgets)
214
widget.text_size       # Text size (for text-containing widgets)
215
widget.font            # Font family (for text-containing widgets)
216

217
# Common methods
218
widget.destroy()       # Remove widget
219
widget.focus()         # Give keyboard focus
220
widget.resize(width, height)  # Change size
221
```
222

223
## Event Handling
224

225
guizero provides simple event handling through widget properties:
226

227
```python { .api }
228
# Event handlers can be assigned to widget properties
229
button.when_clicked = callback_function
230
textbox.when_key_pressed = key_handler
231
app.when_closed = cleanup_function
232
```
233

234
## Layout Management
235

236
guizero supports multiple layout approaches:
237

238
- **auto**: Automatic layout (default) - widgets are arranged automatically
239
- **grid**: Grid-based positioning using grid parameter [x, y]
240
- **align**: Simple alignment using align parameter ("left", "right", "top", "bottom")
241

242
## Colors and Styling
243

244
Colors can be specified using:
245
- Named colors: "red", "blue", "green", "white", "black", etc.
246
- Hex colors: "#FF0000", "#00FF00", "#0000FF", etc.
247
- RGB tuples: (255, 0, 0), (0, 255, 0), (0, 0, 255), etc.
248

249
## Error Handling
250

251
guizero provides helpful error messages designed for learners:
252

253
```python { .api }
254
from guizero.utilities import GUIZeroException
255

256
# Custom exception class for guizero-specific errors
257
class GUIZeroException(Exception): ...
258
```