DrawingAction¶

For many if not most applications, the interface documented for Canvas is sufficient. However, it is also possible to directly manipulate a Canvas's stored instructions, thereby modifying the results in a non-linear fashion.

Usage¶

Each drawing operation that has been performed on a Canvas is represented by an object of class DrawingAction. Each drawing method has a corresponding DrawingAction subclass of the same name, except in CamelCase. For example, the line_to() method creates a LineTo object, and LineTo is a subclass of DrawingAction.

The current state of the drawing context is represented by a state object. All states are subclasses of the abstract BaseState; the simplest is State. Initially, a canvas has only one state; this initial state is always accessible via the canvas's root_state attribute.

Each state stores a list of its associated drawing actions.

import toga

canvas = toga.Canvas()

print(canvas.root_state)
# State()
print(canvas.root_state.drawing_actions)
# []

canvas.rect(0, 0, 10, 10)
canvas.stroke()

print(canvas.root_state.drawing_actions)
# [Rect(x=0, y=0, width=10, height=10),
#  Stroke(stroke_style=None, line_width=None, line_dash=None)]

When you save and then restore the state of the drawing context using a context manager (e.g., state(), stroke(), or fill()), a new state object is created and inserted into the currently active state's drawing_actions. This is possible because BaseState is itself a subclass of DrawingAction.

Continuing from the previous example:

with canvas.state():
    canvas.line_width = 10
    canvas.line_dash = [1, 2]

canvas.fill()

print(canvas.root_state.drawing_actions)
# [Rect(x=0, y=0, width=10, height=10),
#  Stroke(stroke_style=None, line_width=None, line_dash=None),
#  State(),
#  Fill(fill_rule=FillRule.NONZERO, fill_style=None)]

The actions corresponding to setting line width and line dash are contained inside the State(), like so:

root_state ─┬─ Rect
            ├─ Stroke
            ├─ State ──┬─ SetLineWidth
            └─ Fill    └─ SetLineDash

Note that the the Fill isn't inside the State, because its method was called after the context manager exited.

Accessing specific drawing actions¶

A state's drawing actions are a list, and can be accessed using list syntax. For example, if you wanted to access the Fill object in the previous example, you could use:

fill = canvas.root_state.drawing_actions[3]

However, this is not very practical, especially if the action of interest is nested within several states. A better way is to leverage the fact that each drawing method returns its drawing action. The line calling the fill method could be modified to:

fill = canvas.fill()

And now fill is a direct reference to the Fill object. This Fill object can then be modified as required.

The same is true even when a method is being used as a context manager, using with ... as ... syntax. For instance, the following code would bind fill, stroke, and move_to to the Fill, Stroke, and MoveTo drawing actions created by the methods called:

with canvas.fill() as fill:
    with canvas.stroke() as stroke:
        move_to = canvas.move_to(0, 0)

Modifying attributes of drawing actions¶

DrawingAction objects also have attributes corresponding to the equivalent method's parameters. If you modify these attributes, it will retroactively alter what is drawn on the canvas. For example, consider the following code and its output:

import toga

canvas = toga.Canvas(width=200, height=200)
with canvas.stroke() as stroke:
    canvas.move_to(50, 50)
    first_line = canvas.line_to(150, 50)
    canvas.line_to(50, 150)

Initial output — An initial set of strokes on a canvas.

Since we've saved references, we can alter the parameters of the stroke and the first line segment. After altering attributes like this, the canvas's redraw() method must be called to ensure the results are rendered on screen.

stroke.line_width = 20
first_line.y = 150

canvas.redraw()

After editing — An updated stroke path and width, after calling `redraw()` on the canvas.

The line has gotten wider, and the second point has moved down to a y coordinate of 150, which alters the orientation of both line segments.

Creating and adding new drawing actions¶

DrawingAction objects can also be created directly, and the list of DrawingAction objects on a state can be manually altered. As with altering attributes, and direct modification of the lists of drawing actions should be followed by a call to the canvas's redraw method.

