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
```