Eli Zaretskii <eliz@gnu.org> writes:

> I've read the code and the docs, but I don't think I have a clear idea
> of what "canvases" are and what would be their intended usage.
> Perhaps consider starting the documentation with some introductory
> comments and even a small tutorial.

A canvas is an object that contains memory that can be painted to, and
then displayed by setting it as the `display' text property.

> It sounds like you are talking about a way to create images
> dynamically, but then I don't understand why we need canvas-from-image,
> for example.

It's not really a way to create images dynamically, but rather paint to
a section of the screen.  `canvas-from-image' is just a convenience
function that produces a paintable canvas from a static image.

> Also, is there support for clicking the mouse on a canvas?  I don't
> see it.

You can bind mouse events as usual.

> Well, that'd be my main comments.  I don't quite understand the parts
> of the display code you use for this, they seem like a copy/paste from

Correct, glyph production and iterator code code was mostly copied from
the xwidgets code, since I was somewhat in a rush.  Thanks for the
feedback.

> other objects, sometimes with comments that weren't updated and still
> reference images instead of canvases.

I'll fix that promptly.

> If the drawing on the canvas is  supposed to be modified by Lisp code,
> then we'd need a much more elaborate machinery than just one flag to
> decide when a canvas needs to be redrawn.

Agreed, that is something I've been trying to figure out for some time
now.  Right now, I just do my best to figure out if the canvas has not
touched anything important, and if it has, it just garbages each frame
and calls redisplay.

Attached is some sample code that should hopefully demonstrate exactly
what they are capable of.