0
# Display Widgets
1

2
Display widgets are used to show information to users, including text, images, graphics, and visual data representations. These widgets form the output components of GUI applications.
3

4
## Capabilities
5

6
### Text Widget
7

8
The Text widget displays static text with customizable styling and formatting options.
9

10
```python { .api }
11
class Text:
12
    def __init__(self, master, text="", size=None, color=None, bg=None, 
13
                 font=None, grid=None, align=None, visible=True, 
14
                 enabled=None, width=None, height=None):
15
        """
16
        Create a text display widget.
17
        
18
        Args:
19
            master: Parent widget (App, Window, or container)
20
            text (str): Text content to display
21
            size (int): Font size in points
22
            color (str): Text color
23
            bg (str): Background color
24
            font (str): Font family name
25
            grid (list): Grid position [x, y] for grid layout
26
            align (str): Alignment ("left", "right", "top", "bottom")
27
            visible (bool): Initial visibility state
28
            enabled (bool): Initial enabled state
29
            width (int): Widget width in pixels
30
            height (int): Widget height in pixels
31
        """
32
        
33
    @property
34
    def value(self) -> str:
35
        """Get/set the text content."""
36
        
37
    @value.setter
38
    def value(self, text: str): ...
39
        
40
    @property
41
    def size(self) -> int:
42
        """Get/set the font size."""
43
        
44
    @size.setter
45
    def size(self, size: int): ...
46
        
47
    @property
48
    def color(self) -> str:
49
        """Get/set the text color."""
50
        
51
    @color.setter
52
    def color(self, color: str): ...
53
        
54
    @property
55
    def font(self) -> str:
56
        """Get/set the font family."""
57
        
58
    @font.setter
59
    def font(self, font: str): ...
60
        
61
    @property
62
    def text_bold(self) -> bool:
63
        """Get/set bold text style."""
64
        
65
    @text_bold.setter
66
    def text_bold(self, value: bool): ...
67
        
68
    @property
69
    def text_italic(self) -> bool:
70
        """Get/set italic text style."""
71
        
72
    @text_italic.setter
73
    def text_italic(self, value: bool): ...
74
```
75

76
### Picture Widget
77

78
The Picture widget displays images from files, supporting various image formats including GIF, PNG, and JPG (with PIL).
79

80
```python { .api }
81
class Picture:
82
    def __init__(self, master, image=None, grid=None, align=None, 
83
                 visible=True, enabled=None, width=None, height=None):
84
        """
85
        Create an image display widget.
86
        
87
        Args:
88
            master: Parent widget (App, Window, or container)
89
            image (str): Path to image file
90
            grid (list): Grid position [x, y] for grid layout
91
            align (str): Alignment ("left", "right", "top", "bottom")
92
            visible (bool): Initial visibility state
93
            enabled (bool): Initial enabled state
94
            width (int): Display width in pixels (scales image)
95
            height (int): Display height in pixels (scales image)
96
        """
97
        
98
    @property
99
    def image(self) -> str:
100
        """Get/set the image file path."""
101
        
102
    @image.setter
103
    def image(self, image_path: str): ...
104
        
105
    @property
106
    def value(self) -> str:
107
        """Get/set the image file path (alias for image)."""
108
        
109
    @value.setter
110
    def value(self, image_path: str): ...
111
        
112
    # Event handlers
113
    @property
114
    def when_clicked(self):
115
        """Callback when image is clicked."""
116
        
117
    @when_clicked.setter
118
    def when_clicked(self, callback): ...
119
        
120
    @property
121
    def when_left_button_pressed(self):
122
        """Callback when left mouse button is pressed on image."""
123
        
124
    @when_left_button_pressed.setter
125
    def when_left_button_pressed(self, callback): ...
126
        
127
    @property
128
    def when_left_button_released(self):
129
        """Callback when left mouse button is released on image."""
130
        
131
    @when_left_button_released.setter
132
    def when_left_button_released(self, callback): ...
133
```
134

135
### Drawing Canvas
136

137
The Drawing widget provides a canvas for creating graphics, drawings, and visual representations programmatically.
138

