0
# Asciimatics
1

2
A comprehensive cross-platform Python library that provides full-screen text UI capabilities and ASCII animation functionality. Asciimatics serves as a modern replacement for curses libraries, offering coloured/styled text rendering with 256-color terminal support and unicode characters (including CJK languages), precise cursor positioning, non-blocking keyboard input with unicode support, mouse input handling, console resize detection, and screen scraping capabilities.
3

4
## Package Information
5

6
- **Package Name**: asciimatics
7
- **Language**: Python
8
- **Installation**: `pip install asciimatics`
9
- **Version**: 1.15.0
10
- **License**: Apache 2.0
11

12
## Core Imports
13

14
```python
15
import asciimatics
16
from asciimatics.screen import Screen, ManagedScreen
17
from asciimatics.scene import Scene
18
```
19

20
Common patterns for animations:
21

22
```python
23
from asciimatics.effects import Print, Stars, Matrix
24
from asciimatics.renderers import FigletText, Fire
25
from asciimatics.screen import ManagedScreen
26
```
27

28
For text-based UIs:
29

30
```python
31
from asciimatics.widgets import Frame, Layout, Button, Text, Label
32
from asciimatics.scene import Scene
33
from asciimatics.screen import ManagedScreen
34
```
35

36
## Basic Usage
37

38
### Simple Animation
39

40
```python
41
from asciimatics.screen import ManagedScreen
42
from asciimatics.scene import Scene
43
from asciimatics.effects import Print
44
from asciimatics.renderers import FigletText
45
from asciimatics.exceptions import ResizeScreenError
46
import sys
47

48
def demo(screen):
49
    effects = [
50
        Print(screen,
51
              FigletText("ASCIIMATICS", font='big'),
52
              screen.height // 2 - 3)
53
    ]
54
    screen.play([Scene(effects, 500)])
55

56
if __name__ == "__main__":
57
    try:
58
        ManagedScreen(demo).run()
59
    except ResizeScreenError:
60
        pass
61
```
62

63
### Text-based UI
64

65
```python
66
from asciimatics.widgets import Frame, Layout, Button, Label
67
from asciimatics.scene import Scene
68
from asciimatics.screen import ManagedScreen
69
from asciimatics.exceptions import StopApplication
70

71
class DemoFrame(Frame):
72
    def __init__(self, screen):
73
        super(DemoFrame, self).__init__(screen,
74
                                        screen.height * 2 // 3,
75
                                        screen.width * 2 // 3,
76
                                        hover_focus=True,
77
                                        title="Contact Details")
78
        layout = Layout([100], fill_frame=True)
79
        self.add_layout(layout)
80
        layout.add_widget(Label("Welcome to Asciimatics!"))
81
        layout.add_widget(Button("OK", self._ok))
82
        self.fix()
83

84
    def _ok(self):
85
        raise StopApplication("User pressed OK")
86

87
def demo(screen):
88
    screen.play([Scene([DemoFrame(screen)], -1)], stop_on_resize=True)
89

90
ManagedScreen(demo).run()
91
```
92

93
## Architecture
94

95
Asciimatics uses a layered architecture based on the Artist pattern:
96

97
- **Screen**: The main interface to the terminal, providing low-level drawing operations
98
- **Scene**: Container for effects with duration and lifecycle management
99
- **Effects**: Visual elements that can be animated over time (text, sprites, particles)
100
- **Renderers**: Components that generate drawable content (text, images, patterns)
101
- **Widgets**: UI components for building interactive applications
102
- **Canvas**: Drawing surfaces for complex graphics operations
103

104
This design enables creation of both simple animations and complex interactive applications while maintaining cross-platform compatibility across Windows, macOS, Linux, and even Android.
105

106
## Capabilities
107

108
### Screen and Display Control
109

110
Core terminal control functionality including screen management, cursor positioning, color handling, keyboard/mouse input, and cross-platform terminal operations.
111