An extra point could be added to the above path like so:

from toga.widgets.canvas import LineTo

new_point = LineTo(150, 50)
stroke.drawing_actions.insert(1, new_point)

canvas.redraw()

After adding a new drawing action — An updated stroke with an additional line segment, after calling `redraw()` on the canvas.

This example uses insert, but drawing_actions is a list, with all of a list's normal methods, including append, remove, and extend. Remember to call redraw after any such alterations.

Reference¶

Bases: ABC

A Canvas drawing operation.

Every canvas drawing method creates a DrawingAction, adds it to the currently active state, and returns it. Each argument passed to the method becomes a property of the DrawingAction, which can be modified as shown in Modifying attributes of Drawing actions.

A DrawingAction can also be created manually. Their constructors take the same arguments as the corresponding Canvas drawing method, and their classes have the same names, but capitalized.

Source code in core/src/toga/widgets/canvas/drawingaction.py

class DrawingAction(ABC):
    """A [`Canvas`][toga.Canvas] drawing operation.

    Every canvas drawing method creates a `DrawingAction`, adds it to the currently
    active state, and returns it. Each argument passed to the method becomes a property
    of the `DrawingAction`, which can be modified as shown in
    [Modifying attributes of Drawing actions][].

    A `DrawingAction` can also be
    [created manually][creating-and-adding-new-drawing-actions]. Their constructors take
    the same arguments as the corresponding [`Canvas`][toga.Canvas] drawing method, and
    their classes have the same names, but capitalized.
    """

    def __repr__(self) -> str:
        if is_dataclass(self):
            str_fields = []
            for field in fields(self):
                match value := getattr(self, field.name):
                    case float():
                        str_value = f"{value:.3f}"
                    case Enum():
                        str_value = str(value)
                    case _:
                        str_value = repr(value)
                str_fields.append(f"{field.name}={str_value}")

            parenthetical = ", ".join(str_fields)

        else:
            parenthetical = ""

        return f"{type(self).__name__}({parenthetical})"

    @abstractmethod
    def _draw(self, context: Any) -> None:
        """Called by parent state to execute this drawing action."""

    def __contains__(self, other: DrawingAction):
        return hasattr(self, "drawing_actions") and any(
            action is other or other in action for action in self.drawing_actions
        )

Bases: DrawingAction, DrawingActionDispatch, ABC

A base class for all drawing actions that can function as state-saving context managers.

Source code in core/src/toga/widgets/canvas/state.py

