Canvas

from zpui_lib.ui import Canvas
...
c = Canvas(o)
c.centered_text("Hello world", font=("Fixedsys62.ttf", 16))
c.display()

class zpui_lib.ui.Canvas(o, base_image=None, name='', interactive=False)

This object allows you to work with graphics on the display quicker and easier. You can draw text, graphical primitives, insert bitmaps and do other things that the PIL library allows, with a bunch of useful helper functions.

Args:

• o: output device

• base_image: a PIL.Image to use as a base, if needed

• name: a name, for internal usage

• interactive: whether the canvas updates the display after each drawing

background_color = 'black'

default background color to use for drawing

default_color = 'white'

default color to use for drawing

width = 0

width of canvas in pixels.

height = 0

height of canvas in pixels.

size = (0, 0)

a tuple of (width, height).

image = None

PIL.Image object the Canvas is currently operating on.

load_font(path, size, alias=None, type='truetype')

Loads a font by its path for the given size, then returns it. Also, stores the font in the canvas.py font_cache dictionary, so that it doesn’t have to be re-loaded later on.

Supports both absolute paths, paths relative to root ZPUI directory and paths to fonts in the ZPUI font directory (ui/fonts by default).

decypher_font_reference(reference)

Is designed to detect the various ways that a font argument can be passed into a function, then return an ImageFont instance.

point(coord_pairs, **kwargs)

Draw a point, or multiple points on the canvas. Coordinates are expected in ((x1, y1), (x2, y2), ...) format, where x* & y* are coordinates of each point you want to draw.

Keyword arguments:

• fill: point color (default: white, as default canvas color)

line(coords, **kwargs)

Draw a line on the canvas. Coordinates are expected in (x1, y1, x2, y2) format, where x1 & y1 are coordinates of the start, and x2 & y2 are coordinates of the end.

Keyword arguments:

• fill: line color (default: white, as default canvas color)

• width: line width (default: 0, which results in a single-pixel-wide line)

text(text, coords, **kwargs)

Draw text on the canvas. Coordinates are expected in (x, y) format, where x & y are coordinates of the top left corner.

You can pass a font keyword argument to it - it accepts either a PIL.ImageFont object or a tuple of (path, size), which are then supplied to Canvas.load_font().

Do notice that order of first two arguments is reversed compared to the corresponding PIL.ImageDraw method.

Keyword arguments:

• fill: text color (default: white, as default canvas color)

vertical_text(text, coords, **kwargs)

Draw vertical text on the canvas. Coordinates are expected in (x, y) format, where x & y are coordinates of the top left corner.

You can pass a font keyword argument to it - it accepts either a PIL.ImageFont object or a tuple of (path, size), which are then supplied to Canvas.load_font().

Do notice that order of first two arguments is reversed compared to the corresponding PIL.ImageDraw method.

Keyword arguments:

• fill: text color (default: white, as default canvas color)

custom_shape_text(text, coords_cb, **kwargs)

Draw text on the canvas, getting the position for each character from a supplied function. Coordinates are expected in (x, y) format, where x & y are coordinates of the top left corner of the character.

You can pass a font keyword argument to it - it accepts either a PIL.ImageFont object or a tuple of (path, size), which are then supplied to Canvas.load_font().

Do notice that order of first two arguments is reversed compared to the corresponding PIL.ImageDraw method.

Keyword arguments:

• fill: text color (default: white, as default canvas color)

rectangle(coords, **kwargs)

Draw a rectangle on the canvas. Coordinates are expected in (x1, y1, x2, y2) format, where x1 & y1 are coordinates of the top left corner, and x2 & y2 are coordinates of the bottom right corner.

Keyword arguments:

• outline: outline color (default: white, as default canvas color)

• fill: fill color (default: None, as in, transparent)

rectangle_wh(coords, **kwargs)

Draw a rectangle on the canvas. Coordinates are expected in (x1, y1, w, h) format, where x1 & y1 are coordinates of the top left corner, and w & h are width and height of the rectangle.

Keyword arguments:

• outline: outline color (default: white, as default canvas color)

• fill: fill color (default: None, as in, transparent)

This function calls rectangle internally.

polygon(coord_pairs, **kwargs)

Draw a polygon on the canvas. Coordinates are expected in ((x1, y1), (x2, y2), (x3, y3),  [...]) format, where xX and yX are points that construct a polygon.

Keyword arguments:

• outline: outline color (default: white, as default canvas color)

• fill: fill color (default: None, as in, transparent)

circle(coords, **kwargs)

Draw a circle on the canvas. Coordinates are expected in (xc, yx, r) format, where xc & yc are coordinates of the circle center and r is the radius.

Keyword arguments:

• outline: outline color (default: white, as default canvas color)

• fill: fill color (default: None, as in, transparent)

ellipse(coords, **kwargs)

Draw a ellipse on the canvas. Coordinates are expected in (x1, y1, x2, y2) format, where x1 & y1 are coordinates of the top left corner, and x2 & y2 are coordinates of the bottom right corner.

Keyword arguments:

• outline: outline color (default: white, as default canvas color)

