Canvas#

Availability (Key)#

macOS

GTK

Windows

iOS

Android

Web

○

○

○

○

The canvas is used for creating a blank widget that you can draw on.

Usage#

Simple usage to draw a black circle on the screen using the arc drawing object:

import toga
canvas = toga.Canvas(style=Pack(flex=1))
box = toga.Box(children=[canvas])
with canvas.fill() as fill:
    fill.arc(50, 50, 15)

More advanced usage for something like a vector drawing app where you would want to modify the parameters of the drawing objects. Here we draw a black circle and black rectangle. We then change the size of the circle, move the rectangle, and finally delete the rectangle.

import toga
canvas = toga.Canvas(style=Pack(flex=1))
box = toga.Box(children=[canvas])
with canvas.fill() as fill:
    arc1 = fill.arc(x=50, y=50, radius=15)
    rect1 = fill.rect(x=50, y=50, width=15, height=15)

arc1.x, arc1.y, arc1.radius = (25, 25, 5)
rect1.x = 75
fill.remove(rect1)

Use of drawing contexts, for example with a platformer game. Here you would want to modify the x/y coordinate of a drawing context that draws each character on the canvas. First, we create a hero context. Next, we create a black circle and a black outlined rectangle for the hero’s body. Finally, we move the hero by 10 on the x-axis.

import toga
canvas = toga.Canvas(style=Pack(flex=1))
box = toga.Box(children=[canvas])
with canvas.context() as hero:
    with hero.fill() as body:
        body.arc(50, 50, 15)
    with hero.stroke() as outline:
        outline.rect(50, 50, 15, 15)

hero.translate(10, 0)

Reference#

Main Interface#

class toga.widgets.canvas.Canvas(id=None, style=None, on_resize=None, on_press=None, on_release=None, on_drag=None, on_alt_press=None, on_alt_release=None, on_alt_drag=None, factory=None)#

Create new canvas.

Parameters:

  • id (str) – An identifier for this widget.

  • style (Style) – An optional style object. If no style is provided then a new one will be created for the widget.

  • on_resize (Callable) – Handler to invoke when the canvas is resized.

  • on_press (Callable) – Handler to invoke when the primary (usually the left) button is pressed.

  • on_release (Callable) – Handler to invoke when the primary (usually the left) button is released.

  • on_drag (Callable) – Handler to invoke when cursor is dragged with the primary (usually the left) button pressed.

  • on_alt_press (Callable) – Handler to invoke when the alternate (usually the right) button pressed.

  • on_alt_release (Callable) – Handler to invoke when the alternate (usually the right) button released

  • on_alt_drag (Callable) – Handler to invoke when the cursor is dragged with the alternate (usually the right) button pressed.

Create a base Toga widget.

This is an abstract base class; it cannot be instantiated.

Parameters:

  • id – The ID for the widget.

  • style – A style object. If no style is provided, a default style will be applied to the widget.

as_image()#
measure_text(text, font, tight=False)#
property on_alt_drag#

Return the handler to invoke when the mouse is dragged while the alternate (usually the right) mouse button is pressed.

Returns:

The handler that is invoked when the mouse is dragged with the alternate mouse button pressed.

property on_alt_press#

Return the handler to invoke when the alternate (usually the right) mouse button is pressed.

Returns:

The handler that is invoked when the alternate mouse button is pressed.

property on_alt_release#

Return the handler to invoke when the alternate (usually the right) mouse button is released.

Returns:

The handler that is invoked when the alternate mouse button is released.

property on_drag#

Return the handler invoked when the mouse is dragged with the primary (usually the left) mouse button is pressed.

Returns:

The handler that is invoked when the mouse is dragged with the primary button pressed.

property on_press#

Return the handler invoked when the primary (usually the left) mouse button is pressed.

Returns:

The handler that is invoked when the primary mouse button is pressed.

property on_release#

Return the handler invoked when the primary (usually the left) mouse button is released.

Returns:

The handler that is invoked when the primary mouse button is released.

property on_resize#

The handler to invoke when the canvas is resized.

Returns:

The handler that is invoked on canvas resize.

reset_transform()#

Constructs and returns a ResetTransform.

Returns:

ResetTransform object.

rotate(radians)#

Constructs and returns a Rotate.

Parameters:

radians (float) – The angle to rotate clockwise in radians.

Returns:

Rotate object.

