Consolidate Canvas methods / sync API more closely to HTML5

[HalfWhitt]

What is the problem or limitation you are having?

One of the things I found really confusing when I first started looking at the Canvas API — and to be honest, still trips me up — is the way that in addition to the snake_case-named drawing operation methods, there's the whole other set of identically-named (but CamelCase) methods that do the same thing but as a context manager. It's a lot to take in and make sense of.

Describe the solution you'd like

I have an alternative proposal: why not behave like open(), and consolidate the two behaviors in one method? That way each method is in intuitive snake_case, and is either a simple drawing operation when called alone, or a context manager when invoked through with.

I'm sure the nitty gritty details will inevitably be fiddlier than I anticipate, but I believe the basic idea would be to remove the @contextmanager decorator from the methods, return the context object, and define __enter__ and __exit__ on Context itself.

Describe alternatives you've considered

Fleshing out the documentation — maybe even writing a topic guide for Canvas — would certainly help one grok the naming conventions... Honestly, this would be a good idea in any event, I've just been intimidated by it so far!

Additional context

I see that the current paradigm was put in place in #2029:

To make it clear(er) when an operation is a context producing operation, rather than a simple drawing operation, context-producing operations have been renamed to TitleCase. This also avoids a collision caused by introducing the Canvas.context property; the operation on canvas to produce a new sub-context is now Canvas.Context().

Edit: Current status

We've reached consensus on the shape of the API we're after, described in this comment.

To-do list

• Tighten Canvas backend API and align more with HTML #4057

• Rename DrawingObject to DrawingAction #4084

• Rename Context to State #4114

• Split drawing action methods out into mixin class #4105, for sharing between State and Canvas (and a Path2D analogue?)

• Remove State.canvas backreference, combine drawing actions, move drawing methods #4159

  • Remove State's reference to its parent Canvas, making State objects canvas-agnostic.
  • Canvas gets all the drawing methods (which add to current State), and they're deprecated on State.
  • Unify existing context manager drawing actions with their "standalone" versions

• Add drawing context attributes and save/restore to Canvas #4332

• Canvas docs revamp #4362

• Align Canvas method parameters better with JavaScript #4330

• Turn Canvas transform methods into states #4477

• Add keyword parameters to Canvas.state() #4485

• Canvas: deprecate write_text, add fill_text & stroke_text #4432

• Implement other missing methods / functionality of Context2D, including:

  • Support round_rect() on Canvas #4161
  • Support stand-alone Path objects in Canvas #4163 as an analogue to Path2D
  • Support arc_to on Canvas #4158

[HalfWhitt]

Related:

To avoid the collision, Canvas now has a context property that returns the root context of the canvas. Simple drawing operations have been retained for backwards compatibility, redirecting to the default context; context generating operations have been retained.

The context managers are still present; that is, with canvas.Fill(): is a shortcut to with canvas.context.Fill(). On the one hand, these can save a little typing, but on the other, I feel like they just muddy the waters further. There are many ways to do a thing, and they all have basically the same name...

[corranwebster]

@HalfWhitt So I'm coming to this from trying to implement the Canvas widget for Qt, as a former maintainer of the Kiva 2D drawing API (a Python layer over a bunch of backends: Agg, QPainter, Quartz, Cairo, SVG, etc.), and as a casual user of Toga (I've written an app for my spouse that they use daily). I find the Context, Fill, Stroke, ClosedPath, etc. context managers a bit confusing as to their purpose.

I sort of get what Fill and Stroke are trying to do: set up the state of the context so that you can concentrate on drawing a path, which then gets rendered at the end of the context and the original state restored. But it doesn't seem like it's really adding much over setting them manually in a sub context. And ClosedPath seems to just do a close_path operation, but my initial expectation was that this was how you create a stand-alone path object that could be re-drawn over and over (like Path2D in an HTML Canvas).

In terms of other ways to do things: in Kiva we had the graphics context itself be a Python context manger, so you'd do things like:

with context:
    context.translate(100, 50)
    context.set_line_cap(LINE_CAP_SQUARE)
    context.set_line_join(LINE_JOIN_BEVEL)
   # create path
   ...
   # draw with current line state
   context.stroke()

# original transform, line cap and join restored

This seems similar to what Context.Context does, but I don't know if that fits the way that the Canvas works in Toga. Architecturally Kiva tried to be as thin a veneer as possible over the underlying drawing library, so didn't really have a notion of things like DrawingObjects. But I could see the utility in having something like:

