Re: Emacs canvas support

[Po Lu]

Eli Zaretskii <address@hidden> 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.

(setq canvas (make-canvas 1800 1800))

(erase-buffer)
(insert (propertize " " 'display canvas))

(canvas-draw-image canvas (create-image "splash.png")
                   0 0 180 180 (selected-frame) 1.0)
(canvas-ellipse canvas (/ 180 2) (/ 180 2) 130 130 "green")
(canvas-rectangle canvas 0 0 180 180 "red" t)
(canvas-rectangle canvas 20 20 40 100 "white" t 0.5)
(canvas-draw-string canvas 0 0 "Hello, Emacs" "red" 1.0 "monospace" 50)
(canvas-draw-string canvas 60 60 "Hello, Emacs" "white" 1.0 '("monospace" t t) 
50)
(let ((image (create-image "splash.png")))
  (canvas-draw-image canvas image 700 20))
(setq track-mouse t)
(defun mouse-movement-canvas-4-paint ()
  "The function to be called when the mouse is moved."
  (interactive "")
  (track-mouse
    (let ((event))
      (while (mouse-movement-p (setq event (read-event)))
        (let* ((position (event-start event))
               (x (car (posn-x-y position)))
               (y (cdr (posn-x-y position))))
          (message (format "%d %d" x y))
          (canvas-filled-arc canvas x y 100.0 (* 45.0 (/ pi 180.0)) pi 
"blue"))))))
(defun mouse-movement-canvas-paint ()
  "The function to be called when the mouse is moved."
  (interactive "")
  (track-mouse
    (let ((event))
      (while (mouse-movement-p (setq event (read-event)))
        (let* ((position (event-start event))
               (x (car (posn-x-y position)))
               (y (cdr (posn-x-y position))))
          (message (format "%d %d" x y))
          (canvas-ellipse canvas x y 10 10 "blue"))))))
(defun mouse-movement-3-canvas-paint ()
  "The function to be called when the mouse is moved."
  (interactive "")
  (track-mouse
    (let ((event))
      (while (mouse-movement-p (setq event (read-event)))
        (let* ((position (event-start event))
               (x (car (posn-x-y position)))
               (y (cdr (posn-x-y position))))
          (message (format "%d %d" x y))
          (canvas-rectangle canvas x y 80 80 "white"))))))
(defun mouse-movement-2-canvas-paint ()
  "The function to be called when the mouse is moved."
  (interactive "")
  (track-mouse
    (let ((event))
      (while (mouse-movement-p (setq event (read-event)))
        (let* ((position (event-start event))
               (x (car (posn-x-y position)))
               (y (cdr (posn-x-y position))))
          (message (format "%d %d" x y))
          (canvas-draw-string canvas x y "Welcome to Emacs" nil nil nil 22))))))
(local-set-key [down-mouse-1] #'mouse-movement-canvas-paint)
(local-set-key [down-mouse-3] #'mouse-movement-2-canvas-paint)
(local-set-key [down-mouse-2] #'mouse-movement-3-canvas-paint)
(local-set-key [C-down-mouse-1] #'mouse-movement-canvas-4-paint)
(canvas-measure-string canvas "hi")
(canvas-draw-string canvas 0 0 "Hi" "yellow")
(setq canvas2 (canvas-from-image (create-image "splash.png")))
(canvas-rectangle canvas2 0 0 40 20 "orange")
(canvas-rectangle canvas2 20 0 40 20 "black")

(canvas-rounded-rectangle canvas 20 0 40 20 10.0 "red" nil)
(canvas-draw-canvas canvas canvas2 500 500)