Canvas

from ui import Canvas
...
c = Canvas(o)
c.text("Hello world", (10, 20))
c.display()

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

Bases: object

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).

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)

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)

get_image()

Get the current PIL.Image object.

get_center()

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).

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)

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, font=None)

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

get_text_bounds(text, font=None)

Returns the 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, 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.

invert_rect(coords)

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

class ui.MockOutput(width=128, height=64, type=None, device_mode='1')

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')