0
# Application Management
1
2
Core functionality for creating and managing application windows, including the main application window and secondary windows.
3
4
## Capabilities
5
6
### Main Application Window
7
8
The App class creates the main application window that serves as the root container for all GUI elements. It handles the application lifecycle and provides the main event loop.
9
10
```python { .api }
11
class App:
12
def __init__(self, title="guizero", width=500, height=500, layout="auto",
13
bg=None, visible=True):
14
"""
15
Create the main application window.
16
17
Args:
18
title (str): Window title text
19
width (int): Window width in pixels
20
height (int): Window height in pixels
21
layout (str): Layout manager ("auto" or "grid")
22
bg (str): Background color
23
visible (bool): Initial visibility state
24
"""
25
26
def display(self):
27
"""Start the GUI event loop - call this to show the app and begin event handling."""
28
29
def destroy(self):
30
"""Close the application and cleanup resources."""
31
32
def exit_full_screen(self):
33
"""Exit full screen mode."""
34
35
def full_screen(self):
36
"""Enter full screen mode."""
37
38
def hide(self):
39
"""Hide the application window."""
40
41
def show(self):
42
"""Show the application window."""
43
44
def cancel(self, callback):
45
"""Cancel a scheduled callback."""
46
47
def repeat(self, time, callback, args=None):
48
"""
49
Schedule a callback to repeat at regular intervals.
50
51
Args:
52
time (int): Interval in milliseconds
53
callback (function): Function to call
54
args (list): Arguments to pass to callback
55
"""
56
57
def after(self, time, callback, args=None):
58
"""
59
Schedule a callback to run once after a delay.
60
61
Args:
62
time (int): Delay in milliseconds
63
callback (function): Function to call
64
args (list): Arguments to pass to callback
65
"""
66
67
# Properties
68
@property
69
def title(self) -> str:
70
"""Get/set the window title."""
71
72
@title.setter
73
def title(self, value: str): ...
74
75
@property
76
def width(self) -> int:
77
"""Get/set the window width."""
78
79
@width.setter
80
def width(self, value: int): ...
81
82
@property
83
def height(self) -> int:
84
"""Get/set the window height."""
85
86
@height.setter
87
def height(self, value: int): ...
88
89
@property
90
def bg(self) -> str:
91
"""Get/set the background color."""
92
93
@bg.setter
94
def bg(self, value: str): ...
95
96
@property
97
def full_screen(self) -> bool:
98
"""Get/set full screen mode."""
99
100
@full_screen.setter
101
def full_screen(self, value: bool): ...
102
103
@property
104
def visible(self) -> bool:
105
"""Get/set window visibility."""
106
107
@visible.setter
108
def visible(self, value: bool): ...
109
110
@property
111
def tk(self):
112
"""Access to underlying Tkinter root object."""
113
114
# Event handlers
115
@property
116
def when_closed(self):
117
"""Callback function when window is closed."""
118
119
@when_closed.setter
120
def when_closed(self, callback): ...
121
```
122
123
#### Usage Example
124
125
```python
126
from guizero import App, Text, PushButton
127
128
# Create the main application
129
app = App(title="My Application", width=400, height=300, bg="lightblue")
130
131
# Add some widgets
132
Text(app, text="Welcome to my app!")
133
134
def close_app():
135
app.destroy()
136
137
PushButton(app, text="Close", command=close_app)
138
139
# Set up event handlers
140
def on_app_closing():
141
print("Application is closing")
142
143
app.when_closed = on_app_closing
144
145
# Start the application
146
app.display()
147
```
148
149
### Secondary Windows
150
151
The Window class creates additional windows that can be opened from the main application. These are useful for dialogs, settings screens, or any secondary interface.
152
153
```python { .api }
154
class Window:
155
def __init__(self, master, title="guizero", width=500, height=500,
156
layout="auto", bg=None, visible=True):
157
"""
158
Create a secondary window.
159
160
Args:
161
master (App): Parent application
162
title (str): Window title text
163
width (int): Window width in pixels
164
height (int): Window height in pixels
165
layout (str): Layout manager ("auto" or "grid")
166
bg (str): Background color
167
visible (bool): Initial visibility state
168
"""
169
170
def show(self):
171
"""Show the window."""
172
173
def hide(self):
174
"""Hide the window."""
175
176
def destroy(self):
177
"""Close the window and cleanup resources."""
178
179
def full_screen(self):
180
"""Enter full screen mode."""
181
182
def exit_full_screen(self):
183
"""Exit full screen mode."""
184
185
# Properties (same as App)
186
@property
187
def title(self) -> str:
188
"""Get/set the window title."""
189
190
@title.setter
191
def title(self, value: str): ...
192
193
@property
194
def width(self) -> int:
195
"""Get/set the window width."""
196
197
@width.setter
198
def width(self, value: int): ...
199
200
@property
201
def height(self) -> int:
202
"""Get/set the window height."""
203
204
@height.setter
205
def height(self, value: int): ...
206
207
@property
208
def bg(self) -> str:
209
"""Get/set the background color."""
210
211
@bg.setter
212
def bg(self, value: str): ...
213
214
@property
215
def visible(self) -> bool:
216
"""Get/set window visibility."""
217
218
@visible.setter
219
def visible(self, value: bool): ...
220
221
@property
222
def tk(self):
223
"""Access to underlying Tkinter Toplevel object."""
224
```
225
226
#### Usage Example
227
228
```python
229
from guizero import App, Window, Text, PushButton
230
231
app = App(title="Main Window")
232
233
def open_settings():
234
settings_window = Window(app, title="Settings", width=300, height=200)
235
Text(settings_window, text="Settings go here")
236
237
def close_settings():
238
settings_window.destroy()
239
240
PushButton(settings_window, text="Close", command=close_settings)
241
242
PushButton(app, text="Open Settings", command=open_settings)
243
244
app.display()
245
```
246
247
## Application Lifecycle
248
249
The typical guizero application lifecycle:
250
251
1. **Create App**: Initialize the main application window
252
2. **Add Widgets**: Create and add widgets to the app or containers
253
3. **Set Event Handlers**: Configure callbacks for user interactions
254
4. **Display**: Call `app.display()` to start the event loop
255
5. **Handle Events**: Application responds to user interactions
256
6. **Cleanup**: Application closes when user closes window or calls `destroy()`
257
258
## Scheduling and Timers
259
260
Apps support scheduling callbacks to run at specific times or intervals:
261
262
```python
263
# Run once after 5 seconds
264
app.after(5000, my_function)
265
266
# Run every 2 seconds
267
app.repeat(2000, update_clock)
268
269
# Cancel a scheduled callback
270
callback_id = app.repeat(1000, periodic_task)
271
app.cancel(callback_id)
272
```