with context.State(
    translate=(100, 50),
    line_cap=LINE_CAP_SQUARE,
    line_join=LINE_JOIN_BEVEL,
) as state:
   # create path
   ...
   # draw
   context.stroke()

# original transform, line cap and join restored

or some variant of that. This is I suspect what you might be getting at with an all-in-one open-like API.

[HalfWhitt]

First of all, disclaimer: while I'm a member of the core team, I only joined less than a year ago, and have only been involved with BeeWare at all for the last couple of years. So I wasn't here for any of the design discussion of Canvas, and only know what I've gleaned from the code itself, reading PRs, and talking to others. Further disclaimer that I'm typing up a lot here — hopefully it'll make sense and I won't refer to too many things erroneously.

As Malcolm said, the idea is to match the HTML5 canvas API as closely as possible. There are some things added for convenience — but from what I can see, there's also a decent bit that's different or missing.

[Disclaimer: I'm sure you personally, corranwebster, know everything I'm about to say about the HTML canvas, but I want to lay this all out as systematically as I can. Also, canvases in general are still pretty new to me.]

First of all, in addition to the unavoidable ambiguity with Python's own "context manager", Toga's idea of a "context" vs HTML's are different. HTML canvas's context is a singleton:

Later calls to this method on the same canvas element, with the same contextType argument, will always return the same drawing context instance as was returned the first time the method was invoked. It is not possible to get a different drawing context object on a given canvas element.

This single context can push and pop its state onto and off of a stack with save() and restore() methods.

In contrast, Toga's Context class is analogous to the state of HTML's context. Rather than having one context with a stack of states, Toga has one Canvas widget with a stack of Contexts. Also, there's no way to save or restore with simple save() or restore() methods; there's only the context manager with context.Context():. It's not an added convenience, it's a replacement. (The Fill(), ClosedPath(), etc. context managers are just a bit of convenient sugar on Context() that do something extra as they enter and/or as they exist.)

Similarly, I think it's nice that Toga's stroke() and fill() methods take an optional color argument, unavailable in HTML/JS. It's nice to be able to specify that as a one-shot rather than having to set it first as a property of the context. However... in Toga you can't set it a property of the context. Things like fill color, stroke color, stroke width, etc. should be saved and restored with the state stack, but there's no way to set them as persistent attributes in Toga.

Now, as for Toga's DrawingObject and Context classes... the idea is that they're persistent objects that, if need be, can be edited later:

Any argument provided to a drawing operation or context object becomes a property of that object. Those properties can be modified after creation, after which you should invoke Canvas.redraw to request a redraw of the canvas.

Drawing operations can also be added to or removed from a context using the list operations append, insert, remove and clear. In this case, Canvas.redraw will be called automatically.

That does seem like potentially a handy addition to me... although personally I suspect alteration of objects (like editing bar height in a graph, as in the documented example) is far more likely to be useful to going back and adding or removing individual operations from a context state. In any event, I think those list-like methods are the primary reason the context-managing context managers (eesh) need to return themselves — so you can access them later. However, the fact that you need to return and assign them, then call their methods, provides a really easy foot-gun:

ctx = canvas.context
[drawing operations using ctx.do_stuff()]
with cts.ClosedPath() as closed:
    # What you need to do:
    [drawing operations using closed.do_stuff()]
    # What you could quite easily keep doing, but these operate outside
    # this subcontext, ignoring any translations, rotations, etc.:
    [drawing operations using ctx.do_stuff()]

I think that extra functionality or convenience is fine (and backwards compatibility with features we already offer is nice), but we should build it on top of something as close to the target API as possible. With that in mind, here's what I'm thinking:

• Canvas itself maintains a stack of what are currently Context objects, but renamed to State (or perhaps ContextState).

• Canvas gets all the various drawing methods (fill(), line_to(), etc.), which pass through to the current state (or are stored associated with the current state — this could be implemented a couple of different ways). It doesn't need add and remove, which collide with Widget methods, and are the original reason Canvas stopped being its own Context... However, it would in this case need clear. I'm not sure that's a problem, though — Canvas is a leaf node anyway, and can't have children. Is there any harm in shadowing methods used for managing its nonexistent children?

• Canvas still stores a record of all operations, and still has the redraw() method to rerun through them.

• Canvas also gains save() and restore() methods, which push and pop states appropriately. save() can double as a context manager to enter and then leave a state. It can also return a reference to that state... which won't normally need to be assigned to anything, but can be if you want to be able to add or remove from it later I guess.

