0
# Core Application and Widgets
1
2
The foundational classes and widgets that form the basis of pyTermTk applications, including the main application class, base widget functionality, and essential UI components.
3
4
## Capabilities
5
6
### Main Application Class
7
8
The TTk class serves as the main application container and event loop manager for pyTermTk applications.
9
10
```python { .api }
11
class TTk:
12
def __init__(self, **kwargs):
13
"""
14
Initialize the main application.
15
16
Parameters:
17
- mouseTrack (bool): Enable mouse tracking (default: True)
18
- sigmask (bool): Enable signal masking (default: True)
19
"""
20
21
def mainloop(self):
22
"""Start the main event loop."""
23
24
def quit(self):
25
"""Quit the application and exit the main loop."""
26
27
def addWidget(self, widget):
28
"""Add a widget to the root container."""
29
30
def removeWidget(self, widget):
31
"""Remove a widget from the root container."""
32
33
def setMaxSize(self, size):
34
"""Set the maximum size of the terminal."""
35
36
def getCanvas(self):
37
"""Get the main canvas for drawing operations."""
38
```
39
40
### Base Widget Class
41
42
TTkWidget is the base class for all UI components, providing fundamental functionality for positioning, sizing, event handling, and drawing.
43
44
```python { .api }
45
class TTkWidget:
46
def __init__(self, parent=None, **kwargs):
47
"""
48
Initialize a widget.
49
50
Parameters:
51
- parent (TTkWidget): Parent widget
52
- pos (TTkPoint): Position as (x, y) tuple
53
- size (TTkSize): Size as (width, height) tuple
54
- name (str): Widget name for identification
55
- visible (bool): Initial visibility state (default: True)
56
- enabled (bool): Initial enabled state (default: True)
57
- focusPolicy (int): Focus policy constant
58
- toolTip (str): Tooltip text
59
"""
60
61
def setParent(self, parent):
62
"""Set the parent widget."""
63
64
def parent(self):
65
"""Get the parent widget."""
66
67
def children(self):
68
"""Get list of child widgets."""
69
70
def show(self):
71
"""Show the widget."""
72
73
def hide(self):
74
"""Hide the widget."""
75
76
def isVisible(self):
77
"""Check if widget is visible."""
78
79
def setVisible(self, visible):
80
"""Set widget visibility."""
81
82
def setEnabled(self, enabled):
83
"""Set widget enabled state."""
84
85
def isEnabled(self):
86
"""Check if widget is enabled."""
87
88
def setFocus(self):
89
"""Set keyboard focus to this widget."""
90
91
def hasFocus(self):
92
"""Check if widget has keyboard focus."""
93
94
def setFocusPolicy(self, policy):
95
"""Set the focus policy for the widget."""
96
97
def pos(self):
98
"""Get widget position as (x, y) tuple."""
99
100
def setPos(self, x, y):
101
"""Set widget position."""
102
103
def size(self):
104
"""Get widget size as (width, height) tuple."""
105
106
def setSize(self, width, height):
107
"""Set widget size."""
108
109
def geometry(self):
110
"""Get widget geometry as (x, y, width, height)."""
111
112
def setGeometry(self, x, y, width, height):
113
"""Set widget geometry."""
114
115
def move(self, x, y):
116
"""Move widget to new position."""
117
118
def resize(self, width, height):
119
"""Resize widget to new dimensions."""
120
121
def update(self):
122
"""Schedule widget for repainting."""
123
124
def setName(self, name):
125
"""Set widget name."""
126
127
def name(self):
128
"""Get widget name."""
129
130
def setToolTip(self, toolTip):
131
"""Set tooltip text."""
132
133
def toolTip(self):
134
"""Get tooltip text."""
135
136
def setMaximumSize(self, width, height):
137
"""Set maximum size constraints."""
138
139
def setMinimumSize(self, width, height):
140
"""Set minimum size constraints."""
141
142
def maximumSize(self):
143
"""Get maximum size constraints."""
144
145
def minimumSize(self):
146
"""Get minimum size constraints."""
147
148
def getCanvas(self):
149
"""Get the widget's drawing canvas."""
150
151
def paintEvent(self, canvas):
152
"""Override to implement custom painting."""
153
154
def keyEvent(self, evt):
155
"""Override to handle key events."""
156
157
def mousePressEvent(self, evt):
158
"""Override to handle mouse press events."""
159
160
def mouseReleaseEvent(self, evt):
161
"""Override to handle mouse release events."""
162
163
def mouseMoveEvent(self, evt):
164
"""Override to handle mouse move events."""
165
166
def wheelEvent(self, evt):
167
"""Override to handle mouse wheel events."""
168
169
def resizeEvent(self, width, height):
170
"""Override to handle resize events."""
171
172
def focusInEvent(self):
173
"""Override to handle focus in events."""
174
175
def focusOutEvent(self):
176
"""Override to handle focus out events."""
177
```
178
179
### Container Widget
180
181
TTkContainer extends TTkWidget to provide child widget management and layout capabilities.
182
183
```python { .api }
184
class TTkContainer(TTkWidget):
185
def __init__(self, parent=None, **kwargs):
186
"""
187
Initialize a container widget.
188
189
Parameters:
190
- layout (TTkLayout): Layout manager for child widgets
191
- padding (TTkPadding): Padding around content area
192
"""
193
194
def addWidget(self, widget):
195
"""Add a child widget to the container."""
196
197
def removeWidget(self, widget):
198
"""Remove a child widget from the container."""
199
200
def setLayout(self, layout):
201
"""Set the layout manager for this container."""
202
203
def layout(self):
204
"""Get the current layout manager."""
205
206
def setPadding(self, padding):
207
"""Set padding around the content area."""
208
209
def getPadding(self):
210
"""Get the current padding configuration."""
211
```
212
213
### Padding Configuration
214
215
TTkPadding defines padding/margins around container content.
216
217
```python { .api }
218
class TTkPadding:
219
def __init__(self, top=0, bottom=0, left=0, right=0):
220
"""
221
Initialize padding configuration.
222
223
Parameters:
224
- top (int): Top padding in characters
225
- bottom (int): Bottom padding in characters
226
- left (int): Left padding in characters
227
- right (int): Right padding in characters
228
"""
229
230
def setTop(self, top):
231
"""Set top padding."""
232
233
def setBottom(self, bottom):
234
"""Set bottom padding."""
235
236
def setLeft(self, left):
237
"""Set left padding."""
238
239
def setRight(self, right):
240
"""Set right padding."""
241
242
def top(self):
243
"""Get top padding."""
244
245
def bottom(self):
246
"""Get bottom padding."""
247
248
def left(self):
249
"""Get left padding."""
250
251
def right(self):
252
"""Get right padding."""
253
```
254
255
### Widget Utilities
256
257
Helper classes and utilities for widget management.
258
259
```python { .api }
260
class TTkSpacer(TTkWidget):
261
def __init__(self, parent=None, **kwargs):
262
"""
263
A spacer widget for layout spacing.
264
265
Parameters:
266
- sizePolicy: Size policy for expanding behavior
267
"""
268
269
def setSizePolicy(self, policy):
270
"""Set the size policy for space expansion."""
271
272
def TTkHelper:
273
@staticmethod
274
def alignCenter(size, area):
275
"""Calculate centered position within an area."""
276
277
@staticmethod
278
def alignRight(size, area):
279
"""Calculate right-aligned position within an area."""
280
281
@staticmethod
282
def alignBottom(size, area):
283
"""Calculate bottom-aligned position within an area."""
284
```
285
286
## Usage Examples
287
288
### Basic Widget Creation
289
290
```python
291
import TermTk as ttk
292
293
# Create main application
294
root = ttk.TTk()
295
296
# Create a basic widget
297
widget = ttk.TTkWidget(parent=root, pos=(10, 5), size=(20, 10))
298
widget.setName("MyWidget")
299
widget.setToolTip("This is a basic widget")
300
301
# Create a container with padding
302
container = ttk.TTkContainer(parent=root, pos=(5, 5), size=(30, 15))
303
padding = ttk.TTkPadding(top=1, bottom=1, left=2, right=2)
304
container.setPadding(padding)
305
306
# Add child widgets to container
307
child1 = ttk.TTkWidget(parent=container)
308
child2 = ttk.TTkWidget(parent=container)
309
310
# Start the application
311
root.mainloop()
312
```
313
314
### Custom Widget with Event Handling
315
316
```python
317
import TermTk as ttk
318
319
class CustomWidget(ttk.TTkWidget):
320
def __init__(self, parent=None, **kwargs):
321
super().__init__(parent=parent, **kwargs)
322
self.clicked_count = 0
323
324
def mousePressEvent(self, evt):
325
self.clicked_count += 1
326
print(f"Widget clicked {self.clicked_count} times")
327
self.update() # Trigger repaint
328
329
def paintEvent(self, canvas):
330
# Custom drawing
331
canvas.drawText((1, 1), f"Clicks: {self.clicked_count}")
332
333
# Usage
334
root = ttk.TTk()
335
custom = CustomWidget(parent=root, pos=(5, 5), size=(20, 10))
336
root.mainloop()
337
```