0
# Display Widgets
1

2
Widgets for displaying information including labels, images, progress bars, and other visual components.
3

4
## Capabilities
5

6
### Label Widget
7

8
TTkLabel displays text with support for formatting, alignment, and color styling.
9

10
```python { .api }
11
class TTkLabel(TTkWidget):
12
    def __init__(self, parent=None, text="", **kwargs):
13
        """
14
        Initialize a label widget.
15
        
16
        Parameters:
17
        - text (str): Text content to display
18
        - color (TTkColor): Text color
19
        - alignment (int): Text alignment constant
20
        - wordWrap (bool): Enable word wrapping
21
        """
22
    
23
    def setText(self, text):
24
        """Set the label text."""
25
    
26
    def text(self):
27
        """Get the label text."""
28
    
29
    def setAlignment(self, alignment):
30
        """Set text alignment."""
31
    
32
    def alignment(self):
33
        """Get text alignment."""
34
    
35
    def setWordWrap(self, wrap):
36
        """Enable/disable word wrapping."""
37
    
38
    def wordWrap(self):
39
        """Check if word wrapping is enabled."""
40
    
41
    def setColor(self, color):
42
        """Set text color."""
43
    
44
    def color(self):
45
        """Get text color."""
46
    
47
    def setPixmap(self, pixmap):
48
        """Set a pixmap/image to display."""
49
    
50
    def pixmap(self):
51
        """Get the current pixmap."""
52
    
53
    def clear(self):
54
        """Clear the label content."""
55
```
56

57
### Image Widget
58

59
TTkImage displays images and graphics in the terminal using text characters and colors.
60

61
```python { .api }
62
class TTkImage(TTkWidget):
63
    def __init__(self, parent=None, **kwargs):
64
        """
65
        Initialize an image widget.
66
        
67
        Parameters:
68
        - image: Image data to display
69
        - scaledContents (bool): Scale image to fit widget
70
        - alignment (int): Image alignment
71
        """
72
    
73
    def setImage(self, image):
74
        """Set the image to display."""
75
    
76
    def image(self):
77
        """Get the current image."""
78
    
79
    def setPixmap(self, pixmap):
80
        """Set a pixmap to display."""
81
    
82
    def pixmap(self):
83
        """Get the current pixmap."""
84
    
85
    def setScaledContents(self, scaled):
86
        """Enable/disable content scaling."""
87
    
88
    def hasScaledContents(self):
89
        """Check if content scaling is enabled."""
90
    
91
    def setAlignment(self, alignment):
92
        """Set image alignment."""
93
    
94
    def alignment(self):
95
        """Get image alignment."""
96
    
97
    def clear(self):
98
        """Clear the image."""
99
    
100
    def loadFromFile(self, filename):
101
        """Load image from file."""
102
```
103

104
### Graph Widget
105

106
TTkGraph provides plotting capabilities for data visualization in terminal.
107

108
```python { .api }
109
class TTkGraph(TTkWidget):
110
    def __init__(self, parent=None, **kwargs):
111
        """
112
        Initialize a graph widget.
113
        
114
        Parameters:
115
        - title (str): Graph title
116
        - xLabel (str): X-axis label
117
        - yLabel (str): Y-axis label
118
        """
119
    
120
    def addData(self, data, label=None, color=None):
121
        """
122
        Add data series to the graph.
123
        
124
        Parameters:
125
        - data: List of (x, y) tuples or y values
126
        - label (str): Data series label
127
        - color (TTkColor): Line/point color
128
        """
129
    
130
    def clearData(self):
131
        """Clear all data series."""
132
    
133
    def setTitle(self, title):
134
        """Set graph title."""
135
    
136
    def title(self):
137
        """Get graph title."""
138
    
139
    def setXLabel(self, label):
140
        """Set X-axis label."""
141
    
142
    def xLabel(self):
143
        """Get X-axis label."""
144
    
145
    def setYLabel(self, label):
146
        """Set Y-axis label."""
147
    
148
    def yLabel(self):
149
        """Get Y-axis label."""
150
    
151
    def setXRange(self, min_val, max_val):
152
        """Set X-axis range."""
153
    
154
    def setYRange(self, min_val, max_val):
155
        """Set Y-axis range."""
156
    
157
    def setAutoRange(self, enabled):
158
        """Enable/disable automatic range adjustment."""
159
    
160
    def setGridEnabled(self, enabled):
161
        """Enable/disable grid display."""
162
    
163
    def setLegendEnabled(self, enabled):
164
        """Enable/disable legend display."""
165
    
166
    def refresh(self):
167
        """Refresh the graph display."""
168
```
169

170
### Progress Bar Widget
171

172
TTkFancyProgressBar displays progress indication with customizable styling.
173

