Canvas

macOS

GTK+

Windows

iOS

Android

Django

y

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

  • 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 nodes as children of this one. If a node already has a different parent, it will be moved over. This does nothing if a node already is a child of this node.

Parameters

children – Nodes to add as children of this node.

Raises

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

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

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

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

property enabled
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 (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.

focus()
property id

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

Returns

The widgets identifier as a str.

insert(index, child)

Insert a node as a child of this one. If the node already has a different parent, it will be moved over. This does nothing if the node already is a child of this node.

Parameters
  • index – Position of child node.

  • child – A node to insert as a child of this node.

Raises

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

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.

measure_text(text, font, tight=False)
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.

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.

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

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

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

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=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=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 (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=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.

class toga.widgets.canvas.FillRule(value)

An enumeration.

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.