• Other methods like begin_path() and fill() can double as context managers, like their CamelCase versions currently do, that save state, do a convenient beginning and/or ending command, and restore state. It would make sense to expand this to other commands such as rotate() and translate().

  That's what I meant by my initial post; but I like your idea, too, of being able to provide various state modifications to the constructor of the context manager. The two could even coexist, with the former being a shortcut for the latter with various settings. Though adding that functionality to save would be misleading, as it would look like those were the settings you were saving, rather than "jumping into", so I also like your idea of naming it state.

• Canvas states gain the ability to store attributes like fill rule, stroke width, etc. If, say, the user calls fill() without specifying a color, the color to use is deduced from whatever was last set in the current state, or in any parent state.

I suppose it's also worth asking whether it would be worth it to:

• Adopt an external library (like Kiva, for instance) instead of re-implementing our version of an already well-trodden API.
• Build (or adopt) a higher-level API that can be used on top of the low-level Canvas API. At the very least, if we make Canvas more compliant with the standard, we open the possibility of users being able to use it as a backend for other libraries that already know how to output to a canvas.
• Maybe even ditch the entire idea of maintaining a persistent and editable record of all previous states and drawing methods, even after they've been popped? The JavaScript/HTML API doesn't give access to that; it works just fine, and people have still managed to build all manner of higher-level libraries and conveniences on top of it.

[HalfWhitt]

Toga has one Canvas widget with a stack of Contexts.

To clarify: I mean this conceptually. The way it's actually implemented is that the canvas holds a root context; the context then holds a list of drawing objects. Context is a subclass of drawing object, so any of those in the list can be a "subcontext" with its own list of drawing objects. Each one corresponds to saving a state onto the stack, then popping it back off before progressing through the list.

[corranwebster]

I'm a big fan of using Python context managers for managing state in 2D drawing APIs. In Kiva it was transformative when we replaced the save_state/restore_state with a context manager when it came to debugging: before the use of context managers an omitted restore would mean all subsequent drawing was messed up, and finding where you missed the restore could be a huge problem; also if there was an exception raised in your code there's basically no way to recover unless you are finicky about try: ... finally: ... (essentially manually implementing context managers). Even if you catch the exception somewhere, at the point you catch the exception you have no idea how much state you need to unwind to get back to where you were and continue drawing. Using context managers basically removes this whole class of errors.

The Context objects also seem to be playing the role of HTML canvas's Path2D. I haven't tried it, but it seems like you should be able to do some drawing into a Context, and then once it's complete, re-use that context to replicate that over and over (eg. for a plot marker: draw the shape of the marker in a Context, and then for each point in your plot translate to the location of that marker, add the marker Context at that point, something like:

with context.Context() as marker:
    # "plus" shape
    marker.move_to(0, 10)
    marker.line_to(0, -10)
    marker.move_to(10, 0)
    marker.line_to(-10, 0)

for x, y in points:
    with context.Stroke() as stroke:
        stroke.translate(x, y)
        stroke.append(marker)

There's also some oddness about nesting of Fill and Stroke, eg. It looks like:

with context.Stroke(color=rgb(255, 0, 0)) as outer:
     # do some drawing
     ...
     with outer.Stroke(line_width=10) as inner:
         # color is black, not red, here
         ...

So in terms of what you're suggesting:

• yes, merging the management of stroke, fill, and transform states into a state context object makes sense.
• I'm not sure Canvas needs any drawing methods: with an HTML canvas you have to ask for a context, so it's not a foreign concept. But I can see the convenience of having it exposed.
• I'd strongly advise against exposing public save/restore methods for the reasons above: it's a huge foot-gun. All save/restore should be via a Python context manager, even if it deviates from the HTML canvas API.
• the idea of having rotate, fill etc. doubling as Python context managers is interesting and potentially powerful.
• and yes, to follow the HTML canvas API, you'd expect to have things like context.fill_color = 'red' set the fill color of the current state to red and then subsequent fill() calls would use that color.

Additionally, it would be nice if you could take a set of drawing commands for the HTML canvas, apply a fairly consistent set of rules to transform them (eg. camelCase -> snake_case, save/restore -> context manager) and have that work, and then have added convenience functionality on top to make things more Pythonic. Part of that would be adding a "path" object that is independent of a Context (ie. that can be re-used across different Canvases), even if it's just a Context-like thing under the covers.

Addressing the last three points:

