tessl/pypi-guizero
Python module to allow learners to easily create GUIs
—
Pending
display-widgets.mddocs/
Display Widgets
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.
Capabilities
Text Widget
The Text widget displays static text with customizable styling and formatting options.
class Text:
def __init__(self, master, text="", size=None, color=None, bg=None,
font=None, grid=None, align=None, visible=True,
enabled=None, width=None, height=None):
"""
Create a text display widget.
Args:
master: Parent widget (App, Window, or container)
text (str): Text content to display
size (int): Font size in points
color (str): Text color
bg (str): Background color
font (str): Font family name
grid (list): Grid position [x, y] for grid layout
align (str): Alignment ("left", "right", "top", "bottom")
visible (bool): Initial visibility state
enabled (bool): Initial enabled state
width (int): Widget width in pixels
height (int): Widget height in pixels
"""
@property
def value(self) -> str:
"""Get/set the text content."""
@value.setter
def value(self, text: str): ...
@property
def size(self) -> int:
"""Get/set the font size."""
@size.setter
def size(self, size: int): ...
@property
def color(self) -> str:
"""Get/set the text color."""
@color.setter
def color(self, color: str): ...
@property
def font(self) -> str:
"""Get/set the font family."""
@font.setter
def font(self, font: str): ...
@property
def text_bold(self) -> bool:
"""Get/set bold text style."""
@text_bold.setter
def text_bold(self, value: bool): ...
@property
def text_italic(self) -> bool:
"""Get/set italic text style."""
@text_italic.setter
def text_italic(self, value: bool): ...Picture Widget
The Picture widget displays images from files, supporting various image formats including GIF, PNG, and JPG (with PIL).
class Picture:
def __init__(self, master, image=None, grid=None, align=None,
visible=True, enabled=None, width=None, height=None):
"""
Create an image display widget.
Args:
master: Parent widget (App, Window, or container)
image (str): Path to image file
grid (list): Grid position [x, y] for grid layout
align (str): Alignment ("left", "right", "top", "bottom")
visible (bool): Initial visibility state
enabled (bool): Initial enabled state
width (int): Display width in pixels (scales image)
height (int): Display height in pixels (scales image)
"""
@property
def image(self) -> str:
"""Get/set the image file path."""
@image.setter
def image(self, image_path: str): ...
@property
def value(self) -> str:
"""Get/set the image file path (alias for image)."""
@value.setter
def value(self, image_path: str): ...
# Event handlers
@property
def when_clicked(self):
"""Callback when image is clicked."""
@when_clicked.setter
def when_clicked(self, callback): ...
@property
def when_left_button_pressed(self):
"""Callback when left mouse button is pressed on image."""
@when_left_button_pressed.setter
def when_left_button_pressed(self, callback): ...
@property
def when_left_button_released(self):
"""Callback when left mouse button is released on image."""
@when_left_button_released.setter
def when_left_button_released(self, callback): ...Drawing Canvas
The Drawing widget provides a canvas for creating graphics, drawings, and visual representations programmatically.
class Drawing:
def __init__(self, master, width=400, height=400, grid=None, align=None,
visible=True, enabled=None):
"""
Create a drawing canvas widget.
Args:
master: Parent widget (App, Window, or container)
width (int): Canvas width in pixels
height (int): Canvas height in pixels
grid (list): Grid position [x, y] for grid layout
align (str): Alignment ("left", "right", "top", "bottom")
visible (bool): Initial visibility state
enabled (bool): Initial enabled state
"""
def line(self, x1, y1, x2, y2, color="black", width=1):
"""
Draw a line on the canvas.
Args:
x1, y1 (int): Starting coordinates
x2, y2 (int): Ending coordinates
color (str): Line color
width (int): Line width in pixels
Returns:
Shape ID for later reference
"""
def rectangle(self, x1, y1, x2, y2, color="black", outline=False,
outline_color="black"):
"""
Draw a rectangle on the canvas.
Args:
x1, y1 (int): Top-left coordinates
x2, y2 (int): Bottom-right coordinates
color (str): Fill color
outline (bool): Draw outline
outline_color (str): Outline color
Returns:
Shape ID for later reference
"""
def oval(self, x1, y1, x2, y2, color="black", outline=False,
outline_color="black"):
"""
Draw an oval/circle on the canvas.
Args:
x1, y1 (int): Top-left coordinates of bounding box
x2, y2 (int): Bottom-right coordinates of bounding box
color (str): Fill color
outline (bool): Draw outline
outline_color (str): Outline color
Returns:
Shape ID for later reference
"""
def triangle(self, x1, y1, x2, y2, x3, y3, color="black", outline=False,
outline_color="black"):
"""
Draw a triangle on the canvas.
Args:
x1, y1 (int): First point coordinates
x2, y2 (int): Second point coordinates
x3, y3 (int): Third point coordinates
color (str): Fill color
outline (bool): Draw outline
outline_color (str): Outline color
Returns:
Shape ID for later reference
"""
def polygon(self, points, color="black", outline=False,
outline_color="black"):
"""
Draw a polygon on the canvas.
Args:
points (list): List of (x, y) coordinate tuples
color (str): Fill color
outline (bool): Draw outline
outline_color (str): Outline color
Returns:
Shape ID for later reference
"""
def text(self, x, y, text, color="black", font=None, size=None):
"""
Draw text on the canvas.
Args:
x, y (int): Text position coordinates
text (str): Text to display
color (str): Text color
font (str): Font family
size (int): Font size
Returns:
Shape ID for later reference
"""
def image(self, x, y, image, width=None, height=None):
"""
Draw an image on the canvas.
Args:
x, y (int): Image position coordinates
image (str): Path to image file
width (int): Display width (scales image)
height (int): Display height (scales image)
Returns:
Shape ID for later reference
"""
def clear(self):
"""Clear all drawings from the canvas."""
def delete(self, shape_id):
"""
Delete a specific shape from the canvas.
Args:
shape_id: ID returned from drawing methods
"""
@property
def width(self) -> int:
"""Get/set the canvas width."""
@width.setter
def width(self, width: int): ...
@property
def height(self) -> int:
"""Get/set the canvas height."""
@height.setter
def height(self, height: int): ...
# Event handlers
@property
def when_clicked(self):
"""Callback when canvas is clicked."""
@when_clicked.setter
def when_clicked(self, callback): ...
@property
def when_mouse_dragged(self):
"""Callback when mouse is dragged on canvas."""
@when_mouse_dragged.setter
def when_mouse_dragged(self, callback): ...Waffle Grid
The Waffle widget creates a grid of clickable squares, useful for pixel art, game boards, or visual data representation.
class Waffle:
def __init__(self, master, height=3, width=3, dim=20, pad=5,
color="white", dotty=False, grid=None, align=None,
visible=True, enabled=None, remember=True, command=None):
"""
Create a grid of clickable squares.
Args:
master: Parent widget (App, Window, or container)
height (int): Number of rows
width (int): Number of columns
dim (int): Size of each square in pixels
pad (int): Padding between squares in pixels
color (str): Default color for squares
dotty (bool): Draw squares as circles instead
grid (list): Grid position [x, y] for grid layout
align (str): Alignment ("left", "right", "top", "bottom")
visible (bool): Initial visibility state
enabled (bool): Initial enabled state
remember (bool): Remember previous colors when clicked
command (function): Callback when square is clicked
"""
def set_pixel(self, x, y, color):
"""
Set the color of a specific square.
Args:
x (int): Column position (0-based)
y (int): Row position (0-based)
color (str): Color to set
"""
def get_pixel(self, x, y):
"""
Get the color of a specific square.
Args:
x (int): Column position (0-based)
y (int): Row position (0-based)
Returns:
str: Current color of the square
"""
def clear(self):
"""Reset all squares to the default color."""
@property
def height(self) -> int:
"""Get/set the number of rows."""
@height.setter
def height(self, rows: int): ...
@property
def width(self) -> int:
"""Get/set the number of columns."""
@width.setter
def width(self, cols: int): ...
@property
def color(self) -> str:
"""Get/set the default color."""
@color.setter
def color(self, color: str): ...
# Event handler
@property
def when_clicked(self):
"""Callback when a square is clicked."""
@when_clicked.setter
def when_clicked(self, callback): ...Display Widget Usage Examples
Dynamic Text Updates
from guizero import App, Text, PushButton
import time
app = App()
# Create text widget with initial message
status_text = Text(app, text="Ready", size=14, color="blue")
counter = 0
def update_counter():
global counter
counter += 1
status_text.value = f"Count: {counter}"
status_text.color = "green" if counter % 2 == 0 else "red"
PushButton(app, text="Update", command=update_counter)
app.display()Image Gallery
from guizero import App, Picture, PushButton, Box
import os
app = App(title="Image Gallery")
# Container for image and controls
main_box = Box(app)
# Picture widget
picture = Picture(main_box, width=300, height=200)
# Controls
controls_box = Box(main_box)
image_files = ["image1.jpg", "image2.png", "image3.gif"]
current_image = 0
def show_next():
global current_image
current_image = (current_image + 1) % len(image_files)
if os.path.exists(image_files[current_image]):
picture.image = image_files[current_image]
def show_previous():
global current_image
current_image = (current_image - 1) % len(image_files)
if os.path.exists(image_files[current_image]):
picture.image = image_files[current_image]
PushButton(controls_box, text="Previous", command=show_previous)
PushButton(controls_box, text="Next", command=show_next)
app.display()Interactive Drawing
from guizero import App, Drawing, PushButton, Box
app = App(title="Simple Drawing")
# Drawing canvas
canvas = Drawing(app, width=400, height=300)
canvas.bg = "white"
# Drawing state
current_color = "black"
shapes = []
def draw_circle():
shape_id = canvas.oval(50, 50, 100, 100, color=current_color)
shapes.append(shape_id)
def draw_rectangle():
shape_id = canvas.rectangle(150, 50, 200, 100, color=current_color)
shapes.append(shape_id)
def change_color():
global current_color
current_color = "red" if current_color == "black" else "black"
def clear_canvas():
canvas.clear()
shapes.clear()
# Controls
controls = Box(app)
PushButton(controls, text="Circle", command=draw_circle)
PushButton(controls, text="Rectangle", command=draw_rectangle)
PushButton(controls, text="Change Color", command=change_color)
PushButton(controls, text="Clear", command=clear_canvas)
app.display()Pixel Art with Waffle
from guizero import App, Waffle, PushButton, Text
app = App(title="Pixel Art")
# Create 8x8 waffle grid
waffle = Waffle(app, height=8, width=8, dim=30, pad=2)
current_color = "black"
status_text = Text(app, text=f"Current color: {current_color}")
def pixel_clicked(x, y):
waffle.set_pixel(x, y, current_color)
def change_color():
global current_color
colors = ["black", "red", "green", "blue", "yellow", "purple", "orange"]
current_index = colors.index(current_color)
current_color = colors[(current_index + 1) % len(colors)]
status_text.value = f"Current color: {current_color}"
def clear_waffle():
waffle.clear()
waffle.when_clicked = pixel_clicked
PushButton(app, text="Change Color", command=change_color)
PushButton(app, text="Clear", command=clear_waffle)
app.display()Supported Image Formats
The Picture widget supports different image formats depending on available libraries:
- Always supported: GIF, PNG (via Tkinter)
- With PIL/Pillow: JPG, BMP, ICO, TIF, animated GIF
- Platform notes: macOS may have limited GIF support without PIL
Canvas Coordinate System
The Drawing widget uses a standard computer graphics coordinate system:
- Origin (0, 0) is at the top-left corner
- X increases to the right
- Y increases downward
- All coordinates are in pixels
Color Specifications
All display widgets support multiple color formats:
- Named colors: "red", "blue", "green", "white", "black", "yellow", etc.
- Hex colors: "#FF0000", "#00FF00", "#0000FF", etc.
- RGB tuples: (255, 0, 0), (0, 255, 0), (0, 0, 255), etc.
Install with Tessl CLI
npx tessl i tessl/pypi-guizero