• fill: fill color (default: None, as in, transparent)

arc(coords, start, end, **kwargs)

Draw an arc on the canvas. Coordinates are expected in (x1, y1, x2, y2) format, where x1 & y1 are coordinates of the top left corner, and x2 & y2 are coordinates of the bottom right corner. start and end angles are measured in degrees (360 is a full circle), start at 0 (3 o’clock) and increase clockwise.

Arc angle alignment reference:

# 270 # 225 315 # 180 0 # 135 45 # 90

Keyword arguments:

• fill: text color (default: white, as default canvas color)

get_image(coords=None)

Get the current PIL.Image object. If coords are supplied, reeturns a rectangular region of the image, as defined by coords.

get_center(x=None, y=None)

Get center coordinates. Will not represent the physical center - especially with those displays having even numbers as width and height in pixels (that is, the absolute majority of them).

You can substitute width and height of your choice as x and y, purely so you can quickly center things in arbitrary areas.

center_box(wb, hb, w=None, h=None, return_four=False)

Get coordinates to center a (wb, wh) box inside an area of (w, h). Basically, returns coordinates for the top left corner of a centered object.

More or less, is a shorthand to get rid of some annoying math in app code.

invert()

Inverts the image that Canvas is currently operating on.

display()

Display the current image on the o object that was supplied to Canvas.

clear(coords=None, fill=None)

Fill an area of the image with default background color. If coordinates are not supplied, fills the whole canvas, effectively clearing it. Uses the background color by default.

check_coordinates(coords, check_count=True, rearrange_coords=True)

A helper function to check and reformat coordinates supplied to functions. Currently, accepts integer coordinates, as well as strings - denoting offsets from opposite sides of the screen.

check_coordinate_pairs(coord_pairs)

A helper function to check and reformat coordinate pairs supplied to functions. Each pair is checked by check_coordinates.

centered_text(text, cw=None, ch=None, ox=0, oy=0, font=None)

Draws centered text on the canvas. This is mostly a convenience function, used in some UI elements. You can pass alternate screen center values (cw, ch) so that text is centered related to those, as opposed to the actual screen center.

You can also pass offsets (ox and oy) - for instance, pass oy=-32 to bring text 32 pixels upwards.

get_text_bounds(text, font=None)

Returns the uncompensated dimensions for a given text. If you use a non-default font, pass it as font.

get_text_bounds_compensated(text, font=None)

Returns the compensated dimensions for a given text. If you use a non-default font, pass it as font.

get_centered_text_bounds(text, cw=None, ch=None, x=None, y=None, font=None)

Returns the coordinates for the text to be centered on the screen. The coordinates come wrapped in a Rect object. If you use a non-default font, pass it as font. You can also pass alternate screen center values so that text is centered related to those, as opposed to the real screen center.

get_rect(coords)

Returns a rectangular region of the image, as defined by coords.

invert_rect(coords)

Inverts the image in the given rectangle region. Is useful for highlighting a part of the image, for example.

paste(image_or_path, coords=None, invert=False, mask='auto')

Pastes the supplied image onto the canvas, with optional coordinates. Otherwise, you can supply a string path to an image that will be opened and pasted.

If coords is not supplied, the image will be pasted in the top left corner. coords can be a 2-tuple giving the upper left corner or a 4-tuple defining the left, upper, right and lower pixel coordinate. If a 4-tuple is given, the size of the pasted image must match the size of the region.

show_grid(step_x=20, step_y=20)

Helper function for checking your coordinate placement

class zpui_lib.ui.MockOutput(width=None, height=None, type=None, device_mode=None, o=None, warn_on_display=True, hook=None)

A mock output device that you can use to draw icons and other bitmaps using Canvas.

Keyword arguments:

• width

• height

• type: ZPUI output device type list (["b&w"] by default)

• device_mode: PIL device.mode attribute (by default, '1')

zpui_lib.ui.open_image(path, *args, **kwargs)

Simple wrapper around PIL.Image.open, that simplifies imports somewhat, and will allow us to improve upon it in the future.

zpui_lib.ui.invert_image(path, *args, **kwargs)

Simple wrapper around PIL.ImageOps.invert, that simplifies imports somewhat, and will allow us to improve upon it in the future.

zpui_lib.ui.crop(image, min_width=None, min_height=None, align=None)

Default crop alignment: top left. You can pass an argument to align= to align it differently. You can pass a string like "right"/"bottom"/"hcenter"/"vcenter", or pass a list of strings, like ["right", "vcenter"].

"right" and "hcenter" arguments require you to specify min_width, and "bottom" and "vcenter" arguments require you to specify min_height.

zpui_lib.ui.expand_coords(coords, expand_by)

A simple method to expand 4 coordinates: x1, y1, x2, y2. If expand_by is an integer/float, will do x1-v, y1-v, x2+v, y2+v. If expand_by is a list of 4 values, will do x1-v1, y1-v1, x2+v2, y2+v2.

zpui_lib.ui.replace_color(icon, fromc, toc)

zpui_lib.ui.swap_colors(icon, fromc1, toc1, fromc2, toc2)