174
```python { .api }
175
class TTkFancyProgressBar(TTkWidget):
176
    def __init__(self, parent=None, **kwargs):
177
        """
178
        Initialize a progress bar widget.
179
        
180
        Parameters:
181
        - value (float): Initial value (default: 0.0)
182
        - lookAndFeel (TTkLookAndFeelFPBar): Custom styling (optional)
183
        """
184
    
185
    def setValue(self, value):
186
        """Set the current progress value."""
187
    
188
    def value(self):
189
        """Get the current progress value."""
190
    
191
    def setMinimum(self, minimum):
192
        """Set the minimum value."""
193
    
194
    def minimum(self):
195
        """Get the minimum value."""
196
    
197
    def setMaximum(self, maximum):
198
        """Set the maximum value."""
199
    
200
    def maximum(self):
201
        """Get the maximum value."""
202
    
203
    def setRange(self, minimum, maximum):
204
        """Set the value range."""
205
    
206
    def reset(self):
207
        """Reset progress to minimum value."""
208
    
209
    def setOrientation(self, orientation):
210
        """Set progress bar orientation."""
211
    
212
    def orientation(self):
213
        """Get progress bar orientation."""
214
    
215
    def setTextVisible(self, visible):
216
        """Show/hide progress text."""
217
    
218
    def isTextVisible(self):
219
        """Check if progress text is visible."""
220
    
221
    def setFormat(self, format_str):
222
        """Set progress text format string."""
223
    
224
    def format(self):
225
        """Get progress text format string."""
226
    
227
    def setInvertedAppearance(self, inverted):
228
        """Invert the progress bar appearance."""
229
    
230
    def invertedAppearance(self):
231
        """Check if appearance is inverted."""
232
    
233
    # Signals
234
    valueChanged: pyTTkSignal  # Emitted when value changes
235
```
236

237
### About Dialog Widget
238

239
TTkAbout displays application information in a dialog format.
240

241
```python { .api }
242
class TTkAbout(TTkWidget):
243
    def __init__(self, parent=None, **kwargs):
244
        """
245
        Initialize an about dialog widget.
246
        
247
        Parameters:
248
        - title (str): Dialog title
249
        - text (str): About text content
250
        - logo: Logo image to display
251
        """
252
    
253
    def setTitle(self, title):
254
        """Set the dialog title."""
255
    
256
    def title(self):
257
        """Get the dialog title."""
258
    
259
    def setText(self, text):
260
        """Set the about text content."""
261
    
262
    def text(self):
263
        """Get the about text content."""
264
    
265
    def setLogo(self, logo):
266
        """Set the logo image."""
267
    
268
    def logo(self):
269
        """Get the logo image."""
270
    
271
    def setVersion(self, version):
272
        """Set the application version."""
273
    
274
    def version(self):
275
        """Get the application version."""
276
    
277
    def setCopyright(self, copyright_text):
278
        """Set the copyright text."""
279
    
280
    def copyright(self):
281
        """Get the copyright text."""
282
    
283
    def addAuthor(self, name, email=None, role=None):
284
        """Add an author to the about information."""
285
    
286
    def addCredit(self, name, task):
287
        """Add a credit entry."""
288
    
289
    def addLicense(self, name, text):
290
        """Add license information."""
291
```
292

293
## Usage Examples
294

295
### Basic Label Display
296

297
```python
298
import TermTk as ttk
299

300
root = ttk.TTk()
301
container = ttk.TTkContainer(parent=root)
302
layout = ttk.TTkVBoxLayout()
303

304
# Simple text label
305
title = ttk.TTkLabel(text="Application Title")
306
title.setAlignment(ttk.TTkConstant.AlignCenter)
307

308
# Colored label
309
status = ttk.TTkLabel(text="Status: Ready")
310
green_color = ttk.TTkColor(fg="#00FF00")
311
status.setColor(green_color)
312

313
# Multi-line label with word wrap
314
description = ttk.TTkLabel(text="This is a long description that will wrap to multiple lines when the widget is not wide enough to display it all on one line.")
315
description.setWordWrap(True)
316

317
layout.addWidget(title)
318
layout.addWidget(status)
319
layout.addWidget(description)
320

321
container.setLayout(layout)
322
root.mainloop()
323
```
324

325
### Progress Bar Example
326

327
```python
328
import TermTk as ttk
329
import time
330

331
root = ttk.TTk()
332
container = ttk.TTkContainer(parent=root)
333
layout = ttk.TTkVBoxLayout()
334

335
# Create progress bar
336
progress = ttk.TTkFancyProgressBar(minimum=0, maximum=100, value=0)
337
progress.setTextVisible(True)
338
progress.setFormat("Progress: %p%")
339

340
# Label to show current value
341
label = ttk.TTkLabel(text="Starting...")
342

343
layout.addWidget(label)
344
layout.addWidget(progress)
345

346
container.setLayout(layout)
347

348
# Simulate progress updates
349
def update_progress():
350
    for i in range(101):
351
        progress.setValue(i)
352
        label.setText(f"Processing item {i}/100")
353
        root.update()  # Force UI update
354
        time.sleep(0.1)  # Simulate work
355
    label.setText("Complete!")
356

357
# Start progress in a timer (in real app, use threading)
358
timer = ttk.TTkTimer()
359
timer.timeout.connect(update_progress)
360
timer.start(100)  # Start after 100ms
361

362
root.mainloop()
363
```
364