• My gut feeling is that Toga should be handling drawing itself via native libraries, rather than doing something like rendering to a bitmap using a Python wrapper around Agg or Skia or similar and then blitting that to a widget. While there are some advantages to that approach, there are issues around packaging, etc. that are less than ideal compared to using what comes with the system. In particular native font handling and text drawing will always be better than a third party python library. If someone really wants that it's pretty easy to do (eg. draw into a buffer that PIL/Pillow can access, and then use an ImageView - I've done this myself with Toga), so it's not precluded.
• There's definitely room for a higher-level API on top of the low level drawing: once you get drawing sorted it's not long before you start wanting to interact with the things that you've drawn. See for example Qt's QPainter vs. QGraphicsView. It doesn't have to be part of the core, though, as long as the core exposes enough interactivity and a rich enough drawing API.
• The persistent record of DrawingObjects makes a reasonable amount of sense: from the Canvas's perspective it's going to need to redraw things from time-to-time and there's a choice of either having user code that gets called on each refresh (eg. the user has to supply a draw callback, or subclass Canvas and override it's draw method), or you provide methods for the user to draw and build a log of operations which you can play back. Canvas is doing the latter, and it fits the HTML canvas's model where as a user you can draw once and it persists. And even in the first case, if your underlying drawing library is lacking in features then you find that you need to implement something like this anyway for dealing with re-usable paths. The one concern is memory usage for very complex drawings (eg. plots with many points: in the first approach once you've drawn a marker you're done with it and can release the memory; in the second approach you need to have an object for every marker which persists).

[HalfWhitt]

Additionally, it would be nice if you could take a set of drawing commands for the HTML canvas, apply a fairly consistent set of rules to transform them (eg. camelCase -> snake_case, save/restore -> context manager) and have that work, and then have added convenience functionality on top to make things more Pythonic.

I'd strongly advise against exposing public save/restore methods for the reasons above: it's a huge foot-gun. All save/restore should be via a Python context manager, even if it deviates from the HTML canvas API.

Honestly that's what I had in mind — support the "normal" syntax so code can be copied more or less verbatim from a canvas tutorial elsewhere, but then add a context manager to be more ergonomic. But as long as it is, like you say, a consistent translation, then maybe it is indeed worth not having "standalone" save and restore methods.

I'm not sure Canvas needs any drawing methods: with an HTML canvas you have to ask for a context, so it's not a foreign concept. But I can see the convenience of having it exposed.

I guess I had two things in mind:

• For HTML's canvas, it needs a get_context() because there are other contexts available, for 3D rendering and for replacing the content with a bitmap. I doubt we'll ever be adding other contexts... but then again, who knows I guess.
• Some degree of backwards compatibility, because in current Toga, Canvas.context isn't analogous to the overall context; it's specifically the "original" state of the context, without any more pushed onto it. But maybe I'm being paranoid. I'm pretty sure any path forward is going to involve plenty of deprecations and shims, no matter how we do it.

Being able to call methods directly on Canvas seems like it would be nice, as long as there's no compelling reason not to allow it, but I'm not married to the idea; calling them on Canvas.context would be fine too as far as I'm concerned.

There's also some oddness about nesting of Fill and Stroke, eg. It looks like:

with context.Stroke(color=rgb(255, 0, 0)) as outer:
     # do some drawing
     ...
     with outer.Stroke(line_width=10) as inner:
         # color is black, not red, here

Yeah, at present, the contexts / states don't really save much.

The Context objects also seem to be playing the role of HTML canvas's Path2D. I haven't tried it, but it seems like you should be able to do some drawing into a Context, and then once it's complete, re-use that context to replicate that over and over [...]

Part of [establishing a consistent translation from HTML canvas to Toga] would be adding a "path" object that is independent of a Context (ie. that can be re-used across different Canvases), even if it's just a Context-like thing under the covers.

Interesting, I'll have to give this a ponder...

• My gut feeling is that Toga should be handling drawing itself via native libraries, rather than doing something like rendering to a bitmap using a Python wrapper around Agg or Skia or similar and then blitting that to a widget. While there are some advantages to that approach, there are issues around packaging, etc. that are less than ideal compared to using what comes with the system.

Okay yeah, that makes sense. Was just thinking out loud, really... It's a little frustrating sometimes how often the ideal of open source projects reusing modular bits of each other isn't as practical as one would like. Sometimes you just gotta reinvent a (slightly different) wheel.

• There's definitely room for a higher-level API on top of the low level drawing: once you get drawing sorted it's not long before you start wanting to interact with the things that you've drawn. See for example Qt's QPainter vs. QGraphicsView. It doesn't have to be part of the core, though, as long as the core exposes enough interactivity and a rich enough drawing API.

That's what I was thinking... As long as it's "compliant" enough, someone might even be able to get an existing higher-level library to run on it instead of the HTML canvas or whatever else it was previously rendering to. Though that might be me being idealistic again... 🤣

