Canvas

macOS GTK+ Windows iOS Android Django
y y   y    

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, 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) – Function to call when resized.
  • factory (module) – A python module that is capable to return a implementation of this class with the same name. (optional & normally not needed)
add(*children)

Add a node as a child of this one. :param child: A node to add as a child to this node.

Raises:ValueError – If this node is a leaf, and cannot have children.
app

The App to which this widget belongs. On setting the app we also iterate over all children of this widget and set them to the same app.

Returns:The toga.App to which this widget belongs.
Raises:ValueError – If the widget is already associated with another app.
arc(x, y, radius, startangle=0.0, endangle=6.283185307179586, anticlockwise=False)

Constructs and returns a Arc.

Parameters:
  • x (float) – The x coordinate of the arc’s center.
  • y (float) – The y coordinate of the arc’s center.
  • radius (float) – The arc’s radius.
  • startangle (float, optional) – The angle (in radians) at which the arc starts, measured clockwise from the positive x axis, default 0.0.
  • endangle (float, optional) – The angle (in radians) at which the arc ends, measured clockwise from the positive x axis, default 2*pi.
  • anticlockwise (bool, optional) – 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.

can_have_children

Determine if the node can have children.

This does not resolve whether there actually are any children; it only confirms whether children are theoretically allowed.

children

The children of this node. This always returns a list, even if the node is a leaf and cannot have children.

Returns:A list of the children for this widget.
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=6.283185307179586, anticlockwise=False)

Constructs and returns a Ellipse.

Parameters:
  • x (float) – The x axis of the coordinate for the ellipse’s center.
  • y (float) – The y axis of the coordinate for the ellipse’s center.
  • radiusx (float) – The ellipse’s major-axis radius.
  • radiusy (float) – The ellipse’s minor-axis radius.
  • rotation (float, optional) – The rotation for this ellipse, expressed in radians, default 0.0.
  • startangle (float, optional) – The starting point in radians, measured from the x axis, from which it will be drawn, default 0.0.
  • endangle (float, optional) – The end ellipse’s angle in radians to which it will be drawn, default 2*pi.
  • anticlockwise (bool, optional) – If true, draws the ellipse anticlockwise (counter-clockwise) instead of clockwise, default false.
Returns:

Ellipse object.

enabled
fill(color='black', fill_rule='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 (str, optional) – ‘nonzero’ is the non-zero winding rule and ‘evenodd’ is the even-odd winding rule.
  • preserve (bool, optional) – Preserves the path within the Context.
  • color (str, optional) – color value in any valid color format, default to black.
Yields:

Fill object.

id

The node identifier. This id can be used to target styling directives

Returns:The widgets identifier as a str.
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 <NewPath> object.
on_resize

The handler to invoke when the canvas is resized.

Returns:The function callable that is called on canvas resize.
parent

The parent of this node.

Returns:The parent of this node. Returns None if this node is the root node.
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.

refresh()

Refresh the layout and appearance of the tree this node is contained in.

refresh_sublayouts()
remove(drawing_object)

Remove a drawing object

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

Constructs and returns a ResetTransform.

Returns:ResetTransform object.
root

The root of the tree containing this node.

Returns:The root node. Returns self if this node is the root node.
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 (float) – scale factor for the X dimension.
  • sy (float) – scale factor for the Y dimension.
Returns:

Scale object.

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.

translate(tx, ty)

Constructs and returns a Translate.

Parameters:
  • tx (float) – X value of coordinate.
  • ty (float) – Y value of coordinate.
Returns:

Translate object.

window

The Window to which this widget belongs. On setting the window, we automatically update all children of this widget to belong to the same window.

Returns:The toga.Window to which the widget belongs.
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 (string) – 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.Font, optional) – The font to write with.
Returns:

WriteText object.

Lower-Level Classes

class toga.widgets.canvas.Arc(x, y, radius, startangle=0.0, endangle=6.283185307179586, 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 (float) – The x coordinate of the arc’s center.
  • y (float) – The y coordinate of the arc’s center.
  • radius (float) – The arc’s radius.
  • startangle (float, optional) – The angle (in radians) at which the arc starts, measured clockwise from the positive x axis, default 0.0.
  • endangle (float, optional) – The angle (in radians) at which the arc ends, measured clockwise from the positive x axis, default 2*pi.
  • anticlockwise (bool, optional) – 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=6.283185307179586, anticlockwise=False)

Constructs and returns a Arc.

Parameters:
  • x (float) – The x coordinate of the arc’s center.
  • y (float) – The y coordinate of the arc’s center.
  • radius (float) – The arc’s radius.
  • startangle (float, optional) – The angle (in radians) at which the arc starts, measured clockwise from the positive x axis, default 0.0.
  • endangle (float, optional) – The angle (in radians) at which the arc ends, measured clockwise from the positive x axis, default 2*pi.
  • anticlockwise (bool, optional) – 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.

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=6.283185307179586, anticlockwise=False)

Constructs and returns a Ellipse.

Parameters:
  • x (float) – The x axis of the coordinate for the ellipse’s center.
  • y (float) – The y axis of the coordinate for the ellipse’s center.
  • radiusx (float) – The ellipse’s major-axis radius.
  • radiusy (float) – The ellipse’s minor-axis radius.
  • rotation (float, optional) – The rotation for this ellipse, expressed in radians, default 0.0.
  • startangle (float, optional) – The starting point in radians, measured from the x axis, from which it will be drawn, default 0.0.
  • endangle (float, optional) – The end ellipse’s angle in radians to which it will be drawn, default 2*pi.
  • anticlockwise (bool, optional) – If true, draws the ellipse anticlockwise (counter-clockwise) instead of clockwise, default false.
Returns:

Ellipse object.

fill(color='black', fill_rule='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 (str, optional) – ‘nonzero’ is the non-zero winding rule and ‘evenodd’ is the even-odd winding rule.
  • preserve (bool, optional) – Preserves the path within the Context.
  • color (str, optional) – 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 <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 (string) – 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.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=6.283185307179586, 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 (float) – The x axis of the coordinate for the ellipse’s center.
  • y (float) – The y axis of the coordinate for the ellipse’s center.
  • radiusx (float) – The ellipse’s major-axis radius.
  • radiusy (float) – The ellipse’s minor-axis radius.
  • rotation (float, optional) – The rotation for this ellipse, expressed in radians, default 0.0.
  • startangle (float, optional) – The starting point in radians, measured from the x axis, from which it will be drawn, default 0.0.
  • endangle (float, optional) – The end ellipse’s angle in radians to which it will be drawn, default 2*pi.
  • anticlockwise (bool, optional) – If true, draws the ellipse anticlockwise (counter-clockwise) instead of clockwise, default false.
class toga.widgets.canvas.Fill(color='black', fill_rule='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.
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 (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) – 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.

Parameters:
  • sx (float) – scale factor for the X dimension.
  • sy (float) – 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.
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 (float) – X value of coordinate.
  • ty (float) – 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 (string) – 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.Font, optional) – The font to write with.