0
# Utilities and System Classes
1

2
Utility classes, system services, and helper functionality for pyTermTk applications including timers, clipboard access, keyboard shortcuts, and application helpers.
3

4
## Capabilities
5

6
### Helper Utilities
7

8
TTkHelper provides static utility methods for common application tasks and system operations.
9

10
```python { .api }
11
class TTkHelper:
12
    @staticmethod
13
    def quit():
14
        """Quit the current application."""
15
    
16
    @staticmethod
17
    def aboutTermTk():
18
        """Show information about pyTermTk library."""
19
    
20
    @staticmethod
21
    def getTerminalSize():
22
        """Get current terminal size as (width, height)."""
23
    
24
    @staticmethod
25
    def updateAll():
26
        """Force update of all widgets."""
27
    
28
    @staticmethod
29
    def overlay(widget):
30
        """Add widget as overlay on top of all other widgets."""
31
    
32
    @staticmethod
33
    def removeOverlayAndChild(widget):
34
        """Remove widget from overlay and destroy."""
35
    
36
    # Signals
37
    quitEvent: pyTTkSignal  # Emitted when application quit is requested
38
```
39

40
### Timer System
41

42
TTkTimer provides timed events and periodic callbacks for animations and scheduled tasks.
43

44
```python { .api }
45
class TTkTimer:
46
    def __init__(self):
47
        """Initialize a timer object."""
48
    
49
    def start(self, sec=0.0):
50
        """
51
        Start the timer.
52
        
53
        Parameters:
54
        - sec (float): Timeout in seconds (0.0 for immediate single-shot)
55
        """
56
    
57
    def stop(self):
58
        """Stop the timer."""
59
    
60
    def quit(self):
61
        """Stop and cleanup the timer."""
62
    
63
    def isActive(self):
64
        """Check if timer is currently active."""
65
    
66
    def setSingleShot(self, singleShot):
67
        """Set whether timer fires once or repeatedly."""
68
    
69
    def isSingleShot(self):
70
        """Check if timer is single-shot."""
71
    
72
    def setInterval(self, sec):
73
        """Set timer interval in seconds."""
74
    
75
    def interval(self):
76
        """Get timer interval."""
77
    
78
    # Signals
79
    timeout: pyTTkSignal  # Emitted when timer expires
80
```
81

82
### Clipboard Access
83

84
TTkClipboard provides system clipboard integration for copy/paste operations.
85

86
```python { .api }
87
class TTkClipboard:
88
    @staticmethod
89
    def setText(text):
90
        """
91
        Set text content to system clipboard.
92
        
93
        Parameters:
94
        - text (str): Text to copy to clipboard
95
        """
96
    
97
    @staticmethod
98
    def text():
99
        """
100
        Get text content from system clipboard.
101
        
102
        Returns:
103
        - str: Clipboard text content
104
        """
105
    
106
    @staticmethod
107
    def clear():
108
        """Clear clipboard content."""
109
    
110
    @staticmethod
111
    def hasText():
112
        """Check if clipboard contains text."""
113
```
114

115
### Spacer Widget
116

117
TTkSpacer provides invisible spacing for layouts.
118

119
```python { .api }
120
class TTkSpacer(TTkWidget):
121
    def __init__(self, parent=None, **kwargs):
122
        """
123
        Initialize a spacer widget.
124
        
125
        Parameters:
126
        - sizePolicy: Size policy for expansion behavior
127
        """
128
    
129
    def setSizePolicy(self, policy):
130
        """Set the size policy for space expansion."""
131
    
132
    def sizePolicy(self):
133
        """Get the size policy."""
134
```
135

136
### Menu System
137

138
TTkMenuBarLayout and TTkMenu provide menu bar and dropdown menu functionality.
139

140
```python { .api }
141
class TTkMenuBarLayout(TTkLayout):
142
    def __init__(self, **kwargs):
143
        """Initialize a menu bar layout."""
144
    
145
    def addMenu(self, text, data=None, checkable=False, checked=False, alignment=TTkK.LEFT_ALIGN):
146
        """
147
        Add a menu to the menu bar.
148
        
149
        Parameters:
150
        - text (str): Menu text
151
        - data: Associated data
152
        - checkable (bool): Whether menu can be checked
153
        - checked (bool): Initial checked state
154
        - alignment: Menu alignment
155
        
156
        Returns:
157
        - TTkMenuButton: The created menu button
158
        """
159
    
160
    def clear(self):
161
        """Clear all menus."""
162

163
class TTkMenu(TTkContainer):
164
    def __init__(self, parent=None, **kwargs):
165
        """Initialize a menu widget."""
166
    
167
    def addAction(self, text, callback=None, data=None, checkable=False, checked=False):
168
        """Add an action to the menu."""
169
    
170
    def addSeparator(self):
171
        """Add a separator line to the menu."""
172
    
173
    def addSubMenu(self, text, submenu):
174
        """Add a submenu."""
175
    
176
    def clear(self):
177
        """Clear all menu items."""
178
    
179
    def exec(self, pos=None):
180
        """Execute the menu at specified position."""
181
    
182
    # Signals
183
    triggered: pyTTkSignal    # Emitted when menu item is triggered
184
    aboutToShow: pyTTkSignal  # Emitted before menu is shown
185
    aboutToHide: pyTTkSignal  # Emitted before menu is hidden
186

187
class TTkMenuButton(TTkButton):
188
    def __init__(self, parent=None, **kwargs):
189
        """Initialize a menu button."""
190
    
191
    def setMenu(self, menu):
192
        """Set the dropdown menu."""
193
    
194
    def menu(self):
195
        """Get the dropdown menu."""
196
```
197

