0
# pyTermTk
1

2
A comprehensive Text-based User Interface (TUI) library for Python that enables developers to create sophisticated terminal applications with modern UI paradigms. Evolved from pyCuT and inspired by Qt5, GTK, and tkinter APIs, pyTermTk provides a complete widget toolkit including basic widgets (buttons, labels, checkboxes) and specialized components (windows, frames, tables, trees) with a Qt-like layout system for organizing terminal interfaces.
3

4
## Package Information
5

6
- **Package Name**: pyTermTk
7
- **Language**: Python
8
- **Installation**: `pip install pyTermTk`
9
- **Minimum Python Version**: 3.9+
10

11
## Core Imports
12

13
```python
14
import TermTk
15
```
16

17
Standard import for all widgets and functionality:
18

19
```python
20
from TermTk import *
21
```
22

23
Specific imports for common components:
24

25
```python
26
from TermTk import TTk, TTkWidget, TTkWindow, TTkButton, TTkLabel
27
from TermTk import TTkGridLayout, TTkVBoxLayout, TTkHBoxLayout
28
from TermTk import TTkRadioButton, TTkComboBox, TTkSpinBox, TTkListWidget
29
```
30

31
For advanced widgets from specialized modules:
32

33
```python
34
from TermTk.TTkWidgets.Fancy import TTkFancyProgressBar
35
```
36

37
## Basic Usage
38

39
```python
40
#!/usr/bin/env python3
41

42
import sys
43
sys.path.append('../..')
44
import TermTk as ttk
45

46
# Create the main application
47
root = ttk.TTk()
48

49
# Create a window with title
50
win = ttk.TTkWindow(parent=root, pos=(1,1), size=(50,20), title="Hello World")
51

52
# Add a label
53
label = ttk.TTkLabel(parent=win, pos=(5, 3), text="Hello, pyTermTk!")
54

55
# Add a button
56
button = ttk.TTkButton(parent=win, pos=(5, 6), size=(15, 3), text="Click Me!")
57

58
# Button click handler
59
@ttk.pyTTkSlot()
60
def onButtonClick():
61
    label.setText("Button was clicked!")
62

63
button.clicked.connect(onButtonClick)
64

65
# Start the application
66
root.mainloop()
67
```
68

69
## Architecture
70

71
pyTermTk follows a layered architecture inspired by Qt's design patterns:
72

73
- **TTk**: Main application class managing the event loop and terminal interface
74
- **TTkWidget**: Base class for all UI components with event handling and drawing capabilities
75
- **TTkContainer**: Widgets that can contain other widgets with layout management
76
- **TTkLayout**: Layout managers for automatic widget positioning (Grid, Box layouts)
77
- **TTkCanvas**: Drawing surface with text, color, and Unicode support
78
- **Signal/Slot System**: Event-driven communication between widgets
79

80
The library supports true color rendering, full Unicode character handling including emojis, and cross-platform compatibility across Linux, macOS, Windows, and HTML5 environments through technologies like Pyodide.
81

82
## Capabilities
83

84
### Core Application and Widgets
85

86
The foundational classes and widgets that form the basis of pyTermTk applications, including the main application class, base widget functionality, and essential UI components.
87

88
```python { .api }
89
class TTk:
90
    def __init__(self, **kwargs): ...
91
    def mainloop(self): ...
92
    def quit(self): ...
93

94
class TTkWidget:
95
    def __init__(self, parent=None, **kwargs): ...
96
    def setParent(self, parent): ...
97
    def show(self): ...
98
    def hide(self): ...
99
    def update(self): ...
100
```
101

102
[Core Application and Widgets](./core-widgets.md)
103

104
### Layout Management
105

106
Automatic positioning and sizing of widgets using layout managers including grid layouts for complex arrangements and box layouts for linear organization.
107

108
```python { .api }
109
class TTkGridLayout:
110
    def __init__(self): ...
111
    def addWidget(self, widget, row, col, rowspan=1, colspan=1): ...
112

113
class TTkVBoxLayout:
114
    def __init__(self): ...
115
    def addWidget(self, widget): ...
116

117
class TTkHBoxLayout:
118
    def __init__(self): ...
119
    def addWidget(self, widget): ...
120
```
121

122
[Layout Management](./layouts.md)
123

124
### Input Widgets
125

126
Interactive widgets for user input including buttons, text fields, checkboxes, combo boxes, radio buttons, sliders, spin boxes, and list widgets for comprehensive form controls.
127

