0
# Window Management
1
2
PyTermGUI's window management system provides desktop-like window functionality with multi-window support, compositing, event routing, and flexible layout management. The system enables complex applications with overlapping windows and sophisticated user interfaces.
3
4
## Capabilities
5
6
### WindowManager
7
8
Central manager for multiple windows, handling input routing, focus management, and application lifecycle.
9
10
```python { .api }
11
class WindowManager:
12
"""Multi-window application manager."""
13
14
def __init__(self, *, layout_type: type = None, framerate: int = 60,
15
autorun: bool = None):
16
"""
17
Initialize window manager.
18
19
Parameters:
20
- layout_type (type, optional): Layout class to use
21
- framerate (int): Target framerate, defaults to 60
22
- autorun (bool, optional): Whether to auto-run, defaults to class setting
23
"""
24
25
def add(self, window: "Window", assign: str | bool = True,
26
animate: bool = True) -> "WindowManager":
27
"""
28
Add window to manager.
29
30
Parameters:
31
- window (Window): Window to add
32
- assign (str | bool): Layout assignment - slot name, True for auto, or False for none
33
- animate (bool): Whether to animate window addition
34
35
Returns:
36
The WindowManager instance for chaining
37
"""
38
39
def remove(self, window: "Window") -> "Window":
40
"""Remove window from manager."""
41
42
def focus(self, window: "Window"):
43
"""Set window focus."""
44
45
def run(self):
46
"""Start window manager event loop."""
47
48
def stop(self):
49
"""Stop window manager and exit event loop."""
50
51
@property
52
def focused(self) -> "Window | None":
53
"""Get currently focused window."""
54
55
@property
56
def windows(self) -> list["Window"]:
57
"""Get list of managed windows."""
58
59
def screenshot(self) -> str:
60
"""Capture screenshot of all windows."""
61
```
62
63
### Window
64
65
Desktop-style window widget extending Container with title bar, borders, and window controls.
66
67
```python { .api }
68
class Window(Container):
69
"""Desktop-style window widget."""
70
71
def __init__(self, *widgets, title: str = "", **attrs):
72
"""
73
Create window widget.
74
75
Parameters:
76
- widgets: Child widgets for window content
77
- title (str): Window title text
78
- is_modal (bool, optional): Whether window is modal
79
- is_noblur (bool, optional): Whether window stays in focus
80
- is_noresize (bool, optional): Whether window can be resized
81
"""
82
83
@property
84
def title(self) -> str:
85
"""Get window title."""
86
87
@title.setter
88
def title(self, value: str):
89
"""Set window title."""
90
91
def close(self):
92
"""Close window."""
93
94
def minimize(self):
95
"""Minimize window."""
96
97
def maximize(self):
98
"""Maximize window."""
99
100
def center(self, where: CenteringPolicy = None):
101
"""Center window on screen."""
102
103
def move(self, pos: tuple[int, int]):
104
"""Move window to position."""
105
106
def resize(self, size: tuple[int, int]):
107
"""Resize window."""
108
```
109
110
### Compositor
111
112
Efficient window rendering system that handles overlapping windows, damage tracking, and optimized screen updates.
113
114
```python { .api }
115
class Compositor:
116
"""Window compositing and rendering system."""
117
118
def __init__(self):
119
"""Initialize compositor."""
120
121
def render(self):
122
"""Render all windows to screen."""
123
124
def damage(self, window: Window):
125
"""Mark window as needing redraw."""
126
127
def set_target_fps(self, fps: int):
128
"""Set target framerate for rendering."""
129
130
@property
131
def fps(self) -> float:
132
"""Get current rendering framerate."""
133
```
134
135
### Layout Management
136
137
Window layout system for organizing windows in predefined arrangements.
138
139
```python { .api }
140
class Layout:
141
"""Window layout management."""
142
143
def __init__(self, name: str):
144
"""
145
Create layout configuration.
146
147
Parameters:
148
- name (str): Layout identifier
149
"""
150
151
def apply(self, manager: WindowManager):
152
"""Apply layout to window manager."""
153
154
def add_slot(self, name: str, area: tuple[int, int, int, int]):
155
"""
156
Add layout slot.
157
158
Parameters:
159
- name (str): Slot identifier
160
- area (tuple): (x, y, width, height) area definition
161
"""
162
```
163
164
## Usage Examples
165
166
### Basic Window Application
167
168
```python
169
import pytermgui as ptg
170
171
def main():
172
# Create window manager
173
with ptg.WindowManager() as manager:
174
# Create main window
175
window = ptg.Window(
176
"[bold]Welcome to PyTermGUI",
177
"",
178
ptg.Label("This is a window with content"),
179
ptg.Button("Click me", lambda btn: print("Clicked!")),
180
"",
181
ptg.Button("Exit", lambda btn: manager.stop()),
182
title="My Application",
183
width=50,
184
height=15
185
)
186
187
# Add window to manager
188
manager.add(window)
189
190
# Start event loop
191
# This will block until manager.stop() is called
192
193
if __name__ == "__main__":
194
main()
195
```
196
197
### Multi-Window Application
198
199
```python
200
import pytermgui as ptg
201
202
def create_settings_window(manager):
203
"""Create settings dialog."""
204
settings = ptg.Window(
205
"[bold]Settings",
206
"",
207
ptg.Splitter(
208
ptg.Label("Theme:"),
209
ptg.Toggle(("Dark", "Light"))
210
),
211
ptg.Splitter(
212
ptg.Label("Sound:"),
213
ptg.Checkbox(checked=True)
214
),
215
"",
216
ptg.Button("OK", lambda btn: settings.close()),
217
title="Settings",
218
width=40,
219
height=10
220
)
221
return settings
222
223
def main():
224
with ptg.WindowManager() as manager:
225
# Main application window
226
main_window = ptg.Window(
227
"[bold]Main Application",
228
"",
229
ptg.Button("Open Settings",
230
lambda btn: manager.add(create_settings_window(manager))),
231
ptg.Button("Exit", lambda btn: manager.stop()),
232
title="App",
233
width=60,
234
height=20
235
)
236
237
manager.add(main_window)
238
239
if __name__ == "__main__":
240
main()
241
```
242
243
### Modal Dialog
244
245
```python
246
import pytermgui as ptg
247
248
def show_confirmation(manager, message, callback):
249
"""Show modal confirmation dialog."""
250
def on_yes(btn):
251
dialog.close()
252
callback(True)
253
254
def on_no(btn):
255
dialog.close()
256
callback(False)
257
258
dialog = ptg.Window(
259
f"[bold]{message}",
260
"",
261
ptg.Splitter(
262
ptg.Button("Yes", on_yes),
263
ptg.Button("No", on_no)
264
),
265
title="Confirm",
266
is_modal=True, # Modal window
267
width=40,
268
height=8
269
)
270
271
manager.add(dialog)
272
dialog.center() # Center on screen
273
274
# Usage
275
def handle_delete():
276
show_confirmation(
277
manager,
278
"Delete this item?",
279
lambda result: print(f"User selected: {result}")
280
)
281
```
282
283
### Window with Custom Layout
284
285
```python
286
import pytermgui as ptg
287
288
def create_dashboard():
289
"""Create dashboard with multiple panels."""
290
291
# Create layout panels as separate containers
292
left_panel = ptg.Container(
293
"[bold]Navigation",
294
"",
295
ptg.Button("Home", lambda: switch_view("home")),
296
ptg.Button("Settings", lambda: switch_view("settings")),
297
ptg.Button("About", lambda: switch_view("about")),
298
width=20
299
)
300
301
main_panel = ptg.Container(
302
"[bold]Main Content",
303
"",
304
ptg.Label("Welcome to the dashboard"),
305
ptg.Label("Select an option from the navigation"),
306
width=50
307
)
308
309
# Combine panels horizontally
310
layout = ptg.Splitter(left_panel, main_panel)
311
312
window = ptg.Window(
313
layout,
314
title="Dashboard",
315
width=75,
316
height=25
317
)
318
319
return window
320
321
with ptg.WindowManager() as manager:
322
dashboard = create_dashboard()
323
manager.add(dashboard)
324
```
325
326
### Context Manager Usage
327
328
```python
329
import pytermgui as ptg
330
331
# WindowManager as context manager automatically handles cleanup
332
with ptg.WindowManager() as manager:
333
# Create and add windows
334
window = ptg.Window("Content", title="Auto-managed")
335
manager.add(window)
336
337
# Event loop runs here
338
# Cleanup happens automatically when exiting context
339
```
340
341
### Window Events and Callbacks
342
343
```python
344
import pytermgui as ptg
345
346
def on_window_close(window):
347
"""Handle window close event."""
348
print(f"Window '{window.title}' is closing")
349
350
def on_window_focus(window):
351
"""Handle window focus event."""
352
print(f"Window '{window.title}' gained focus")
353
354
# Create window with event handlers
355
window = ptg.Window(
356
"Content",
357
title="Event Demo",
358
on_close=on_window_close,
359
on_focus=on_window_focus
360
)
361
```