0
# PyTermGUI
1
2
PyTermGUI is a comprehensive Python terminal user interface (TUI) framework that enables developers to create sophisticated command-line applications with modern UI capabilities. It provides a modular widget system with mouse support, allowing for the creation of interactive terminal applications that feel more like desktop applications.
3
4
## Package Information
5
6
- **Package Name**: PyTermGUI
7
- **Package Type**: PyPI
8
- **Language**: Python
9
- **Version**: 7.7.4
10
- **Installation**: `pip install PyTermGUI`
11
- **Requirements**: Python >=3.8, wcwidth, typing_extensions
12
- **Optional Dependencies**: PyYAML (for YAML file loading)
13
14
## Core Imports
15
16
```python
17
import pytermgui as ptg
18
```
19
20
Specific imports for common functionality:
21
22
```python
23
from pytermgui import Widget, Container, Button, Label
24
from pytermgui import get_terminal, WindowManager
25
from pytermgui import Color, tim
26
```
27
28
## Basic Usage
29
30
```python
31
import pytermgui as ptg
32
33
# Create a simple application window
34
with ptg.WindowManager() as manager:
35
# Create a container with widgets
36
window = ptg.Window(
37
"[210 bold]Welcome to PyTermGUI",
38
"",
39
ptg.Button("Click me!", lambda btn: print("Button clicked!")),
40
ptg.InputField(),
41
"",
42
["Submit", lambda btn: manager.stop()],
43
title="My App"
44
)
45
46
manager.add(window)
47
```
48
49
## Architecture
50
51
PyTermGUI follows a layered architecture:
52
53
- **Widget System**: Base Widget class with inheritance hierarchy for all UI components
54
- **Layout Management**: Container-based layout with automatic sizing and positioning
55
- **Terminal Interface**: Low-level ANSI escape sequence handling and terminal capabilities
56
- **Markup Language (TIM)**: Rich text formatting with colors, styles, and layout
57
- **Event System**: Mouse and keyboard event handling with widget focus management
58
- **Animation Framework**: Smooth transitions and animated properties
59
- **Window Management**: Multi-window interface with compositing and layering
60
61
## Capabilities
62
63
### Widget System
64
65
Core widget functionality including the base Widget class, containers for layout management, and a comprehensive set of interactive UI components like buttons, input fields, checkboxes, sliders, and more.
66
67
```python { .api }
68
class Widget:
69
def __init__(self, **attrs): ...
70
71
class Container(Widget):
72
def __init__(self, *widgets, **attrs): ...
73
def add(self, widget): ...
74
75
class Label(Widget):
76
def __init__(self, value="", **attrs): ...
77
78
class Button(Widget):
79
def __init__(self, label, onclick=None, **attrs): ...
80
81
class InputField(Widget):
82
def __init__(self, value="", prompt="", **attrs): ...
83
```
84
85
[Widget System](./widgets.md)
86
87
### Color and Styling
88
89
Advanced color management with support for RGB, HEX, indexed terminal colors, and palette generation. Includes the TIM (Terminal Inline Markup) language for rich text formatting.
90
91
```python { .api }
92
class Color:
93
def __init__(self, value): ...
94
@property
95
def rgb(self) -> tuple[int, int, int]: ...
96
def hex(self) -> str: ...
97
98
def str_to_color(color_str: str) -> Color: ...
99
def foreground(text: str, color: str | Color) -> str: ...
100
def background(text: str, color: str | Color) -> str: ...
101
102
class MarkupLanguage:
103
def parse(self, text: str) -> list: ...
104
```
105
106
[Colors and Markup](./colors-markup.md)
107
108
### Terminal Interface
109
110
Low-level terminal control including ANSI escape sequences, cursor management, screen control, and input handling with keyboard and mouse support.
111
112
```python { .api }
113
class Terminal:
114
def __init__(self): ...
115
@property
116
def size(self) -> tuple[int, int]: ...
117
def print(self, *args, **kwargs): ...
118
119
def get_terminal() -> Terminal: ...
120
def getch(timeout: float = None) -> str: ...
121
def clear(what: str = "screen") -> None: ...
122
def move_cursor(pos: tuple[int, int]) -> None: ...
123
```
124
125
[Terminal Interface](./terminal.md)
126
127
### Window Management
128
129
Multi-window interface system with window compositing, event routing, and layout management for complex desktop-like applications.
130
131
```python { .api }
132
class WindowManager:
133
def __init__(self): ...
134
def add(self, window): ...
135
def run(self): ...
136
def stop(self): ...
137
138
class Window(Container):
139
def __init__(self, *widgets, title="", **attrs): ...
140
141
class Compositor:
142
def __init__(self): ...
143
def render(self): ...
144
```
145
146
[Window Management](./window-management.md)
147
148
### Animation System
149
150
Smooth property animations and transitions for creating dynamic user interfaces with configurable easing and timing.
151
152
```python { .api }
153
class Animator:
154
def schedule(self, animation): ...
155
def run(self): ...
156
157
class FloatAnimation:
158
def __init__(self, duration: float, start: float, end: float): ...
159
160
class AttrAnimation:
161
def __init__(self, obj, attr: str, duration: float, end_value): ...
162
163
def is_animated(obj) -> bool: ...
164
```
165
166
[Animations](./animations.md)
167
168
### File Loading and Serialization
169
170
Load widget configurations from YAML/JSON files and serialize widget states for persistence and configuration management.
171
172
```python { .api }
173
class YamlLoader:
174
def load(self, path: str): ...
175
176
class JsonLoader:
177
def load(self, path: str): ...
178
179
class Serializer:
180
def dump(self, widget) -> dict: ...
181
def load(self, data: dict): ...
182
```
183
184
[File Loading](./file-loading.md)
185
186
### Utilities and Helpers
187
188
Text processing utilities, prettification tools, syntax highlighting, and debugging helpers for development and display enhancement.
189
190
```python { .api }
191
def strip_ansi(text: str) -> str: ...
192
def strip_markup(text: str) -> str: ...
193
def real_length(text: str) -> int: ...
194
def prettify(obj) -> str: ...
195
def pprint(*items, **kwargs): ...
196
197
class Inspector:
198
def inspect(self, obj): ...
199
```
200
201
[Utilities](./utilities.md)
202
203
## Types
204
205
```python { .api }
206
from typing import Union, Optional, Callable, Any
207
from enum import Enum, IntEnum
208
209
WidgetType = Union[Widget, type[Widget]]
210
ColorType = Union[str, Color]
211
BoundCallback = Callable[..., Any]
212
213
class SizePolicy(IntEnum):
214
"""Values according to which Widget sizes are assigned."""
215
FILL = 0
216
STATIC = 1
217
RELATIVE = 2
218
219
class CenteringPolicy(IntEnum):
220
"""Policies to center Container according to."""
221
ALL: int
222
VERTICAL: int
223
HORIZONTAL: int
224
225
class HorizontalAlignment(IntEnum):
226
"""Policies to align widgets horizontally."""
227
LEFT = 0
228
CENTER = 1
229
RIGHT = 2
230
231
class VerticalAlignment(IntEnum):
232
"""Vertical alignment options for widgets."""
233
TOP = 0
234
CENTER = 1
235
BOTTOM = 2
236
237
class Overflow(IntEnum):
238
"""Overflow policies implemented by Container."""
239
HIDE = 0
240
SCROLL = 1
241
RESIZE = 2
242
AUTO = 9999
243
244
class WidgetChange(Enum):
245
"""The type of change that happened within a widget."""
246
LINES: str
247
SIZE: str
248
WIDTH: str
249
HEIGHT: str
250
```
251
252
## Global Instances
253
254
PyTermGUI provides several global instances for common functionality:
255
256
```python { .api }
257
# Global terminal instance
258
terminal: Terminal
259
260
# Global TIM markup processor
261
tim: MarkupLanguage
262
263
# Global animation manager
264
animator: Animator
265
266
# Global input keys instance
267
keys: Keys
268
```