128
```python { .api }
129
class TTkButton:
130
    def __init__(self, parent=None, text="", **kwargs): ...
131
    clicked: pyTTkSignal
132

133
class TTkLineEdit:
134
    def __init__(self, parent=None, text="", **kwargs): ...
135
    def setText(self, text): ...
136
    def text(self): ...
137
    textChanged: pyTTkSignal
138

139
class TTkCheckbox:
140
    def __init__(self, parent=None, text="", **kwargs): ...
141
    def setChecked(self, checked): ...
142
    def isChecked(self): ...
143
    toggled: pyTTkSignal
144

145
class TTkRadioButton:
146
    def __init__(self, parent=None, **kwargs): ...
147
    def setChecked(self, checked): ...
148
    def isChecked(self): ...
149
    toggled: pyTTkSignal
150

151
class TTkComboBox:
152
    def __init__(self, parent=None, **kwargs): ...
153
    def addItem(self, text, userData=None): ...
154
    def currentText(self): ...
155
    currentIndexChanged: pyTTkSignal
156

157
class TTkSpinBox:
158
    def __init__(self, parent=None, **kwargs): ...
159
    def setValue(self, value): ...
160
    def value(self): ...
161
    valueChanged: pyTTkSignal
162

163
class TTkSlider:
164
    def __init__(self, parent=None, **kwargs): ...
165
    def setValue(self, value): ...
166
    def value(self): ...
167
    sliderMoved: pyTTkSignal
168

169
class TTkListWidget:
170
    def __init__(self, parent=None, **kwargs): ...
171
    def addItems(self, items): ...
172
    def currentItem(self): ...
173
    itemClicked: pyTTkSignal
174
```
175

176
[Input Widgets](./input-widgets.md)
177

178
### Display Widgets
179

180
Widgets for displaying information including labels, images, progress bars, scroll bars, and other visual components.
181

182
```python { .api }
183
class TTkLabel:
184
    def __init__(self, parent=None, text="", **kwargs): ...
185
    def setText(self, text): ...
186
    def text(self): ...
187

188
class TTkImage:
189
    def __init__(self, parent=None, **kwargs): ...
190
    def setImage(self, image): ...
191

192
class TTkGraph:
193
    def __init__(self, parent=None, **kwargs): ...
194
    def addData(self, data): ...
195

196
class TTkFancyProgressBar:
197
    def __init__(self, parent=None, **kwargs): ...
198
    def setValue(self, value): ...
199
    def value(self): ...
200
    valueChanged: pyTTkSignal
201

202
class TTkScrollBar:
203
    def __init__(self, parent=None, **kwargs): ...
204
    def setValue(self, value): ...
205
    def value(self): ...
206
    valueChanged: pyTTkSignal
207
```
208

209
[Display Widgets](./display-widgets.md)
210

211
### Container Widgets
212

213
Specialized container widgets including windows, frames, splitters, scrollable areas, tab widgets, and application templates for organizing and structuring complex UIs.
214

215
```python { .api }
216
class TTkWindow:
217
    def __init__(self, parent=None, title="", **kwargs): ...
218
    def setTitle(self, title): ...
219
    def title(self): ...
220

221
class TTkFrame:
222
    def __init__(self, parent=None, **kwargs): ...
223

224
class TTkSplitter:
225
    def __init__(self, parent=None, orientation=TTkConstant.Vertical, **kwargs): ...
226
    def addWidget(self, widget): ...
227

228
class TTkScrollArea:
229
    def __init__(self, parent=None, **kwargs): ...
230
    def setWidget(self, widget): ...
231
```
232

233
[Container Widgets](./container-widgets.md)
234

235
### Text Editing
236

237
Multi-line text editing capabilities with syntax highlighting, line numbers, and advanced text manipulation features.
238

239
```python { .api }
240
class TTkTextEdit:
241
    def __init__(self, parent=None, **kwargs): ...
242
    def setText(self, text): ...
243
    def text(self): ...
244
    def append(self, text): ...
245
    def clear(self): ...
246
    textChanged: pyTTkSignal
247
```
248

249
[Text Editing](./text-editing.md)
250

251
### Model-View Widgets
252

253
Data-driven widgets using the Model-View pattern including tables and trees with support for various data sources and custom models.
254

