displaysys

displaysys

displaysys

A collection of classes and functions for working with displays and input devices in *Python. The goal is to provide a common API for working with displays and input devices across different platforms including MicroPython, CircuitPython and CPython. It works on microcontrollers, desktops, web browsers and Jupyter notebooks.

Classes

DisplayDriver

DisplayDriver(auto_refresh=False)

Base class for all display backends (BusDisplay, SDL2Display, FBDisplay, etc.).

Subclasses implement bus- or platform-specific drawing and refresh. Most applications use a concrete driver from board_config.display rather than instantiating this class directly.

Parameters:

Name	Type	Description	Default
auto_refresh		If True or an integer period in ms, starts a multimer timer that calls show() automatically.	False

Attributes

width property

width

The width of the display in pixels.

height property

height

The height of the display in pixels.

rotation property writable

rotation

The rotation of the display.

touch_device property writable

touch_device

The touch device.

requires_byteswap property

requires_byteswap

Whether the display requires byte swapping.

vscroll property writable

vscroll

The vertical scroll position relative to the top fixed area.

Returns:

Type	Description
int	The vertical scroll position.

tfa property

tfa

The top fixed area set by set_vscroll or vscrdef.

Returns:

Type	Description
int	The top fixed area.

vsa property

vsa

The vertical scroll area set by set_vscroll or vscrdef.

Returns:

Type	Description
int	The vertical scroll area.

bfa property

bfa

The bottom fixed area set by set_vscroll or vscrdef.

Returns:

Type	Description
int	The bottom fixed area.

tfa_area property

tfa_area

Top fixed area for vertical scrolling.

Returns:

Type	Description
	tuple[int, int, int, int]: (x, y, width, height) of the top fixed band.

vsa_area property

vsa_area

The vertical scroll area as an Area object.

Returns:

Type	Description
tuple	The vertical scroll area.

bfa_area property

bfa_area

The bottom fixed area as an Area object.

Returns:

Type	Description
tuple	The bottom fixed area.

power property writable

power

The power state of the display.

brightness property writable

brightness

The brightness of the display.

Methods:

fill

fill(color)

Fill the display with a color.

Parameters:

Name	Type	Description	Default
color	int	The color to fill the display with.	required

scroll

scroll(dx, dy)

Scroll the display.

Parameters:

Name	Type	Description	Default
dx	int	The number of pixels to scroll horizontally.	required
dy	int	The number of pixels to scroll vertically.	required

disable_auto_byteswap

disable_auto_byteswap(value)

Disable byte swapping in the display driver.

If self.requires_byteswap and the guest application is capable of byte swapping color data check to see if byte swapping can be disabled. If so, disable it.

Usage

# If byte swapping is required and the display driver is capable of having byte swapping disabled,
# disable it and set a flag so we can swap the color bytes as they are created.
if display_drv.requires_byteswap:
    needs_swap = display_drv.disable_auto_byteswap(True)
else:
    needs_swap = False

Parameters:

Name	Type	Description	Default
value	bool	Whether to disable byte swapping.	required

Returns:

Type	Description
bool	Whether byte swapping was disabled successfully.

blit_transparent

blit_transparent(buf, x, y, w, h, key)

Blit a buffer with transparency.

Parameters:

Name	Type	Description	Default
buf	memoryview	The buffer to blit.	required
x	int	The x coordinate to blit to.	required
y	int	The y coordinate to blit to.	required
w	int	The width to blit.	required
h	int	The height to blit.	required
key	int	The color key to use for transparency.	required

Returns:

Type	Description
tuple	The x, y, w, h coordinates of the blitted area.

set_vscroll

set_vscroll(tfa=0, bfa=0)

Set the vertical scroll definition and move the vertical scroll to the top.

Parameters:

Name	Type	Description	Default
tfa	int	The top fixed area.	0
bfa	int	The bottom fixed area.	0

translate_point

translate_point(point)

Translate a point from real coordinates to scrolled coordinates.