112
```python { .api }
113
class Screen:
114
    def print_at(self, text, x, y, colour=COLOUR_WHITE, attr=A_NORMAL, bg=COLOUR_BLACK): ...
115
    def get_from(self, x, y, length): ...
116
    def clear_buffer(self, fg, attr, bg): ...
117
    def refresh(): ...
118
    def get_event(): ...
119

120
class ManagedScreen:
121
    def __init__(self, function, arguments=None, catch_interrupt=True): ...
122
    def run(self): ...
123
```
124

125
[Screen and Display Control](./screen-and-display.md)
126

127
### Effects and Animation
128

129
Comprehensive animation system with built-in effects like banners, stars, matrix rain, snow, fire, and custom sprite animations. Includes timing control, scene management, and transition effects.
130

131
```python { .api }
132
class Effect:
133
    def __init__(self, screen, start_frame=0, stop_frame=0): ...
134
    def reset(self): ...
135
    def update(self, frame_no): ...
136

137
class Print(Effect):
138
    def __init__(self, screen, renderer, y, x=None, colour=COLOUR_WHITE, attr=A_NORMAL, bg=COLOUR_BLACK, transparent=True, speed=1, clear=False): ...
139

140
class Stars(Effect):
141
    def __init__(self, screen, count, stop_frame=0): ...
142

143
class Matrix(Effect):
144
    def __init__(self, screen, stop_frame=0): ...
145
```
146

147
[Effects and Animation](./effects-and-animation.md)
148

149
### Widgets and User Interface
150

151
Complete widget toolkit for building text-based user interfaces with buttons, text inputs, lists, forms, dialogs, and layout management. Supports validation, focus handling, and event processing.
152

153
```python { .api }
154
class Frame(Effect):
155
    def __init__(self, screen, height, width, has_border=True, hover_focus=False, title=None, reduce_cpu=False): ...
156
    def add_layout(self, layout): ...
157
    def fix(self): ...
158

159
class Layout:
160
    def __init__(self, columns, fill_frame=False): ...
161
    def add_widget(self, widget, column=0): ...
162

163
class Button(Widget):
164
    def __init__(self, text, on_click, disabled=False, add_box=False): ...
165

166
class Text(Widget):
167
    def __init__(self, label=None, name=None, on_change=None, validator=None, disabled=False): ...
168
```
169

170
[Widgets and User Interface](./widgets-and-ui.md)
171

172
### Renderers
173

174
Content generation system for creating complex visual elements including ASCII art text, images, charts, patterns, and media playback. Supports both static and dynamic content generation.
175

176
```python { .api }
177
class Renderer:
178
    def render(self, frame): ...
179

180
class FigletText(StaticRenderer):
181
    def __init__(self, text, font='3x5', width=80, colour=COLOUR_WHITE): ...
182

183
class Fire(DynamicRenderer):
184
    def __init__(self, height, width, emitter, colour, bg, start_frame=0): ...
185

186
class ImageFile(StaticRenderer):
187
    def __init__(self, file_name, height=None, colours=8, bg=COLOUR_BLACK, fill_background=False, unicode_char="  "): ...
188
```
189

190
[Renderers](./renderers.md)
191

192
### Particles and Sprites
193

194
Advanced particle system for creating fireworks, explosions, rain, and other dynamic effects. Includes sprite animation support for character-based animations and custom drawable objects.
195

196
```python { .api }
197
class ParticleEffect(Effect):
198
    def __init__(self, screen, x, y, life_time, start_frame=0, stop_frame=0): ...
199

200
class StarFirework(ParticleEffect):
201
    def __init__(self, screen, x, y, life_time, firework_colour=COLOUR_WHITE, trail_colour=None, start_frame=0): ...
202

203
class Sprite(Effect):
204
    def __init__(self, screen, renderer_dict, path, colour=COLOUR_WHITE, attr=A_NORMAL, bg=COLOUR_BLACK, clear=True, start_frame=0, stop_frame=0): ...
205

206
class Sam(Sprite):
207
    def __init__(self, screen, path, start_frame=0, stop_frame=0): ...
208
```
209