• The persistent record of DrawingObjects makes a reasonable amount of sense: from the Canvas's perspective it's going to need to redraw things from time-to-time and there's a choice of either having user code that gets called on each refresh (eg. the user has to supply a draw callback, or subclass Canvas and override it's draw method), or you provide methods for the user to draw and build a log of operations which you can play back. Canvas is doing the latter, and it fits the HTML canvas's model where as a user you can draw once and it persists.

I think I understand what you're saying here... by "it's going to need to redraw things from time-to-time", do you mean due to OS / windowing interactions? As in, in order to maintain what the user has drawn once, the widget may have to redraw it multiple times?

[corranwebster]

• The persistent record of DrawingObjects makes a reasonable amount of sense: from the Canvas's perspective it's going to need to redraw things from time-to-time and there's a choice of either having user code that gets called on each refresh (eg. the user has to supply a draw callback, or subclass Canvas and override it's draw method), or you provide methods for the user to draw and build a log of operations which you can play back. Canvas is doing the latter, and it fits the HTML canvas's model where as a user you can draw once and it persists.

I think I understand what you're saying here... by "it's going to need to redraw things from time-to-time", do you mean due to OS / windowing interactions? As in, in order to maintain what the user has drawn once, the widget may have to redraw it multiple times?

Precisely. In particular, when a window is resized or the Canvas otherwise changes size via user interactions, then you need to redraw and you can't just rely on offscreen buffers of the pixels (there are other cases where this can happen, such as moving a window between screens of different resolutions - in particular HiDPI/Retina to/from normal pixel density - this one in particular has bitten me). If a user draws to an HTML canvas and something causes the canvas to resize, the user doesn't need to re-draw it unless they want to (via a callback on the element changing size). Toga behaves the same way, at least from the user's point of view.

[HalfWhitt]

Okay, that makes sense. I hadn't thought about that aspect at all. Then yes, whether we intend them to be "publicly" editable or not, continuing to hold onto a record of all operations and state-changes makes sense (at least until clear() is called). And as long as they're there, they may as well be accessible for shenanigans.

[corranwebster]

• Some degree of backwards compatibility, because in current Toga, Canvas.context isn't analogous to the overall context; it's specifically the "original" state of the context, without any more pushed onto it. But maybe I'm being paranoid. I'm pretty sure any path forward is going to involve plenty of deprecations and shims, no matter how we do it.

There's one ray of light here, and that's that in all of this discussion, none of it requires changes to the underlying implementation objects: they're just handling low-level commands, so it should be possible to leave the current Context system in place and build out a separate system to explore possibilities or permit backwards compatibility.

[freakboy3742]

Surfacing from my holiday one day of trying to stay on top of things...

As Malcolm said, the idea is to match the HTML5 canvas API as closely as possible. There are some things added for convenience — but from what I can see, there's also a decent bit that's different or missing.

To be clear: a lot of the "missing" pieces are just as likely to be oversight as intention. When there's a difference, it should only be in the form of "Python provides a syntax that gives a more idiomatic way to express this", rather than a fundamentally different worldview. The mapping from Python to HTML5 Canvas should be entirely mechanical - but I won't stake my life that we got that bit right.

In contrast, Toga's Context class is analogous to the state of HTML's context. Rather than having one context with a stack of states, Toga has one Canvas widget with a stack of Contexts. Also, there's no way to save or restore with simple save() or restore() methods; there's only the context manager with context.Context():. It's not an added convenience, it's a replacement.

Yes - but naming confusion notwithstanding, they should be functionally equivalent.

However, the fact that you need to return and assign them, then call their methods, provides a really easy foot-gun:

Agreed this is a potential foot-gun.

There's definitely room for a higher-level API on top of the low level drawing: once you get drawing sorted it's not long before you start wanting to interact with the things that you've drawn. See for example Qt's QPainter vs. QGraphicsView. It doesn't have to be part of the core, though, as long as the core exposes enough interactivity and a rich enough drawing API.

That's what I was thinking... As long as it's "compliant" enough, someone might even be able to get an existing higher-level library to run on it instead of the HTML canvas or whatever else it was previously rendering to. Though that might be me being idealistic again... 🤣

This feels a little distance from a concrete proposal; but conceptually, I can see how it might make sense to have a very low level "direct mapping" of the HTML Canvas API, with a richer layer of context manager handling on top to manage the analog of HTML5 Canvas state.