198
## Usage Examples
199

200
### Timer Example
201

202
```python
203
import TermTk as ttk
204

205
root = ttk.TTk()
206
container = ttk.TTkContainer(parent=root)
207

208
# Create a label to show time
209
time_label = ttk.TTkLabel(parent=container, text="Timer: 0", pos=(5, 5))
210

211
# Create timer
212
timer = ttk.TTkTimer()
213
counter = 0
214

215
@ttk.pyTTkSlot()
216
def update_timer():
217
    global counter
218
    counter += 1
219
    time_label.setText(f"Timer: {counter}")
220

221
timer.timeout.connect(update_timer)
222
timer.start(1.0)  # Update every second
223

224
root.mainloop()
225
```
226

227
### Clipboard Example
228

229
```python
230
import TermTk as ttk
231

232
root = ttk.TTk()
233
container = ttk.TTkContainer(parent=root)
234
layout = ttk.TTkVBoxLayout()
235

236
# Text edit for clipboard operations
237
text_edit = ttk.TTkTextEdit()
238
text_edit.setText("Sample text for clipboard operations")
239

240
# Buttons for clipboard operations
241
copy_btn = ttk.TTkButton(text="Copy to Clipboard")
242
paste_btn = ttk.TTkButton(text="Paste from Clipboard")
243

244
@ttk.pyTTkSlot()
245
def copy_text():
246
    selected = text_edit.selectedText()
247
    if selected:
248
        ttk.TTkClipboard.setText(selected)
249
    else:
250
        ttk.TTkClipboard.setText(text_edit.text())
251

252
@ttk.pyTTkSlot()
253
def paste_text():
254
    clipboard_text = ttk.TTkClipboard.text()
255
    if clipboard_text:
256
        text_edit.insertText(clipboard_text)
257

258
copy_btn.clicked.connect(copy_text)
259
paste_btn.clicked.connect(paste_text)
260

261
# Layout
262
button_layout = ttk.TTkHBoxLayout()
263
button_layout.addWidget(copy_btn)
264
button_layout.addWidget(paste_btn)
265

266
layout.addWidget(text_edit)
267
layout.addLayout(button_layout)
268

269
container.setLayout(layout)
270
root.mainloop()
271
```
272

273
### Menu System Example
274

275
```python
276
import TermTk as ttk
277

278
root = ttk.TTk()
279
app = ttk.TTkAppTemplate(parent=root, title="Menu Example")
280

281
# Get menu bar from app template
282
menu_bar = app.menuBar()
283

284
# File menu
285
file_menu = menu_bar.addMenu("File")
286
file_menu.addAction("New", lambda: print("New file"))
287
file_menu.addAction("Open", lambda: print("Open file"))
288
file_menu.addSeparator()
289
file_menu.addAction("Save", lambda: print("Save file"))
290
file_menu.addAction("Save As", lambda: print("Save As"))
291
file_menu.addSeparator()
292
file_menu.addAction("Exit", ttk.TTkHelper.quit)
293

294
# Edit menu
295
edit_menu = menu_bar.addMenu("Edit")
296
edit_menu.addAction("Undo", lambda: print("Undo"))
297
edit_menu.addAction("Redo", lambda: print("Redo"))
298
edit_menu.addSeparator()
299
edit_menu.addAction("Cut", lambda: print("Cut"))
300
edit_menu.addAction("Copy", lambda: print("Copy"))
301
edit_menu.addAction("Paste", lambda: print("Paste"))
302

303
# View menu with checkable items
304
view_menu = menu_bar.addMenu("View")
305
view_menu.addAction("Show Toolbar", checkable=True, checked=True)
306
view_menu.addAction("Show Status Bar", checkable=True, checked=True)
307
view_menu.addSeparator()
308
view_menu.addAction("Full Screen", lambda: print("Toggle full screen"))
309

310
# Help menu
311
help_menu = menu_bar.addMenu("Help")
312
help_menu.addAction("About", ttk.TTkHelper.aboutTermTk)
313
help_menu.addAction("Documentation", lambda: print("Show docs"))
314

315
# Set central widget
316
central = ttk.TTkContainer()
317
layout = ttk.TTkVBoxLayout()
318
layout.addWidget(ttk.TTkLabel(text="Application with menu system"))
319
central.setLayout(layout)
320
app.setCentralWidget(central)
321

322
root.mainloop()
323
```