0
# Input Widgets
1
2
Interactive widgets for user input including buttons, text fields, checkboxes, combo boxes, and other form controls.
3
4
## Capabilities
5
6
### Button Widget
7
8
TTkButton provides clickable button functionality with text labels and customizable appearance.
9
10
```python { .api }
11
class TTkButton(TTkWidget):
12
def __init__(self, parent=None, text="", **kwargs):
13
"""
14
Initialize a button widget.
15
16
Parameters:
17
- text (str): Button text label
18
- border (bool): Whether to show border (default: True)
19
- checkable (bool): Whether button can be toggled (default: False)
20
- checked (bool): Initial checked state for checkable buttons
21
"""
22
23
def setText(self, text):
24
"""Set the button text."""
25
26
def text(self):
27
"""Get the button text."""
28
29
def setCheckable(self, checkable):
30
"""Set whether the button is checkable/toggleable."""
31
32
def isCheckable(self):
33
"""Check if the button is checkable."""
34
35
def setChecked(self, checked):
36
"""Set the checked state (for checkable buttons)."""
37
38
def isChecked(self):
39
"""Get the checked state."""
40
41
def click(self):
42
"""Programmatically click the button."""
43
44
# Signals
45
clicked: pyTTkSignal # Emitted when button is clicked
46
pressed: pyTTkSignal # Emitted when button is pressed down
47
released: pyTTkSignal # Emitted when button is released
48
toggled: pyTTkSignal # Emitted when checkable button is toggled
49
```
50
51
### Line Edit Widget
52
53
TTkLineEdit provides single-line text input functionality with validation and formatting options.
54
55
```python { .api }
56
class TTkLineEdit(TTkWidget):
57
def __init__(self, parent=None, text="", **kwargs):
58
"""
59
Initialize a line edit widget.
60
61
Parameters:
62
- text (str): Initial text content
63
- inputType (int): Input type for validation
64
- readOnly (bool): Whether the field is read-only
65
- maxLength (int): Maximum text length
66
- placeholderText (str): Placeholder text when empty
67
"""
68
69
def setText(self, text):
70
"""Set the text content."""
71
72
def text(self):
73
"""Get the text content."""
74
75
def clear(self):
76
"""Clear the text content."""
77
78
def copy(self):
79
"""Copy selected text to clipboard."""
80
81
def cut(self):
82
"""Cut selected text to clipboard."""
83
84
def paste(self):
85
"""Paste text from clipboard."""
86
87
def selectAll(self):
88
"""Select all text."""
89
90
def setReadOnly(self, readOnly):
91
"""Set read-only state."""
92
93
def isReadOnly(self):
94
"""Check if field is read-only."""
95
96
def setMaxLength(self, maxLength):
97
"""Set maximum text length."""
98
99
def maxLength(self):
100
"""Get maximum text length."""
101
102
def setPlaceholderText(self, text):
103
"""Set placeholder text."""
104
105
def placeholderText(self):
106
"""Get placeholder text."""
107
108
def setInputType(self, inputType):
109
"""Set input validation type."""
110
111
def setEchoMode(self, mode):
112
"""Set echo mode for password fields."""
113
114
def hasSelectedText(self):
115
"""Check if text is selected."""
116
117
def selectedText(self):
118
"""Get selected text."""
119
120
def cursorPosition(self):
121
"""Get cursor position."""
122
123
def setCursorPosition(self, position):
124
"""Set cursor position."""
125
126
# Signals
127
textChanged: pyTTkSignal # Emitted when text changes
128
textEdited: pyTTkSignal # Emitted when text is edited by user
129
returnPressed: pyTTkSignal # Emitted when Enter is pressed
130
editingFinished: pyTTkSignal # Emitted when editing is finished
131
```
132
133
### Checkbox Widget
134
135
TTkCheckbox provides a checkable option with text label.
136
137
```python { .api }
138
class TTkCheckbox(TTkWidget):
139
def __init__(self, parent=None, text="", **kwargs):
140
"""
141
Initialize a checkbox widget.
142
143
Parameters:
144
- text (str): Checkbox label text
145
- checked (bool): Initial checked state
146
"""
147
148
def setText(self, text):
149
"""Set the checkbox label text."""
150
151
def text(self):
152
"""Get the checkbox label text."""
153
154
def setChecked(self, checked):
155
"""Set the checked state."""
156
157
def isChecked(self):
158
"""Get the checked state."""
159
160
def toggle(self):
161
"""Toggle the checked state."""
162
163
def setTristate(self, tristate):
164
"""Enable/disable tristate mode."""
165
166
def isTristate(self):
167
"""Check if tristate mode is enabled."""
168
169
def setCheckState(self, state):
170
"""Set check state (for tristate checkboxes)."""
171
172
def checkState(self):
173
"""Get check state."""
174
175
# Signals
176
toggled: pyTTkSignal # Emitted when checked state changes
177
clicked: pyTTkSignal # Emitted when checkbox is clicked
178
stateChanged: pyTTkSignal # Emitted when check state changes
179
```
180
181
### Radio Button Widget
182
183
TTkRadioButton provides mutually exclusive selection within a group.
184
185
```python { .api }
186
class TTkRadioButton(TTkWidget):
187
def __init__(self, parent=None, **kwargs):
188
"""
189
Initialize a radio button widget.
190
191
Parameters:
192
- radiogroup (str): Radio group name for mutual exclusion (default: 'DefaultGroup')
193
- checked (bool): Initial checked state (default: False)
194
- checkStatus (TTkK.CheckState): Initial check state
195
- text (TTkString): Radio button label text
196
"""
197
198
def setText(self, text):
199
"""Set the radio button label text."""
200
201
def text(self):
202
"""Get the radio button label text."""
203
204
def setChecked(self, checked):
205
"""Set the checked state."""
206
207
def isChecked(self):
208
"""Get the checked state."""
209
210
def setCheckState(self, state):
211
"""Set check state (for tristate support)."""
212
213
def checkState(self):
214
"""Get check state."""
215
216
def radioGroup(self):
217
"""Get the radio group name."""
218
219
def toggle(self):
220
"""Toggle the checked state."""
221
222
# Signals
223
toggled: pyTTkSignal # Emitted when checked state changes
224
clicked: pyTTkSignal # Emitted when radio button is clicked
225
```
226
227
### Combo Box Widget
228
229
TTkComboBox provides a dropdown selection widget with customizable options.
230
231
```python { .api }
232
class TTkComboBox(TTkWidget):
233
def __init__(self, parent=None, **kwargs):
234
"""
235
Initialize a combo box widget.
236
237
Parameters:
238
- list (list): Initial list of items
239
- index (int): Initial selected index (default: -1)
240
- insertPolicy (TTkK.InsertPolicy): Policy for inserting items (default: TTkK.InsertAtBottom)
241
- textAlign (TTkK.Alignment): Text alignment (default: TTkK.CENTER_ALIGN)
242
- editable (bool): Whether the combo box is editable (default: False)
243
"""
244
245
def addItem(self, text, userData=None):
246
"""Add an item to the combo box."""
247
248
def addItems(self, texts):
249
"""Add multiple items to the combo box."""
250
251
def insertItem(self, index, text, userData=None):
252
"""Insert an item at a specific index."""
253
254
def removeItem(self, index):
255
"""Remove an item at a specific index."""
256
257
def clear(self):
258
"""Clear all items."""
259
260
def count(self):
261
"""Get the number of items."""
262
263
def currentIndex(self):
264
"""Get the current selected index."""
265
266
def setCurrentIndex(self, index):
267
"""Set the current selected index."""
268
269
def currentText(self):
270
"""Get the current selected text."""
271
272
def setCurrentText(self, text):
273
"""Set the current text (for editable combo boxes)."""
274
275
def itemText(self, index):
276
"""Get text of item at index."""
277
278
def itemData(self, index):
279
"""Get user data of item at index."""
280
281
def setItemText(self, index, text):
282
"""Set text of item at index."""
283
284
def setItemData(self, index, userData):
285
"""Set user data of item at index."""
286
287
def findText(self, text):
288
"""Find index of text in items."""
289
290
def setEditable(self, editable):
291
"""Set whether combo box is editable."""
292
293
def isEditable(self):
294
"""Check if combo box is editable."""
295
296
def lineEdit(self):
297
"""Get the line edit widget for editable combo boxes."""
298
299
# Signals
300
currentIndexChanged: pyTTkSignal # Emitted when selection changes
301
currentTextChanged: pyTTkSignal # Emitted when current text changes
302
editTextChanged: pyTTkSignal # Emitted when edit text changes (editable mode)
303
```
304
305
### Spin Box Widget
306
307
TTkSpinBox provides numeric input with increment/decrement controls.
308
309
```python { .api }
310
class TTkSpinBox(TTkWidget):
311
def __init__(self, parent=None, **kwargs):
312
"""
313
Initialize a spin box widget.
314
315
Parameters:
316
- value (int): Initial value
317
- minimum (int): Minimum allowed value
318
- maximum (int): Maximum allowed value
319
- step (int): Step size for increment/decrement
320
"""
321
322
def setValue(self, value):
323
"""Set the current value."""
324
325
def value(self):
326
"""Get the current value."""
327
328
def setMinimum(self, minimum):
329
"""Set the minimum allowed value."""
330
331
def minimum(self):
332
"""Get the minimum allowed value."""
333
334
def setMaximum(self, maximum):
335
"""Set the maximum allowed value."""
336
337
def maximum(self):
338
"""Get the maximum allowed value."""
339
340
def setRange(self, minimum, maximum):
341
"""Set the value range."""
342
343
def setSingleStep(self, step):
344
"""Set the step size."""
345
346
def singleStep(self):
347
"""Get the step size."""
348
349
def stepUp(self):
350
"""Increment the value by one step."""
351
352
def stepDown(self):
353
"""Decrement the value by one step."""
354
355
def setPrefix(self, prefix):
356
"""Set text prefix."""
357
358
def prefix(self):
359
"""Get text prefix."""
360
361
def setSuffix(self, suffix):
362
"""Set text suffix."""
363
364
def suffix(self):
365
"""Get text suffix."""
366
367
# Signals
368
valueChanged: pyTTkSignal # Emitted when value changes
369
textChanged: pyTTkSignal # Emitted when displayed text changes
370
```
371
372
### Slider Widget
373
374
TTkSlider provides a sliding control for selecting values within a range.
375
376
```python { .api }
377
class TTkSlider(TTkWidget):
378
def __init__(self, parent=None, **kwargs):
379
"""
380
Initialize a slider widget.
381
382
Parameters:
383
- orientation (int): Horizontal or vertical orientation
384
- value (int): Initial value
385
- minimum (int): Minimum value
386
- maximum (int): Maximum value
387
"""
388
389
def setValue(self, value):
390
"""Set the current value."""
391
392
def value(self):
393
"""Get the current value."""
394
395
def setMinimum(self, minimum):
396
"""Set the minimum value."""
397
398
def minimum(self):
399
"""Get the minimum value."""
400
401
def setMaximum(self, maximum):
402
"""Set the maximum value."""
403
404
def maximum(self):
405
"""Get the maximum value."""
406
407
def setRange(self, minimum, maximum):
408
"""Set the value range."""
409
410
def setOrientation(self, orientation):
411
"""Set slider orientation."""
412
413
def orientation(self):
414
"""Get slider orientation."""
415
416
def setTickPosition(self, position):
417
"""Set tick mark position."""
418
419
def setTickInterval(self, interval):
420
"""Set tick mark interval."""
421
422
def setSingleStep(self, step):
423
"""Set single step size."""
424
425
def setPageStep(self, step):
426
"""Set page step size."""
427
428
# Signals
429
valueChanged: pyTTkSignal # Emitted when value changes
430
sliderPressed: pyTTkSignal # Emitted when slider is pressed
431
sliderReleased: pyTTkSignal # Emitted when slider is released
432
sliderMoved: pyTTkSignal # Emitted when slider is moved
433
rangeChanged: pyTTkSignal # Emitted when range changes
434
```
435
436
### List Widget
437
438
TTkListWidget provides a scrollable list of selectable items with search functionality.
439
440
```python { .api }
441
class TTkListWidget(TTkAbstractScrollWidget):
442
def __init__(self, parent=None, **kwargs):
443
"""
444
Initialize a list widget.
445
446
Parameters:
447
- items (list[str]): Initial list of items (default: [])
448
- selectionMode (TTkK.SelectionMode): Selection mode (default: SingleSelection)
449
- dragDropMode (TTkK.DragDropMode): Drag/drop behavior (default: NoDragDrop)
450
- showSearch (bool): Show search field (default: True)
451
"""
452
453
def addItem(self, text):
454
"""Add a single item to the list."""
455
456
def addItems(self, items):
457
"""Add multiple items to the list."""
458
459
def insertItem(self, index, text):
460
"""Insert an item at a specific index."""
461
462
def removeItem(self, index):
463
"""Remove an item at a specific index."""
464
465
def clear(self):
466
"""Clear all items from the list."""
467
468
def count(self):
469
"""Get the number of items."""
470
471
def currentItem(self):
472
"""Get the current selected item."""
473
474
def currentRow(self):
475
"""Get the current selected row index."""
476
477
def setCurrentRow(self, row):
478
"""Set the current selected row."""
479
480
def selectedItems(self):
481
"""Get list of selected items."""
482
483
def item(self, row):
484
"""Get item at specific row."""
485
486
def itemText(self, row):
487
"""Get text of item at specific row."""
488
489
def setSelectionMode(self, mode):
490
"""Set the selection mode."""
491
492
def selectionMode(self):
493
"""Get the selection mode."""
494
495
def setDragDropMode(self, mode):
496
"""Set drag and drop mode."""
497
498
def dragDropMode(self):
499
"""Get drag and drop mode."""
500
501
# Signals
502
itemClicked: pyTTkSignal # Emitted when item is clicked
503
textClicked: pyTTkSignal # Emitted when item text is clicked
504
searchModified: pyTTkSignal # Emitted when search text changes
505
currentItemChanged: pyTTkSignal # Emitted when current item changes
506
```
507
508
## Usage Examples
509
510
### Button with Click Handler
511
512
```python
513
import TermTk as ttk
514
515
root = ttk.TTk()
516
container = ttk.TTkContainer(parent=root)
517
518
# Create button
519
button = ttk.TTkButton(parent=container, text="Click Me!", pos=(5, 5), size=(15, 3))
520
521
# Connect click handler
522
@ttk.pyTTkSlot()
523
def on_button_click():
524
print("Button was clicked!")
525
button.setText("Clicked!")
526
527
button.clicked.connect(on_button_click)
528
529
root.mainloop()
530
```
531
532
### Form with Various Input Widgets
533
534
```python
535
import TermTk as ttk
536
537
root = ttk.TTk()
538
container = ttk.TTkContainer(parent=root)
539
layout = ttk.TTkVBoxLayout()
540
541
# Name input
542
name_layout = ttk.TTkHBoxLayout()
543
name_label = ttk.TTkLabel(text="Name:")
544
name_edit = ttk.TTkLineEdit(placeholderText="Enter your name")
545
name_layout.addWidget(name_label)
546
name_layout.addWidget(name_edit, stretch=1)
547
548
# Age input
549
age_layout = ttk.TTkHBoxLayout()
550
age_label = ttk.TTkLabel(text="Age:")
551
age_spin = ttk.TTkSpinBox(minimum=0, maximum=120, value=25)
552
age_layout.addWidget(age_label)
553
age_layout.addWidget(age_spin)
554
age_layout.addStretch(1)
555
556
# Options
557
newsletter_cb = ttk.TTkCheckbox(text="Subscribe to newsletter")
558
gender_layout = ttk.TTkHBoxLayout()
559
male_rb = ttk.TTkRadioButton(text="Male")
560
female_rb = ttk.TTkRadioButton(text="Female")
561
gender_layout.addWidget(male_rb)
562
gender_layout.addWidget(female_rb)
563
gender_layout.addStretch(1)
564
565
# Country selection
566
country_layout = ttk.TTkHBoxLayout()
567
country_label = ttk.TTkLabel(text="Country:")
568
country_combo = ttk.TTkComboBox()
569
country_combo.addItems(["USA", "Canada", "UK", "Australia"])
570
country_layout.addWidget(country_label)
571
country_layout.addWidget(country_combo, stretch=1)
572
573
# Submit button
574
submit_btn = ttk.TTkButton(text="Submit")
575
576
# Add all to main layout
577
layout.addLayout(name_layout)
578
layout.addLayout(age_layout)
579
layout.addWidget(newsletter_cb)
580
layout.addLayout(gender_layout)
581
layout.addLayout(country_layout)
582
layout.addStretch(1)
583
layout.addWidget(submit_btn)
584
585
container.setLayout(layout)
586
587
# Form submission handler
588
@ttk.pyTTkSlot()
589
def submit_form():
590
print(f"Name: {name_edit.text()}")
591
print(f"Age: {age_spin.value()}")
592
print(f"Newsletter: {newsletter_cb.isChecked()}")
593
print(f"Country: {country_combo.currentText()}")
594
595
submit_btn.clicked.connect(submit_form)
596
597
root.mainloop()
598
```
599
600
### Slider Control Example
601
602
```python
603
import TermTk as ttk
604
605
root = ttk.TTk()
606
container = ttk.TTkContainer(parent=root)
607
layout = ttk.TTkVBoxLayout()
608
609
# Volume control
610
volume_label = ttk.TTkLabel(text="Volume: 50")
611
volume_slider = ttk.TTkSlider(orientation=ttk.TTkConstant.Horizontal,
612
minimum=0, maximum=100, value=50)
613
614
# Update label when slider moves
615
@ttk.pyTTkSlot(int)
616
def update_volume(value):
617
volume_label.setText(f"Volume: {value}")
618
619
volume_slider.valueChanged.connect(update_volume)
620
621
layout.addWidget(volume_label)
622
layout.addWidget(volume_slider)
623
624
container.setLayout(layout)
625
root.mainloop()
626
```
627
628
### List Widget Selection Example
629
630
```python
631
import TermTk as ttk
632
633
root = ttk.TTk()
634
container = ttk.TTkContainer(parent=root)
635
layout = ttk.TTkVBoxLayout()
636
637
# Create list widget
638
list_widget = ttk.TTkListWidget()
639
list_widget.addItems([
640
"Python", "JavaScript", "Java", "C++", "C#",
641
"Go", "Rust", "Swift", "Kotlin", "TypeScript"
642
])
643
644
# Status label
645
status_label = ttk.TTkLabel(text="Select a programming language")
646
647
# Handle selection changes
648
@ttk.pyTTkSlot()
649
def on_selection_changed():
650
current = list_widget.currentItem()
651
if current:
652
status_label.setText(f"Selected: {current}")
653
else:
654
status_label.setText("No selection")
655
656
list_widget.currentItemChanged.connect(on_selection_changed)
657
658
# Handle item clicks
659
@ttk.pyTTkSlot()
660
def on_item_clicked():
661
current = list_widget.currentItem()
662
print(f"Clicked: {current}")
663
664
list_widget.itemClicked.connect(on_item_clicked)
665
666
layout.addWidget(list_widget)
667
layout.addWidget(status_label)
668
669
container.setLayout(layout)
670
root.mainloop()
671
```