139
```python { .api }
140
class Drawing:
141
    def __init__(self, master, width=400, height=400, grid=None, align=None, 
142
                 visible=True, enabled=None):
143
        """
144
        Create a drawing canvas widget.
145
        
146
        Args:
147
            master: Parent widget (App, Window, or container)
148
            width (int): Canvas width in pixels
149
            height (int): Canvas height in pixels
150
            grid (list): Grid position [x, y] for grid layout
151
            align (str): Alignment ("left", "right", "top", "bottom")
152
            visible (bool): Initial visibility state
153
            enabled (bool): Initial enabled state
154
        """
155
        
156
    def line(self, x1, y1, x2, y2, color="black", width=1):
157
        """
158
        Draw a line on the canvas.
159
        
160
        Args:
161
            x1, y1 (int): Starting coordinates
162
            x2, y2 (int): Ending coordinates
163
            color (str): Line color
164
            width (int): Line width in pixels
165
            
166
        Returns:
167
            Shape ID for later reference
168
        """
169
        
170
    def rectangle(self, x1, y1, x2, y2, color="black", outline=False, 
171
                  outline_color="black"):
172
        """
173
        Draw a rectangle on the canvas.
174
        
175
        Args:
176
            x1, y1 (int): Top-left coordinates
177
            x2, y2 (int): Bottom-right coordinates
178
            color (str): Fill color
179
            outline (bool): Draw outline
180
            outline_color (str): Outline color
181
            
182
        Returns:
183
            Shape ID for later reference
184
        """
185
        
186
    def oval(self, x1, y1, x2, y2, color="black", outline=False, 
187
             outline_color="black"):
188
        """
189
        Draw an oval/circle on the canvas.
190
        
191
        Args:
192
            x1, y1 (int): Top-left coordinates of bounding box
193
            x2, y2 (int): Bottom-right coordinates of bounding box
194
            color (str): Fill color
195
            outline (bool): Draw outline
196
            outline_color (str): Outline color
197
            
198
        Returns:
199
            Shape ID for later reference
200
        """
201
        
202
    def triangle(self, x1, y1, x2, y2, x3, y3, color="black", outline=False, 
203
                 outline_color="black"):
204
        """
205
        Draw a triangle on the canvas.
206
        
207
        Args:
208
            x1, y1 (int): First point coordinates
209
            x2, y2 (int): Second point coordinates
210
            x3, y3 (int): Third point coordinates
211
            color (str): Fill color
212
            outline (bool): Draw outline
213
            outline_color (str): Outline color
214
            
215
        Returns:
216
            Shape ID for later reference
217
        """
218
        
219
    def polygon(self, points, color="black", outline=False, 
220
                outline_color="black"):
221
        """
222
        Draw a polygon on the canvas.
223
        
224
        Args:
225
            points (list): List of (x, y) coordinate tuples
226
            color (str): Fill color
227
            outline (bool): Draw outline
228
            outline_color (str): Outline color
229
            
230
        Returns:
231
            Shape ID for later reference
232
        """
233
        
234
    def text(self, x, y, text, color="black", font=None, size=None):
235
        """
236
        Draw text on the canvas.
237
        
238
        Args:
239
            x, y (int): Text position coordinates
240
            text (str): Text to display
241
            color (str): Text color
242
            font (str): Font family
243
            size (int): Font size
244
            
245
        Returns:
246
            Shape ID for later reference
247
        """
248
        
249
    def image(self, x, y, image, width=None, height=None):
250
        """
251
        Draw an image on the canvas.
252
        
253
        Args:
254
            x, y (int): Image position coordinates
255
            image (str): Path to image file
256
            width (int): Display width (scales image)
257
            height (int): Display height (scales image)
258
            
259
        Returns:
260
            Shape ID for later reference
261
        """
262
        
263
    def clear(self):
264
        """Clear all drawings from the canvas."""
265
        
266
    def delete(self, shape_id):
267
        """
268
        Delete a specific shape from the canvas.
269
        
270
        Args:
271
            shape_id: ID returned from drawing methods
272
        """
273
        
274
    @property
275
    def width(self) -> int:
276
        """Get/set the canvas width."""
277
        
278
    @width.setter
279
    def width(self, width: int): ...
280
        
281
    @property
282
    def height(self) -> int:
283
        """Get/set the canvas height."""
284
        
285
    @height.setter
286
    def height(self, height: int): ...
287
        
288
    # Event handlers
289
    @property
290
    def when_clicked(self):
291
        """Callback when canvas is clicked."""
292
        
293
    @when_clicked.setter
294
    def when_clicked(self, callback): ...
295
        
296
    @property
297
    def when_mouse_dragged(self):
298
        """Callback when mouse is dragged on canvas."""
299
        
300
    @when_mouse_dragged.setter
301
    def when_mouse_dragged(self, callback): ...
302
```
303