scale(sx, sy)#

Constructs and returns a Scale.

Parameters:

  • sx – scale factor for the X dimension.

  • sy – scale factor for the Y dimension.

Returns:

Scale object.

translate(tx, ty)#

Constructs and returns a Translate.

Parameters:

  • tx – X value of coordinate.

  • ty – Y value of coordinate.

Returns:

Translate object.

Lower-Level Classes#

class toga.widgets.canvas.Arc(x, y, radius, startangle=0.0, endangle=2 * pi, anticlockwise=False)#

A user-created Arc drawing object which adds an arc.

The arc is centered at (x, y) position with radius r starting at startangle and ending at endangle going in the given direction by anticlockwise (defaulting to clockwise).

Parameters:

  • x – The x coordinate of the arc’s center.

  • y – The y coordinate of the arc’s center.

  • radius – The arc’s radius.

  • startangle – The angle (in radians) at which the arc starts, measured clockwise from the positive x axis, default 0.0.

  • endangle – The angle (in radians) at which the arc ends, measured clockwise from the positive x axis, default 2*pi.

  • anticlockwise – If true, causes the arc to be drawn counter-clockwise between the two angles instead of clockwise, default false.

class toga.widgets.canvas.BezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y)#

A user-created BezierCurveTo drawing object which adds a Bézier curve.

It requires three points. The first two points are control points and the third one is the end point. The starting point is the last point in the current path, which can be changed using move_to() before creating the Bézier curve.

Parameters:

  • cp1x (float) – x coordinate for the first control point.

  • cp1y (float) – y coordinate for first control point.

  • cp2x (float) – x coordinate for the second control point.

  • cp2y (float) – y coordinate for the second control point.

  • x (float) – x coordinate for the end point.

  • y (float) – y coordinate for the end point.

class toga.widgets.canvas.ClosedPath(x, y)#

A user-created ClosedPath drawing object for a closed path context.

Creates a new path and then closes it.

Parameters:

  • x (float) – The x axis of the beginning point.

  • y (float) – The y axis of the beginning point.

class toga.widgets.canvas.Context(*args, **kwargs)#

The user-created Context drawing object to populate a drawing with visual context.

The top left corner of the canvas must be painted at the origin of the context and is sized using the rehint() method.

arc(x, y, radius, startangle=0.0, endangle=2 * pi, anticlockwise=False)#

Constructs and returns a Arc.

Parameters:

  • x – The x coordinate of the arc’s center.

  • y – The y coordinate of the arc’s center.

  • radius – The arc’s radius.

  • startangle – The angle (in radians) at which the arc starts, measured clockwise from the positive x axis, default 0.0.

  • endangle – The angle (in radians) at which the arc ends, measured clockwise from the positive x axis, default 2*pi.

  • anticlockwise – If true, causes the arc to be drawn counter-clockwise between the two angles instead of clockwise, default false.

Returns:

Arc object.

bezier_curve_to(cp1x, cp1y, cp2x, cp2y, x, y)#

Constructs and returns a BezierCurveTo.

Parameters:

  • cp1x (float) – x coordinate for the first control point.

  • cp1y (float) – y coordinate for first control point.

  • cp2x (float) – x coordinate for the second control point.

  • cp2y (float) – y coordinate for the second control point.

  • x (float) – x coordinate for the end point.

  • y (float) – y coordinate for the end point.

Returns:

BezierCurveTo object.

property canvas#

The canvas property of the current context.

Returns:

The canvas node. Returns self if this node is the canvas node.

clear()#

Remove all drawing objects.

closed_path(x, y)#

Calls move_to(x,y) and then constructs and yields a ClosedPath.

Parameters:

  • x (float) – The x axis of the beginning point.

  • y (float) – The y axis of the beginning point.

Yields:

ClosedPath object.

context()#

Constructs and returns a Context.

Makes use of an existing context. The top left corner of the canvas must be painted at the origin of the context and is sized using the rehint() method.

Yields:

Context object.

ellipse(x, y, radiusx, radiusy, rotation=0.0, startangle=0.0, endangle=2 * pi, anticlockwise=False)#

Constructs and returns a Ellipse.

