Canvas#
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 releasedon_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.
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 radiusr
starting atstartangle
and ending atendangle
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.
- 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:
- 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.
- quadratic_curve_to(cpx, cpy, x, y)#
Constructs and returns a
QuadraticCurveTo
.- Parameters:
- Returns:
QuadraticCurveTo
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
- 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 radiiradiusx
andradiusy
starting atstartangle
and ending atendangle
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:
- 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).
- 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.
- 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.
- 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
andsy
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:
- 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.