255
```python { .api }
256
class TTkTable:
257
    def __init__(self, parent=None, **kwargs): ...
258
    def setModel(self, model): ...
259

260
class TTkTree:
261
    def __init__(self, parent=None, **kwargs): ...
262
    def setModel(self, model): ...
263

264
class TTkAbstractTableModel:
265
    def __init__(self): ...
266
    def rowCount(self): ...
267
    def columnCount(self): ...
268
    def data(self, index): ...
269
```
270

271
[Model-View Widgets](./model-view.md)
272

273
### Color and Drawing
274

275
Advanced color support, drawing capabilities, and theming system with ANSI color support, gradients, and custom drawing operations.
276

277
```python { .api }
278
class TTkColor:
279
    def __init__(self, fg=None, bg=None, **kwargs): ...
280
    def foreground(self): ...
281
    def background(self): ...
282

283
class TTkCanvas:
284
    def __init__(self, **kwargs): ...
285
    def drawText(self, pos, text, color=None): ...
286
    def drawChar(self, pos, char, color=None): ...
287

288
class TTkString:
289
    def __init__(self, text="", color=None): ...
290
    def __str__(self): ...
291
```
292

293
[Color and Drawing](./color-drawing.md)
294

295
### Event System
296

297
Signal-slot communication system for event handling and inter-widget communication patterns.
298

299
```python { .api }
300
class pyTTkSignal:
301
    def __init__(self): ...
302
    def connect(self, slot): ...
303
    def disconnect(self, slot=None): ...
304
    def emit(self, *args): ...
305

306
def pyTTkSlot():
307
    """Decorator for slot functions"""
308
    ...
309
```
310

311
[Event System](./event-system.md)
312

313
### File and Dialog Operations
314

315
File operations, dialog widgets, and cross-platform utilities for common application tasks.
316

317
```python { .api }
318
class TTkFileDialogPicker:
319
    def __init__(self, parent=None, **kwargs): ...
320
    def getOpenFileName(self): ...
321
    def getSaveFileName(self): ...
322

323
class TTkMessageBox:
324
    def __init__(self, parent=None, **kwargs): ...
325
    def information(self, title, message): ...
326
    def warning(self, title, message): ...
327
    def critical(self, title, message): ...
328
```
329

330
[File and Dialog Operations](./file-dialogs.md)
331

332
### Utilities and System Classes
333

334
Utility classes, system services, and helper functionality including timers, clipboard access, menu systems, and application helpers.
335

336
```python { .api }
337
class TTkHelper:
338
    @staticmethod
339
    def quit(): ...
340
    @staticmethod
341
    def aboutTermTk(): ...
342
    @staticmethod
343
    def getTerminalSize(): ...
344
    quitEvent: pyTTkSignal
345

346
class TTkTimer:
347
    def __init__(self): ...
348
    def start(self, sec=0.0): ...
349
    def stop(self): ...
350
    timeout: pyTTkSignal
351

352
class TTkClipboard:
353
    @staticmethod
354
    def setText(text): ...
355
    @staticmethod
356
    def text(): ...
357

358
class TTkSpacer:
359
    def __init__(self, parent=None, **kwargs): ...
360

361
class TTkMenuBarLayout:
362
    def __init__(self, **kwargs): ...
363
    def addMenu(self, text, **kwargs): ...
364

365
class TTkMenu:
366
    def __init__(self, parent=None, **kwargs): ...
367
    def addAction(self, text, callback=None, **kwargs): ...
368
    def exec(self, pos=None): ...
369
```
370

371
[Utilities and System Classes](./utilities.md)
372

373
## Types
374

375
Common type definitions used throughout the pyTermTk API:
376

377
```python { .api }
378
# Type aliases for common coordinate and size representations
379
TTkPoint = Tuple[int, int]
380
TTkSize = Tuple[int, int]
381

382
# Constant definitions for common values
383
class TTkConstant:
384
    # Focus policies
385
    NoFocus = 0
386
    TabFocus = 1
387
    ClickFocus = 2
388
    StrongFocus = 3
389
    
390
    # Alignment constants
391
    LEFT_ALIGN = 0x0001
392
    RIGHT_ALIGN = 0x0002
393
    CENTER_ALIGN = 0x0004
394
    
395
    # Orientation
396
    Horizontal = 0
397
    Vertical = 1
398
    
399
    # Mouse buttons
400
    LeftButton = 1
401
    RightButton = 2
402
    MiddleButton = 4
403

404
# Alias for convenience
405
TTkK = TTkConstant
406
```