Chapter 5

Drawing Toolbox Overview

Drawing in MrEd requires a device context (DC), which is an instance of the dc<%> interface. For example, the get-dc method of a canvas returns a dc<%> instance for drawing into the canvas window. Other kinds of DCs draw to different kinds of devices:

• bitmap-dc% -- a bitmap DC draws to an offscreen bitmap.

• post-script-dc% -- a PostScript DC records drawing commands to a PostScript file.

• printer-dc% -- a printer DC draws to a platform-specific printer device (Windows, Mac OS).

Tools that are used for drawing include the following: pen% objects for drawing lines and shape outlines, brush% objects for filling shapes, and bitmap% objects for storing bitmaps.

The following example creates a frame with a drawing canvas, and then draws a round, blue face with square, yellow eyes and a smiling, red mouth:

;; Make a 300 × 300 frame
(define frame (instantiate frame% ("Drawing Example") (width 300) (height 300)))
;; Make the drawing area
(define canvas (instantiate canvas% (frame)))
;; Get the canvas's drawing context
(define dc (send canvas get-dc))

;; Make some pens and brushes
(define no-pen (instantiate pen% ("BLACK" 1 'transparent)))
(define no-brush (instantiate brush% ("BLACK" 'transparent)))
(define blue-brush (instantiate brush% ("BLUE" 'solid)))
(define yellow-brush (instantiate brush% ("YELLOW" 'solid)))
(define red-pen (instantiate pen% ("RED" 2 'solid)))

;; Define a procedure to draw a face
(define (draw-face dc) 
  (send dc set-pen no-pen) 
  (send dc set-brush blue-brush) 
  (send dc draw-ellipse 50 50 200 200) 

  (send dc set-brush yellow-brush) 
  (send dc draw-rectangle 100 100 10 10) 
  (send dc draw-rectangle 200 100 10 10) 

  (send dc set-brush no-brush) 
  (send dc set-pen red-pen) 
  (let ([pi (atan 0 -1)]) 
    (send dc draw-arc 75 75 150 150 (* 5/4 pi) (* 7/4 pi)))

;; Show the frame
(send frame show #t) 
;; Wait a second to let the window get ready
(sleep/yield 1) 
;; Draw the face
(draw-face dc)

The sleep/yield call is necessary under X because drawing to the canvas has no effect when the canvas is not shown. Although the (send frame show #t) expression queues a show request for the frame, the actual display of the frame and its canvas requires handling several events. The sleep/yield procedure pauses for a specified number of seconds, handling events while it pauses.

One second is plenty of time for the frame to show itself, but a better solution is to create a canvas with a paint callback function (or overriding on-paint). Using a paint callback function is better for all platforms; when the canvas in the above example is resized or temporarily covered by another window, the face disappears. To ensure that the face is redrawn whenever the canvas itself is repainted, we provide a paint callback when creating the canvas:

;; Make a 300 × 300 frame
(define frame (instantiate frame% ("Drawing Example") (width 300) (height 300)))

;; Make the drawing area with a paint callback
(define canvas (instantiate canvas% (frame) 
                            (paint-callback (lambda (canvas dc) (draw-face dc)))))

;; ... pens, brushes, and draw-face are the same as above ...

;; Show the frame
(send frame show #t)

Suppose that draw-face creates a particularly complex face that takes a long time to draw. We might want to draw the face once into an offscreen bitmap, and then have the paint callback copy the cached bitmap image onto the canvas whenever the canvas is updated. To draw into a bitmap, we first create a bitmap% object, and then we create a bitmap-dc% to direct drawing commands into the bitmap:

;; ... pens, brushes, and draw-face are the same as above ...
 
;; Create a 300 × 300 bitmap
(define face-bitmap (instantiate bitmap% (300 300)))
;; Create a drawing context for the bitmap
(define bm-dc (instantiate bitmap-dc% (face-bitmap))) 
;; A new bitmap's initial content is undefined, so clear it before drawing
(send bm-dc clear) 
 
;; Draw the face into the bitmap
(draw-face bm-dc) 
 
;; Make a 300 × 300 frame
(define frame (instantiate frame% ("Drawing Example") (width 300) (height 300)))

;; Make the drawing area with a paint callback that copies the bitmap
(define canvas (instantiate canvas% (frame) 
                            (paint-callback (lambda (canvas dc)
                                                (send dc draw-bitmap face-bitmap 0 0)))))
 
;; Show the frame
(send frame show #t)

For all types of DCs, the drawing origin is the top-left corner of the DC. When drawing to a window or bitmap, DC units initially correspond to pixels, but the set-scale method changes the scale. When drawing to a PostScript or printer device, DC units initially correspond to points (1/72 of an inch).

Drawing effects are not completely portable across platforms or across types of DC. The drawing toolbox provides tools to draw images precisely and portably, but also provides convenience tools for occasions when precision or portability is not necessary. For example, drawing with a pen of width 0 or 1 produces reliable results for all platforms and unscaled DCs, but a pen width of 2 or drawing to a scaled DC looks slightly different depending on the platform and destination.