365
### Graph Plotting Example
366

367
```python
368
import TermTk as ttk
369
import math
370

371
root = ttk.TTk()
372
container = ttk.TTkContainer(parent=root)
373

374
# Create graph widget
375
graph = ttk.TTkGraph(parent=container, 
376
                    title="Sine and Cosine Waves",
377
                    xLabel="X Values", 
378
                    yLabel="Y Values")
379

380
# Generate data
381
x_data = [i * 0.1 for i in range(100)]
382
sin_data = [(x, math.sin(x)) for x in x_data]
383
cos_data = [(x, math.cos(x)) for x in x_data]
384

385
# Add data series
386
red_color = ttk.TTkColor(fg="#FF0000")
387
blue_color = ttk.TTkColor(fg="#0000FF")
388

389
graph.addData(sin_data, label="sin(x)", color=red_color)
390
graph.addData(cos_data, label="cos(x)", color=blue_color)
391

392
# Configure graph
393
graph.setGridEnabled(True)
394
graph.setLegendEnabled(True)
395
graph.setAutoRange(True)
396

397
root.mainloop()
398
```
399

400
### Image Display Example
401

402
```python
403
import TermTk as ttk
404

405
root = ttk.TTk()
406
container = ttk.TTkContainer(parent=root)
407
layout = ttk.TTkVBoxLayout()
408

409
# Create image widget
410
image = ttk.TTkImage()
411
image.loadFromFile("logo.png")  # Load from file
412
image.setScaledContents(True)  # Scale to fit widget
413
image.setAlignment(ttk.TTkConstant.AlignCenter)
414

415
# Image caption
416
caption = ttk.TTkLabel(text="Company Logo")
417
caption.setAlignment(ttk.TTkConstant.AlignCenter)
418

419
layout.addWidget(image)
420
layout.addWidget(caption)
421

422
container.setLayout(layout)
423
root.mainloop()
424
```
425

426
### About Dialog Example
427

428
```python
429
import TermTk as ttk
430

431
root = ttk.TTk()
432

433
# Create about dialog
434
about = ttk.TTkAbout(parent=root,
435
                    title="About My App",
436
                    text="My Application v1.0\n\nA terminal-based application built with pyTermTk.")
437

438
about.setVersion("1.0.0")
439
about.setCopyright("Copyright (c) 2024 My Company")
440
about.addAuthor("John Doe", "john@example.com", "Lead Developer")
441
about.addAuthor("Jane Smith", "jane@example.com", "UI Designer")
442
about.addCredit("Bob Johnson", "Testing and Quality Assurance")
443
about.addLicense("MIT", "Permission is hereby granted, free of charge...")
444

445
about.show()
446

447
root.mainloop()
448
```
449

450
### Scroll Bar Widget
451

452
TTkScrollBar provides scrolling controls for navigating content that exceeds the visible area.
453

454
```python { .api }
455
class TTkScrollBar(TTkWidget):
456
    def __init__(self, parent=None, **kwargs):
457
        """
458
        Initialize a scroll bar widget.
459
        
460
        Parameters:
461
        - value (int): Initial value (default: 0)
462
        - minimum (int): Minimum value (default: 0)
463
        - maximum (int): Maximum value (default: 99)
464
        - singleStep (int): Single step size (default: 1)
465
        - pageStep (int): Page step size (default: 10)
466
        - orientation (TTkK.Direction): Orientation (default: TTkK.VERTICAL)
467
        """
468
    
469
    def setValue(self, value):
470
        """Set the current value."""
471
    
472
    def value(self):
473
        """Get the current value."""
474
    
475
    def setMinimum(self, minimum):
476
        """Set the minimum value."""
477
    
478
    def minimum(self):
479
        """Get the minimum value."""
480
    
481
    def setMaximum(self, maximum):
482
        """Set the maximum value."""
483
    
484
    def maximum(self):
485
        """Get the maximum value."""
486
    
487
    def setRange(self, minimum, maximum):
488
        """Set the value range."""
489
    
490
    def setSingleStep(self, step):
491
        """Set single step size."""
492
    
493
    def singleStep(self):
494
        """Get single step size."""
495
    
496
    def setPageStep(self, step):
497
        """Set page step size."""
498
    
499
    def pageStep(self):
500
        """Get page step size."""
501
    
502
    def setOrientation(self, orientation):
503
        """Set scroll bar orientation."""
504
    
505
    def orientation(self):
506
        """Get scroll bar orientation."""
507
    
508
    def setInvertedControls(self, inverted):
509
        """Invert scroll direction."""
510
    
511
    def invertedControls(self):
512
        """Check if controls are inverted."""
513
    
514
    # Signals
515
    valueChanged: pyTTkSignal    # Emitted when value changes
516
    rangeChanged: pyTTkSignal    # Emitted when range changes
517
    sliderMoved: pyTTkSignal     # Emitted when slider is moved
518
```