Parameters:

  • x – The x axis of the coordinate for the ellipse’s center.

  • y – The y axis of the coordinate for the ellipse’s center.

  • radiusx – The ellipse’s major-axis radius.

  • radiusy – The ellipse’s minor-axis radius.

  • rotation – The rotation for this ellipse, expressed in radians, default 0.0.

  • startangle – The starting point in radians, measured from the x axis, from which it will be drawn, default 0.0.

  • endangle – The end ellipse’s angle in radians to which it will e drawn, default 2*pi.

  • anticlockwise – If true, draws the ellipse anticlockwise (counter-clockwise) instead of clockwise, default false.

Returns:

Ellipse object.

fill(color=BLACK, fill_rule=FillRule.NONZERO, preserve=False)#

Constructs and yields a Fill.

A drawing operator that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled).

Parameters:

  • fill_rule – nonzero is the non-zero winding rule; evenodd is the even-odd winding rule.

  • preserve – Preserve the path within the Context.

  • color – color value in any valid color format, default to black.

Yields:

Fill object.

line_to(x, y)#

Constructs and returns a LineTo.

Parameters:

  • x (float) – The x axis of the coordinate for the end of the line.

  • y (float) – The y axis of the coordinate for the end of the line.

Returns:

LineTo object.

move_to(x, y)#

Constructs and returns a MoveTo.

Parameters:

  • x (float) – The x axis of the point.

  • y (float) – The y axis of the point.

Returns:

MoveTo object.

new_path()#

Constructs and returns a NewPath.

Returns:

class: NewPath object.

quadratic_curve_to(cpx, cpy, x, y)#

Constructs and returns a QuadraticCurveTo.

Parameters:

  • cpx (float) – The x axis of the coordinate for the control point.

  • cpy (float) – The y axis of the coordinate for the control point.

  • x (float) – The x axis of the coordinate for the end point.

  • y (float) – The y axis of the coordinate for the end point.

Returns:

QuadraticCurveTo object.

rect(x, y, width, height)#

Constructs and returns a Rect.

Parameters:

  • x (float) – x coordinate for the rectangle starting point.

  • y (float) – y coordinate for the rectangle starting point.

  • width (float) – The rectangle’s width.

  • height (float) – The rectangle’s width.

Returns:

Rect object.

redraw()#

Force a redraw of the Canvas.

The Canvas will be automatically redrawn after adding or remove a drawing object. If you modify a drawing object, this method is used to force a redraw.

remove(drawing_object)#

Remove a drawing object.

Parameters:

( (drawing_object) – obj:’Drawing Object’): The drawing object to remove

stroke(color=BLACK, line_width=2.0, line_dash=None)#

Constructs and yields a Stroke.

Parameters:

  • color (str, Optional) – color value in any valid color format, default to black.

  • line_width (float, Optional) – stroke line width, default is 2.0.

  • line_dash (array of floats, Optional) – stroke line dash pattern, default is None.

Yields:

Stroke object.

write_text(text, x=0, y=0, font=None)#

Constructs and returns a WriteText.

Writes a given text at the given (x,y) position. If no font is provided, then it will use the font assigned to the Canvas Widget, if it exists, or use the default font if there is no font assigned.

Parameters:

  • text (str) – The text to fill.

  • x (float, Optional) – The x coordinate of the text. Default to 0.

  • y (float, Optional) – The y coordinate of the text. Default to 0.

  • font (Font, Optional) – The font to write with.

Returns:

WriteText object.

class toga.widgets.canvas.Ellipse(x, y, radiusx, radiusy, rotation=0.0, startangle=0.0, endangle=2 * pi, anticlockwise=False)#

A user-created Ellipse drawing object which adds an ellipse.

The ellipse is centered at (x, y) position with the radii radiusx and radiusy starting at startangle and ending at endangle going in the given direction by anticlockwise (defaulting to clockwise).

Parameters:

  • x – The x axis of the coordinate for the ellipse’s center.

  • y – The y axis of the coordinate for the ellipse’s center.

  • radiusx – The ellipse’s major-axis radius.

  • radiusy – The ellipse’s minor-axis radius.

  • rotation – The rotation for this ellipse, expressed in radians, default 0.0.

  • startangle – The starting point in radians, measured from the x axis, from which it will be drawn, default 0.0.

  • endangle – The end ellipse’s angle in radians to which it will be drawn, default 2*pi.

  • anticlockwise – If true, draws the ellipse anticlockwise (counter-clockwise) instead of clockwise, default false.