While I'd prefer a backwards compatible solution, I'm willing to be convinced an entirely new API for Canvas is needed; and if we can learn from the lessons of other 2D canvas APIs, all the better. In particular, the way Toga uses context managers for Fill and Stroke is definitely on the experimental end of things; if there's a better way to formulate those that is based on more "local" properties on a stack of contexts/states, I'm open to suggestions.

[HalfWhitt]

To be clear: a lot of the "missing" pieces are just as likely to be oversight as intention. When there's a difference, it should only be in the form of "Python provides a syntax that gives a more idiomatic way to express this", rather than a fundamentally different worldview. The mapping from Python to HTML5 Canvas should be entirely mechanical - but I won't stake my life that we got that bit right.

It generally is; I'd say the main things missing are the idea of stateful fill/stroke style/color attributes that are persisted, and saved/restored with the context state.

There's the recently-discovered issue that the macOS native canvas, at least, clears the current path once it's stroked or filled; much like Python.NET holding onto image files in #3730, there's always the question of how much logic to pull up into core vs. handling individual platforms' quirks in their respective backend...

In contrast, Toga's Context class is analogous to the state of HTML's context.

Yes - but naming confusion notwithstanding, they should be functionally equivalent.

Fair, but as someone coming in for the first time, it's really confusing. I'd never used the HTML canvas or any similar system before, and Toga's Canvas docs kind of say "Here's an intro, now go read the MDN canvas docs and translate that to Python." Learning both at the same time is pretty hard when the same name is used in two simliar-but-not-identical ways like that.

This feels a little distance from a concrete proposal; but conceptually, I can see how it might make sense to have a very low level "direct mapping" of the HTML Canvas API, with a richer layer of context manager handling on top to manage the analog of HTML5 Canvas state.

I was thinking more in terms of having the mostly-direct canvas mapping, with context managers (mostly like we have now); but then someone could potentially build (or port) something more sophisticated on top of that, for things like, say, giving on_press handlers to individual shapes, or having shortcuts for drawing animations. There are a variety of JavaScript libraries for handling higher level and/or interactive things like that on HTML canvases. That definitely isn't something I propose to start now, though, or even as part of Toga itself. Just an idea of what we might enable.

But if I'm understanding you correctly... are you suggesting making the backend focus on one-shot commands like "go here, draw this in this color", while handling the state stack and persistent context attributes all in core via context managers — and then using our own record of state to decide which primitive methods to call on the backend? If so, I dunno. It would certainly help with insuring consistency, though it would almost certainly be slower than letting the OS handle state... assuming the lowest common denominator of API parity between backends is close to all of the HTML API we're matching. Which it seems like it is, but I haven't looked into the individual backends much yet.

While I'd prefer a backwards compatible solution, I'm willing to be convinced an entirely new API for Canvas is needed; and if we can learn from the lessons of other 2D canvas APIs, all the better. In particular, the way Toga uses context managers for Fill and Stroke is definitely on the experimental end of things; if there's a better way to formulate those that is based on more "local" properties on a stack of contexts/states, I'm open to suggestions.

I definitely don't think anything needs to be "entirely new" — certainly not from the user's perspective, at the very least. I mostly want to rearrange/rename some things, and add some missing attributes.

I think we've reached the "picture is worth a thousand words" point... I'll see about putting together a proof of concept, so there's something concrete to discuss / critique.

[corranwebster]

It might be helpful to document the differences between the HTML Canvas and the current state of the Toga Canvas/Context:

HTML	Toga	Comments
arc(x, y, r, start, end, counterclockwise)	arc(x, y, r, start, end, counterclockwise)
arcTo(x1, y1, x2, y2, r)		Useful for drawing rounded shapes.
beginPath()	begin_path()
bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y)	bezier_curve_to(cp1x, cp1y, cp2x, cp2y, x, y)
clearRect()		Makes rectangle transparent. Not sure can do this in all backends.
clip()		Toga doesn't have clip regions, probably should.
closePath()	close_path()
createConicGradient(...)		Toga only supports solid coloured strokes/fills
createImageData(...)		Create an empty raw pixel buffer. Essentially a PIL Image equivalent, but in principle could be any Python buffer object like a NumPy array.
createLinearGradient(...)		Toga only supports solid coloured strokes/fills
createPattern(...)		Toga only supports solid coloured strokes/fills
createRadialGradient(...)		Toga only supports solid coloured strokes/fills
drawFocusIfNeeded(...)		Allows drawing a special path for focus indicator. Not sure all backends can support this.
drawImage(...)		Should add to Toga. See #955
ellipse(x, y, rx, ry, rot, start, end, counterclockwise)	ellipse(x, y, rx, ry, rot, start, end, counterclockwise)
fill(path, rule)	fill(color, rule) or with Fill(...)	Several variants, but no independent path objects in Toga.
fillRect(x, y, width, height)		Can do something similar with rect() followed by fill(), but subtle differences in current path behaviour.
fillText(...)	write_text(...)	Not exactly the same, write_text() also handles stroke.
getContextAttributes()		Effectively returns a dict of the current state. Not sure Toga needs this.
getImageData()		Get underlying pixel data as a buffer. Not sure all backends can support this.
getLineDash()		No direct way to inspect state in Toga other than via DrawingObjects. Probably should be a property if implemented in Python
getTransform()		No direct way to inspect state in Toga other than via DrawingObjects. Probably should be a property if implemented in Python
isContextLost()		Not relevant for Toga/Python
isPointInPath(...)		Potentially useful, but not a high priority. Not sure about backend support.
isPointInStroke(...)		Potentially useful, but not a high priority. Not sure about backend support.
lineTo(x, y)	line_to(x, y)
measureText(text)	measure_text(text, font, ...)	Toga has no concept of "current font" or other text state.
moveTo(x, y)	move_to(x, y)
putImageData(...)		Renders raw pixel data, could be useful to have a version which accepts any Python object that supports the buffer protocol (eg. bytes, bytearray, Pillow Image, NumPy Arrays, etc.)
quadraticCurveTo(cpx, cpy, x, y)	quadratic_curve_to(cpx, cpy, x, y)
rect(x, y, w, h)	rect(x, y, w, h)
reset()	clear()	Slightly different semantics, but same effect.
resetTransform()	reset_transform()	In code which does proper save/restore of state, this is almost never needed.
restore()	Context managers, sort of...	Don't expose directly.
rotate(angle)	rotate(angle)
roundRect(...)		Can be built manually, could be useful to have as a primitive - round rectangles are everywhere.
save()	Context managers, sort of...	Don't expose directly.
scale(x, y)	scale(x, y)
setLineDash()	Stroke() context manager	Probably should be a property if implemented in Python
getTransform()		No direct way to set an affine transform in Toga. Probably should be a property if implemented in Python
stroke(path)	stroke(...) or with Stroke(...)	Have to pass line properties to stroke in Toga, but no independent path objects in Toga.
strokeRect(x, y, width, height)		Can do something similar with rect() followed by fill(), but subtle differences in current path behaviour.
strokeText(...)	write_text(...)	Not exactly the same, write_text() also handles stroke.
transform(a, b, c, d, e, f)		Toga doesn't support direct affine transforms, need to build from rotate, scale, translate.
translate(x, y)	translate(x, y)
	__len__()	HTML Canvas doesn't expose internals of drawing representation.
	__getitem__(i)	HTML Canvas doesn't expose internals of drawing representation.
	insert(i, obj)	HTML Canvas doesn't expose internals of drawing representation.
	append(obj)	HTML Canvas doesn't expose internals of drawing representation.
	remove(obj)	HTML Canvas doesn't expose internals of drawing representation.
context attributes (fillColor, lineWidth, etc)	passed as arguments (color, line_width, etc)
Path2D	Context.Context	Not quite a direct analog, but can do similar things with them. Path2D can exist without an underlying context.
OffscreenCanvasRenderingContext2D		Being able to do offscreen drawing is nice, might be able to abuse Context to do something like this currenlty.
CanvasGradient		Useful for shadow effects and similar.
CanvasPattern
TextMetrics		This is more the realm of font support in Toga.
	DrawingObject	HTML Canvas doesn't expose internals of drawing representation.

To get better alignment between the two APIs, there is some low-hanging fruit:

• make the text drawing routines closer to the HTML ones (ie. fill_text() and stroke_text() instead of write_text())
• add support for things that aren't currently implemented (eg. draw_image(), round_rect(), fill_rect(), patterns, gradients, even put_image_data)
  Doing these is largely a matter of adding a new DrawingObject type for the operation and then doing any implementation needed in the backend.

Additionally, writing this out has made me realise that the implicit Toga backend implementation API is also almost the HTML Canvas API, so it may make sense to align that as well as an implementation detail. This might help support use-cases like the plotting where you want to use the backend implementation but not the full Canvas API.

Where design thought is needed is how to handle things like supporting:

ctx.lineWidth = 2
ctx.moveTo(20, 20)
ctx.lineTo(60, 20)
ctx.stroke()
                               
ctx.moveTo(60, 20)
ctx.lineTo(100, 20)
ctx.strokeStyle = "red"
ctx.stroke()