Useful for touch events.

Parameters:

Name	Type	Description	Default
point	tuple	The x and y coordinates to translate.	required

Returns:

Type	Description
tuple	The translated x and y coordinates.

vscrdef

vscrdef(tfa, vsa, bfa)

Set the vertical scroll definition. Should be overridden by the subclass and called as super().vscrdef(tfa, vsa, bfa).

Parameters:

Name	Type	Description	Default
tfa	int	The top fixed area.	required
vsa	int	The vertical scroll area.	required
bfa	int	The bottom fixed area.	required

vscsad

vscsad(vssa=None)

Set or get the vertical scroll start address. Should be overridden by the subclass and called as super().vscsad(y).

Parameters:

Name	Type	Description	Default
vssa	int	The vertical scroll start address.	None

Returns:

Type	Description
int	The vertical scroll start address.

invert_colors

invert_colors(value)

Invert the colors of the display. Should be overridden by the subclass.

Parameters:

Name	Type	Description	Default
value	bool	True to invert the colors, False to restore the colors.	required

reset

reset()

Perform a reset of the display. Should be overridden by the subclass.

hard_reset

hard_reset()

Perform a hardware reset of the display. Should be overridden by the subclass.

soft_reset

soft_reset()

Perform a software reset of the display. Should be overridden by the subclass.

sleep_mode

sleep_mode(value)

Set the sleep mode of the display. Should be overridden by the subclass.

Parameters:

Name	Type	Description	Default
value	bool	True to enter sleep mode, False to exit sleep mode.	required

deinit

deinit()

Deinitialize the display. Stops the auto-refresh timer so it can't fire after resources are released. Idempotent. Subclasses that override this should call super().deinit().

quit

quit(code=0)

Release resources and terminate the program.

Called by eventsys.devices.Broker.quit() on a window-close (QUIT) event. The base implementation deinitializes the display and raises SystemExit, which is correct for front ends that poll on the main thread. Drivers needing a platform-specific exit (e.g. SDLDisplay, where SystemExit raised from the LVGL scheduled task handler is swallowed on the unix port) should override this.

show

show(*args, **kwargs)

Show the display. Base class method does nothing. May be overridden by subclasses.

Functions:

alloc_buffer

alloc_buffer(size)

Create a new buffer of the specified size. In the future, this function may be modified to use port-specific memory allocation such as ESP32's heap_caps_malloc.

Parameters:

Name	Type	Description	Default
size	int	The size of the buffer to create.	required

Returns:

Type	Description
memoryview	The new buffer.

color565

color565(r, g=None, b=None)

Convert RGB values to a 16-bit color value.

Parameters:

Name	Type	Description	Default
r	(int, tuple or list)	The red value or a tuple or list of RGB values.	required
g	int	The green value.	None
b	int	The blue value.	None

Returns:

Type	Description
int	The 16-bit color value

color565_swapped

color565_swapped(r, g=0, b=0)

Convert RGB to 16-bit RGB565 with byte order swapped for some displays.

Parameters:

Name	Type	Description	Default
r	int | tuple | list	Red value, or an (r, g, b) sequence.	required
g	int	Green value when r is an int.	0
b	int	Blue value when r is an int.	0

Returns:

Name	Type	Description
int		Byte-swapped RGB565 color.

color332

color332(r, g, b)

Convert RGB to 8-bit RGB332 color.

Parameters:

Name	Type	Description	Default
r	int	Red (0-255).	required
g	int	Green (0-255).	required
b	int	Blue (0-255).	required

Returns:

Name	Type	Description
int		RGB332 color byte.

color_rgb

color_rgb(color)

Expand a display color to an (r, g, b) tuple.

Parameters:

Name	Type	Description	Default
color	int | tuple | list | bytearray	16-bit RGB565 int or 2-3 byte sequence.	required

Returns:

Type	Description
	tuple[int, int, int]: Red, green, blue (0-255 each).