class toga.widgets.canvas.Fill(color=BLACK, fill_rule=FillRule.NONZERO, preserve=False)#

A user-created Fill drawing object for a fill context.

A drawing object that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled).

Parameters:

  • color (str, Optional) – Color value in any valid color format, default to black.

  • fill_rule (str, Optional) – nonzero if the non-zero winding rule and evenodd if the even-odd winding rule.

  • preserve (bool, Optional) – Preserves the path within the Context.

property color#
property fill_rule#
class toga.widgets.canvas.FillRule(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#
EVENODD = 0#
NONZERO = 1#
class toga.widgets.canvas.LineTo(x, y)#

A user-created LineTo drawing object which draws a line to a point.

Connects the last point in the sub-path to the (x, y) coordinates with a straight line (but does not actually draw it).

Parameters:

  • x (float) – The x axis of the coordinate for the end of the line.

  • y (float) – The y axis of the coordinate for the end of the line.

class toga.widgets.canvas.MoveTo(x, y)#

A user-created MoveTo drawing object which moves the start of the next operation to a point.

Moves the starting point of a new sub-path to the (x, y) coordinates.

Parameters:

  • x (float) – The x axis of the point.

  • y (float) – The y axis of the point.

class toga.widgets.canvas.NewPath#

A user-created NewPath to add a new path.

class toga.widgets.canvas.QuadraticCurveTo(cpx, cpy, x, y)#

A user-created QuadraticCurveTo drawing object which adds a quadratic curve.

It requires two points. The first point is a control point and the second one is the end point. The starting point is the last point in the current path, which can be changed using moveTo() before creating the quadratic Bézier curve.

Parameters:

  • cpx – The x axis of the coordinate for the control point.

  • cpy – The y axis of the coordinate for the control point.

  • x – The x axis of the coordinate for the end point.

  • y – he y axis of the coordinate for the end point.

class toga.widgets.canvas.Rect(x, y, width, height)#

A user-created Rect drawing object which adds a rectangle.

The rectangle is at position (x, y) with a size that is determined by width and height. Those four points are connected by straight lines and the sub-path is marked as closed, so that you can fill or stroke this rectangle.

Parameters:

  • x (float) – x coordinate for the rectangle starting point.

  • y (float) – y coordinate for the rectangle starting point.

  • width (float) – The rectangle’s width.

  • height (float) – The rectangle’s width.

class toga.widgets.canvas.ResetTransform#

A user-created ResetTransform to reset the canvas.

Resets the canvas by setting it equal to the canvas with no transformations.

class toga.widgets.canvas.Rotate(radians)#

A user-created Rotate to add canvas rotation.

Modifies the canvas by rotating the canvas by angle radians. The rotation center point is always the canvas origin which is in the upper left of the canvas. To change the center point, move the canvas by using the translate() method.

Parameters:

radians (float) – The angle to rotate clockwise in radians.

class toga.widgets.canvas.Scale(sx, sy)#

A user-created Scale to add canvas scaling.

Modifies the canvas by scaling the X and Y canvas axes by sx and sy respectively.

Parameters:

  • sx – scale factor for the X dimension.

  • sy – scale factor for the Y dimension.

class toga.widgets.canvas.Stroke(color=BLACK, line_width=2.0, line_dash=None)#

A user-created Stroke drawing object for a stroke context.

A drawing operator that strokes the current path according to the current line style settings.

Parameters:

  • color (str, Optional) – Color value in any valid color format, default to black.

  • line_width (float, Optional) – Stroke line width, default is 2.0.

  • line_dash (array of floats, Optional) – Stroke line dash pattern, default is None.

property color#
class toga.widgets.canvas.Translate(tx, ty)#

A user-created Translate to translate the canvas.

Modifies the canvas by translating the canvas origin by (tx, ty).

Parameters:

  • tx – X value of coordinate.

  • ty – Y value of coordinate.

class toga.widgets.canvas.WriteText(text, x, y, font)#

A user-created WriteText to add text.

Writes a given text at the given (x,y) position. If no font is provided, then it will use the font assigned to the Canvas Widget, if it exists, or use the default font if there is no font assigned.

Parameters:

  • text (str) – The text to fill.

  • x (float, Optional) – The x coordinate of the text. Default to 0.

  • y (float, Optional) – The y coordinate of the text. Default to 0.

  • font (toga.fonts.Font, Optional) – The font to write with.