Consolidate Canvas methods / sync API more closely to HTML5
- Dominant language
- Python
- Stars
- 5.4k
- Forks
- 827
- Avg merge
- 15h 39m
- Merged PRs (30d)
- 40
Description
### 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](https://github.com/beeware/toga/issues/3994#issuecomment-3695300858).
#### To-do list
- [x] #4057
- [x] #4084
- [x] #4114
- [x] #4105, for sharing between `State` and `Canvas` (and a `Path2D` analogue?)
- [x] #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
- [x] #4332
- [x] #4362
- [x] #4330
- [x] #4477
- [ ] #4485
- [ ] #4432
- [ ] Implement other missing methods / functionality of Context2D, including:
- [x] #4161
- [ ] #4163 as an analogue to Path2D
- [ ] #4158
Contributor guide
Research direction
Start with the consensus API shape in the linked comment, then review the remaining unchecked work in #4485 and #4432 and the Context2D/Path2D items. Compare Canvas, Context, and State behavior against the completed checklist; done when the remaining methods and functionality are implemented and the API consolidation is complete.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- computer-graphics, desktop
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100