210
[Particles and Sprites](./particles-and-sprites.md)
211

212
## Constants and Exceptions
213

214
### Text Attributes
215

216
```python { .api }
217
A_BOLD = 1
218
A_NORMAL = 2  
219
A_REVERSE = 3
220
A_UNDERLINE = 4
221
```
222

223
### Colors
224

225
```python { .api }
226
COLOUR_DEFAULT = -1
227
COLOUR_BLACK = 0
228
COLOUR_RED = 1
229
COLOUR_GREEN = 2
230
COLOUR_YELLOW = 3
231
COLOUR_BLUE = 4
232
COLOUR_MAGENTA = 5
233
COLOUR_CYAN = 6
234
COLOUR_WHITE = 7
235
```
236

237
### Line Styles
238

239
```python { .api }
240
ASCII_LINE = 0
241
SINGLE_LINE = 1
242
DOUBLE_LINE = 2
243
```
244

245
### Exceptions
246

247
```python { .api }
248
class ResizeScreenError(Exception):
249
    """Terminal resize error during scene playback"""
250
    def __init__(self, message, scene=None): ...
251
    @property
252
    def scene(self): ...
253

254
class StopApplication(Exception):
255
    """Signal to stop the application"""
256
    def __init__(self, message): ...
257

258
class NextScene(Exception):
259
    """Signal to move to next scene"""
260
    def __init__(self, name=None): ...
261
    @property
262
    def name(self): ...
263

264
class InvalidFields(Exception):
265
    """Form validation errors"""
266
    def __init__(self, fields): ...
267
    @property
268
    def fields(self): ...
269
```
270

271
## Event Handling
272

273
```python { .api }
274
class Event:
275
    """Base event class"""
276
    pass
277

278
class KeyboardEvent(Event):
279
    """Keyboard input event"""
280
    def __init__(self, key_code): ...
281
    @property
282
    def key_code(self): ...
283

284
class MouseEvent(Event):
285
    """Mouse input event"""
286
    def __init__(self, x, y, buttons): ...
287
    @property
288
    def x(self): ...
289
    @property
290
    def y(self): ...
291
    @property
292
    def buttons(self): ...
293
```
294

295
## Text Processing
296

297
### String Classes
298

299
```python { .api }
300
class ColouredText:
301
    """Text with embedded color codes"""
302
    def __init__(self, raw_text, parser, colour=COLOUR_WHITE, attr=A_NORMAL, bg=COLOUR_BLACK): ...
303
    @property
304
    def text(self): ...
305
    @property
306
    def colour_map(self): ...
307
```
308

309
### Parser System
310

311
```python { .api }
312
class Parser:
313
    """Abstract text parser base class"""
314
    def parse(self, text): ...
315

316
# Parser Command Constants
317
DISPLAY_TEXT = 0
318
CHANGE_COLOURS = 1
319
MOVE_ABSOLUTE = 2
320
MOVE_RELATIVE = 3
321
```
322

323
## Utilities
324

325
```python { .api }
326
def readable_mem(mem):
327
    """Convert bytes to human-readable format"""
328
    pass
329

330
def readable_timestamp(stamp):
331
    """Convert POSIX timestamp to readable format"""
332
    pass
333

334
class BoxTool:
335
    """Box drawing utility for creating bordered regions"""
336
    def __init__(self, unicode_aware, style=SINGLE_LINE): ...
337
    def box(self, width, height): ...
338
    def box_top(self, width): ...
339
    def box_bottom(self, width): ...
340
    def box_line(self, width): ...
341
```
342

343
## Animation Paths
344

345
```python { .api }
346
class Path:
347
    """Static animation path for sprite movement"""
348
    def __init__(self, screen, x, y, path): ...
349
    def next_pos(self): ...
350
    def is_finished(self, frame): ...
351

352
class DynamicPath:
353
    """Abstract base class for dynamic animation paths"""
354
    def __init__(self, screen, x, y): ...
355
    def process_event(self, event): ...
356
    def next_pos(self): ...
357
```