304
### Waffle Grid
305

306
The Waffle widget creates a grid of clickable squares, useful for pixel art, game boards, or visual data representation.
307

308
```python { .api }
309
class Waffle:
310
    def __init__(self, master, height=3, width=3, dim=20, pad=5, 
311
                 color="white", dotty=False, grid=None, align=None, 
312
                 visible=True, enabled=None, remember=True, command=None):
313
        """
314
        Create a grid of clickable squares.
315
        
316
        Args:
317
            master: Parent widget (App, Window, or container)
318
            height (int): Number of rows
319
            width (int): Number of columns
320
            dim (int): Size of each square in pixels
321
            pad (int): Padding between squares in pixels
322
            color (str): Default color for squares
323
            dotty (bool): Draw squares as circles instead
324
            grid (list): Grid position [x, y] for grid layout
325
            align (str): Alignment ("left", "right", "top", "bottom")
326
            visible (bool): Initial visibility state
327
            enabled (bool): Initial enabled state
328
            remember (bool): Remember previous colors when clicked
329
            command (function): Callback when square is clicked
330
        """
331
        
332
    def set_pixel(self, x, y, color):
333
        """
334
        Set the color of a specific square.
335
        
336
        Args:
337
            x (int): Column position (0-based)
338
            y (int): Row position (0-based)
339
            color (str): Color to set
340
        """
341
        
342
    def get_pixel(self, x, y):
343
        """
344
        Get the color of a specific square.
345
        
346
        Args:
347
            x (int): Column position (0-based)
348
            y (int): Row position (0-based)
349
            
350
        Returns:
351
            str: Current color of the square
352
        """
353
        
354
    def clear(self):
355
        """Reset all squares to the default color."""
356
        
357
    @property  
358
    def height(self) -> int:
359
        """Get/set the number of rows."""
360
        
361
    @height.setter
362
    def height(self, rows: int): ...
363
        
364
    @property
365
    def width(self) -> int:
366
        """Get/set the number of columns."""
367
        
368
    @width.setter
369
    def width(self, cols: int): ...
370
        
371
    @property
372
    def color(self) -> str:
373
        """Get/set the default color."""
374
        
375
    @color.setter
376
    def color(self, color: str): ...
377
        
378
    # Event handler
379
    @property
380
    def when_clicked(self):
381
        """Callback when a square is clicked."""
382
        
383
    @when_clicked.setter
384
    def when_clicked(self, callback): ...
385
```
386

387
## Display Widget Usage Examples
388

389
### Dynamic Text Updates
390

391
```python
392
from guizero import App, Text, PushButton
393
import time
394

395
app = App()
396

397
# Create text widget with initial message
398
status_text = Text(app, text="Ready", size=14, color="blue")
399

400
counter = 0
401

402
def update_counter():
403
    global counter
404
    counter += 1
405
    status_text.value = f"Count: {counter}"
406
    status_text.color = "green" if counter % 2 == 0 else "red"
407

408
PushButton(app, text="Update", command=update_counter)
409

410
app.display()
411
```
412

413
### Image Gallery
414

