beeware / beeware/toga

Consolidate Canvas methods / sync API more closely to HTML5

Open
#3,994 45 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.