class BaseState(DrawingAction, DrawingActionDispatch, ABC):
    """A base class for all drawing actions that can function as state-saving context
    managers.
    """

    drawing_actions: list[DrawingAction]
    """The list of all drawing actions contained by this state.

    If you add or remove drawing actions to this list, you'll need to call
    [`Canvas.redraw()`][toga.Canvas.redraw] for the changes to be rendered.
    """

    def __init__(self):
        self.drawing_actions = []
        self._can_be_entered = True

    @abstractmethod
    def _draw(self, context: Any) -> None: ...

    @property
    def _action_target(self):
        # State itself holds its drawing actions.
        return self

    @property
    def _active_state(self):
        """Return the currently active state, either this or a sub-state."""
        if self.drawing_actions:
            # If a sub-state is active, it must be the last action in the list;
            # subsequent actions would be added to that sub-state (or a sub-state of
            # it).
            last = self.drawing_actions[-1]
            if getattr(last, "_is_open", False):
                return last._active_state

        return self

    def __enter__(self):
        if not self._can_be_entered:
            raise RuntimeError(
                "A Canvas context manager can only be entered once, and only before "
                "any subsequent drawing actions are added."
            )

        self._is_open = True
        self._can_be_entered = False
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        self._is_open = False
        # Don't suppress any exceptions
        return False

    ##########################################################################
    # 2026-04: Backwards compatibility for <= 0.5.3
    ##########################################################################

    # These preserve the old signature, and warn about the new one.

    def fill(
        self,
        color: ColorT | None | object = NOT_PROVIDED,
        fill_rule: FillRule = FillRule.NONZERO,
    ) -> AbstractContextManager[Fill]:
        fill = Fill(fill_rule=fill_rule, fill_style=color)
        self._add_to_target(fill)
        warnings.warn(
            (
                "Calling drawing methods on a state is deprecated. To add actions "
                "to the currently active state, call drawing methods on the canvas. "
                "Additionally, the Canvas.fill() method's color parameter can only be "
                "provided via keyword. fill_rule is the only argument it accepts "
                "positionally."
            ),
            DeprecationWarning,
            stacklevel=2,
        )
        self._redraw_without_warning()
        return fill

    def stroke(
        self,
        color: ColorT | None | NOT_PROVIDED = NOT_PROVIDED,
        line_width: float | None = None,
        line_dash: list[float] | None = None,
    ) -> AbstractContextManager[Stroke]:
        stroke = Stroke(stroke_style=color, line_width=line_width, line_dash=line_dash)
        self._add_to_target(stroke)
        warnings.warn(
            (
                "Calling drawing methods on a state is deprecated. To add actions "
                "to the currently active state, call drawing methods on the canvas. "
                "Additionally, the Canvas.stroke() method's arguments can only be "
                "provided as keywords. It does not accept any positional arguments."
            ),
            DeprecationWarning,
            stacklevel=2,
        )
        self._redraw_without_warning()
        return stroke

    ###########################################################################
    # 2026-02: Backwards compatibility for Toga <= 0.5.3
    ###########################################################################

    def __len__(self) -> int:
        self._warn_list_methods()
        return len(self.drawing_actions)

    def __getitem__(self, index: int) -> DrawingAction:
        self._warn_list_methods()
        return self.drawing_actions[index]

    def append(self, obj: DrawingAction) -> None:
        self._warn_list_methods()
        self.drawing_actions.append(obj)
        self._redraw_without_warning()

    def insert(self, index: int, obj: DrawingAction) -> None:
        self._warn_list_methods()
        self.drawing_actions.insert(index, obj)
        self._redraw_without_warning()

    def remove(self, obj: DrawingAction) -> None:
        self._warn_list_methods()
        self.drawing_actions.remove(obj)
        self._redraw_without_warning()

    def clear(self) -> None:
        self._warn_list_methods()
        self.drawing_actions.clear()
        self._redraw_without_warning()

    @property
    def canvas(self) -> Canvas:
        warnings.warn(
            "States no longer hold a reference to their canvas.",
            DeprecationWarning,
            stacklevel=2,
        )

        from .canvas import Canvas

        # Get the first that matches.
        for canvas in Canvas._instances:
            if self is canvas.root_state or self in canvas.root_state:
                return canvas

        return None

    def redraw(self) -> None:
        warnings.warn(
            (
                f"{type(self).__name__}.redraw() is deprecated. Call the canvas's "
                "redraw() method instead."
            ),
            DeprecationWarning,
            stacklevel=2,
        )

        from .canvas import Canvas

        # Redraw any canvases that contain self; could be multiple.
        for canvas in Canvas._instances:
            if self is canvas.root_state or self in canvas.root_state:
                canvas.redraw()

    def _warn_list_methods(self) -> None:
        warnings.warn(
            (
                "A state's list-like methods (append, insert, remove, and clear), as "
                "well as implementing len() and indexing, are deprecated. Manipulate "
                "its drawing_actions directly, and then call redraw() on the canvas."
            ),
            DeprecationWarning,
            stacklevel=3,
        )

`drawing_actions = []` `instance-attribute` ¶

The list of all drawing actions contained by this state.

If you add or remove drawing actions to this list, you'll need to call Canvas.redraw() for the changes to be rendered.