415
```python
416
from guizero import App, Picture, PushButton, Box
417
import os
418

419
app = App(title="Image Gallery")
420

421
# Container for image and controls
422
main_box = Box(app)
423

424
# Picture widget
425
picture = Picture(main_box, width=300, height=200)
426

427
# Controls
428
controls_box = Box(main_box)
429

430
image_files = ["image1.jpg", "image2.png", "image3.gif"]
431
current_image = 0
432

433
def show_next():
434
    global current_image
435
    current_image = (current_image + 1) % len(image_files)
436
    if os.path.exists(image_files[current_image]):
437
        picture.image = image_files[current_image]
438

439
def show_previous():
440
    global current_image
441
    current_image = (current_image - 1) % len(image_files) 
442
    if os.path.exists(image_files[current_image]):
443
        picture.image = image_files[current_image]
444

445
PushButton(controls_box, text="Previous", command=show_previous)
446
PushButton(controls_box, text="Next", command=show_next)
447

448
app.display()
449
```
450

451
### Interactive Drawing
452

453
```python
454
from guizero import App, Drawing, PushButton, Box
455

456
app = App(title="Simple Drawing")
457

458
# Drawing canvas
459
canvas = Drawing(app, width=400, height=300)
460
canvas.bg = "white"
461

462
# Drawing state
463
current_color = "black"
464
shapes = []
465

466
def draw_circle():
467
    shape_id = canvas.oval(50, 50, 100, 100, color=current_color)
468
    shapes.append(shape_id)
469

470
def draw_rectangle():
471
    shape_id = canvas.rectangle(150, 50, 200, 100, color=current_color)
472
    shapes.append(shape_id)
473

474
def change_color():
475
    global current_color
476
    current_color = "red" if current_color == "black" else "black"
477

478
def clear_canvas():
479
    canvas.clear()
480
    shapes.clear()
481

482
# Controls  
483
controls = Box(app)
484
PushButton(controls, text="Circle", command=draw_circle)
485
PushButton(controls, text="Rectangle", command=draw_rectangle)
486
PushButton(controls, text="Change Color", command=change_color)
487
PushButton(controls, text="Clear", command=clear_canvas)
488

489
app.display()
490
```
491

492
### Pixel Art with Waffle
493

494
```python
495
from guizero import App, Waffle, PushButton, Text
496

497
app = App(title="Pixel Art")
498

499
# Create 8x8 waffle grid
500
waffle = Waffle(app, height=8, width=8, dim=30, pad=2)
501

502
current_color = "black"
503
status_text = Text(app, text=f"Current color: {current_color}")
504

505
def pixel_clicked(x, y):
506
    waffle.set_pixel(x, y, current_color)
507

508
def change_color():
509
    global current_color
510
    colors = ["black", "red", "green", "blue", "yellow", "purple", "orange"]
511
    current_index = colors.index(current_color)
512
    current_color = colors[(current_index + 1) % len(colors)]
513
    status_text.value = f"Current color: {current_color}"
514

515
def clear_waffle():
516
    waffle.clear()
517

518
waffle.when_clicked = pixel_clicked
519

520
PushButton(app, text="Change Color", command=change_color)
521
PushButton(app, text="Clear", command=clear_waffle)
522

523
app.display()
524
```
525

526
## Supported Image Formats
527

528
The Picture widget supports different image formats depending on available libraries:
529

530
- **Always supported**: GIF, PNG (via Tkinter)
531
- **With PIL/Pillow**: JPG, BMP, ICO, TIF, animated GIF
532
- **Platform notes**: macOS may have limited GIF support without PIL
533

534
## Canvas Coordinate System
535

536
The Drawing widget uses a standard computer graphics coordinate system:
537
- Origin (0, 0) is at the top-left corner
538
- X increases to the right
539
- Y increases downward
540
- All coordinates are in pixels
541

542
## Color Specifications
543

544
All display widgets support multiple color formats:
545
- **Named colors**: "red", "blue", "green", "white", "black", "yellow", etc.
546
- **Hex colors**: "#FF0000", "#00FF00", "#0000FF", etc.
547
- **RGB tuples**: (255, 0, 0), (0, 255, 0), (0, 0, 255), etc.