Should ctx.lineWidth = 2 generate a "change state" DrawingObject. Can we query the properties? I think it should be possible to do that while building the context, but are they also properties of DrawingObjects, for example? Or do we not permit those, and instead have an API like:

with ctx.State(line_width=2):
    ctx.move_to(20, 20)
    ctx.line_to(60, 20)
    ctx.stroke()

    ctx.move_to(60, 20)
    ctx.line_to(100, 20)
    with ctx.State(stroke_color='red'):
        ctx.stroke()

ie. all state changes happen as part of a context manager. That's probably a fairly teachable API, and one which is less susceptible to weird interactions at a distance (eg. calling a function to draw part of the image, and forgetting to restore the state before returning would be impossible). If we do this, then the rotate(), scale(), translate() functions should also possibly be context managers, since they change the state.

There is also the concept of a device-independent Path object. These are really useful for things like markers in data visualisations. In principle this is very like a Context, but one which only takes geometric DrawingObjects, but not Fill or Stroke objects or things which change the state. All the backends have a native Path object, however, so it could make sense to have the ability to cache to an opaque native path for efficiency.

Finally, I think it's OK for Toga to provide access to the internals as discussed above. From a teaching the API perspective it's easy enough to say "you can use the HTML canvas API with this translation guide, but also after you're done, you can do this as well".

[HalfWhitt]

Thank you for the comprehensive write-up! I was thinking of my decision to forge ahead without one as pragmatic, but in retrospect it was probably just foolhardy and lazy.

Thinking of implementing draw_image() was what started me down this rabbit hole in the first place... 😂

Path2D	Context.Context	Not quite a direct analog, but can do similar things with them. Path2D can exist without an underlying context.

Context objects can already exist independently too, actually. You can create one on its own, and manually add it to the list of drawing instructions, potentially even in more than one place. Although things would certainly go haywire if you added it as a descendant of itself! Maybe there should be a check for that, come to think of it.

Should ctx.lineWidth = 2 generate a "change state" DrawingObject. Can we query the properties? I think it should be possible to do that while building the context, but are they also properties of DrawingObjects, for example?

I was thinking about this... I think if we allow direct setting of properties, then yes, they would have to be added as DrawingObjects in their own right. I don't think attaching these as properties of DrawingObjects would make sense; but I believe the current / last-set state should be queryable from the canvas, or from its context if current Contexts are renamed as States of it. Querying the properties of an individual State might be possible, but it would raise questions. Like what if, as I mentioned above, you add the same Context/State at two different places in the history? If you then ask it what its stroke width is, there could be two different valid answers.

Or do we not permit those, and instead have an API like:

with ctx.State(line_width=2):
    ctx.move_to(20, 20)
    ctx.line_to(60, 20)
    ctx.stroke()

    ctx.move_to(60, 20)
    ctx.line_to(100, 20)
    with ctx.State(stroke_color='red'):
        ctx.stroke()

ie. all state changes happen as part of a context manager. That's probably a fairly teachable API, and one which is less susceptible to weird interactions at a distance (eg. calling a function to draw part of the image, and forgetting to restore the state before returning would be impossible).

Now this, though... that is intriguing. As far as I can tell, that should still map consistently to the "normal" API, while being safer. And, in my opinion, more elegantly expressive.

If we do this, then the rotate(), scale(), translate() functions should also possibly be context managers, since they change the state.

So, I'm seeing two possible spellings, and I think both could happily coexist. One would be a full-fledged state() context manager, that could set anything and everything...

Canvas.context.state(
	# Set attributes on the new state. In JS these would translate directly to saving
	# state, then setting the appopriate property.
	fill_color,
	fill_style,
	line_dash,
	line_join,
	line_width,
	...

	# Perhaps these could be set as well, but I'm not sure how you could specify in what
	# order they should be applied, if multiple are provided...
	rotate,
	transform,
	translate,

	# These could potentially be shortcuts that perform the appropriate action at the
	# end, while optionally setting relevant properties — but again, how to specify
	# order.
	fill=(color, style...),
	stroke=(dash, join, width...),
)

But commands like fill, stroke, rotate, transform, and translate could also be simpler context managers in their own right, e.g.:

with ctx.translate(50, 50):
	with ctx.fill(color="green"):
		...

Obviously that could get real nested real fast. But it would be nice and succinct for simple operations, and the "full" state() version could be used for more complex setups.

As for determining the order in which to apply transformations, fills, and strokes, there is one way that would be dead simple to implement and intuitive to use: toss them all into **kwargs, and execute them in the order received. The only downside would be the awkwardness of documenting it.