1.2 Drawing

Drawing in Racket 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:

Tools that are used for drawing include the following: pen% objects for drawing lines and shape outlines, brush% objects for filling shapes, bitmap% objects for storing bitmaps, and dc-path% objects for describing paths to draw and fill.

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 x 300 frame
  (define frame (new frame% [label "Drawing Example"]
                            [width 300]
                            [height 300]))
  ; Make the drawing area
  (define canvas (new canvas% [parent frame]))
  ; Get the canvas's drawing context
  (define dc (send canvas get-dc))
  ; Make some pens and brushes
  (define no-pen (make-object pen% "BLACK" 1 'transparent))
  (define no-brush (make-object brush% "BLACK" 'transparent))
  (define blue-brush (make-object brush% "BLUE" 'solid))
  (define yellow-brush (make-object brush% "YELLOW" 'solid))
  (define red-pen (make-object 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 x 300 frame
  (define frame (new frame% [label "Drawing Example"]
                            [width 300]
                            [height 300]))
  ; Make the drawing area with a paint callback
  (define canvas
    (new canvas% [parent frame]
                  (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 x 300 bitmap
  (define face-bitmap (make-object bitmap% 300 300))
  ; Create a drawing context for the bitmap
  (define bm-dc (make-object bitmap-dc% face-bitmap))
  ; A bitmap's initial content is undefined; clear it before drawing
  (send bm-dc clear)
  ; Draw the face into the bitmap
  (draw-face bm-dc)
  ; Make a 300 x 300 frame
  (define frame (new frame% [label "Drawing Example"]
                            [width 300]
                            [height 300]))
  ; Make a drawing area whose paint callback copies the bitmap
  (define canvas
    (new canvas% [parent frame]
                  (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).

More complex shapes are typically best implemented with paths. The following example uses paths to draw the Racket logo. It also enables smoothing, so that the logo’s curves are anti-aliased when smoothing is available. (Smoothing is always available under Mac OS X, smoothing is available under Windows XP or when "gdiplus.dll" is installed, and smoothing is available under X when Cairo is installed before GRacket is compiled.)

  (require mzlib/math) ; for pi
  ; Construct paths for a 630 x 630 logo
  (define left-lambda-path ; left side of the lambda
    (let ([p (new dc-path%)])
      (send p move-to 153 44)
      (send p line-to 161.5 60)
      (send p curve-to 202.5 49 230 42 245 61)
      (send p curve-to 280.06 105.41 287.5 141 296.5 186)
      (send p curve-to 301.12 209.08 299.11 223.38 293.96 244)
      (send p curve-to 281.34 294.54 259.18 331.61 233.5 375)
      (send p curve-to 198.21 434.63 164.68 505.6 125.5 564)
      (send p line-to 135 572)
  (define left-logo-path ; left side of the lambda and circle
    (let ([p (new dc-path%)])
      (send p append left-lambda-path)
      (send p arc 0 0 630 630 (* 47/72 2 pi) (* 121/360 2 pi) #f)
  (define bottom-lambda-path
    (let ([p (new dc-path%)])
      (send p move-to 135 572)
      (send p line-to 188.5 564)
      (send p curve-to 208.5 517 230.91 465.21 251 420)
      (send p curve-to 267 384 278.5 348 296.5 312)
      (send p curve-to 301.01 302.98 318 258 329 274)
      (send p curve-to 338.89 288.39 351 314 358 332)
      (send p curve-to 377.28 381.58 395.57 429.61 414 477)
      (send p curve-to 428 513 436.5 540 449.5 573)
      (send p line-to 465 580)
      (send p line-to 529 545)
  (define bottom-logo-path
    (let ([p (new dc-path%)])
      (send p append bottom-lambda-path)
      (send p arc 0 0 630 630 (* 157/180 2 pi) (* 47/72 2 pi) #f)
  (define right-lambda-path
    (let ([p (new dc-path%)])
      (send p move-to 153 44)
      (send p curve-to 192.21 30.69 233.21 14.23 275 20)
      (send p curve-to 328.6 27.4 350.23 103.08 364 151)
      (send p curve-to 378.75 202.32 400.5 244 418 294)
      (send p curve-to 446.56 375.6 494.5 456 530.5 537)
      (send p line-to 529 545)
  (define right-logo-path
    (let ([p (new dc-path%)])
      (send p append right-lambda-path)
      (send p arc 0 0 630 630 (* 157/180 2 pi) (* 121/360 2 pi) #t)
  (define lambda-path ; the lambda by itself (no circle)
    (let ([p (new dc-path%)])
      (send p append left-lambda-path)
      (send p append bottom-lambda-path)
      (let ([t (make-object dc-path%)])
          (send t append right-lambda-path)
          (send t reverse)
          (send p append t))
      (send p close)
  ; This function draws the paths with suitable colors:
  (define (paint-plt dc)
    ; Paint white lambda, no outline:
    (send dc set-pen "BLACK" 0 'transparent)
    (send dc set-brush "WHITE" 'solid)
    (send dc draw-path lambda-path)
    ; Paint outline and colors...
    (send dc set-pen "BLACK" 0 'solid)
    ; Draw red regions
    (send dc set-brush "RED" 'solid)
    (send dc draw-path left-logo-path)
    (send dc draw-path bottom-logo-path)
    ; Draw blue region
    (send dc set-brush "BLUE" 'solid)
    (send dc draw-path right-logo-path))
  ; Create a frame to display the logo on a light-purple background:
  (define f (new frame% [label "Racket Logo"]))
  (define c
    (new canvas%
         [parent f]
          (lambda (c dc)
            (send dc set-background (make-object color% 220 200 255))
            (send dc clear)
            (send dc set-smoothing 'smoothed)
            (send dc set-origin 5 5)
            (send dc set-scale 0.5 0.5)
            (paint-plt dc))]))
  (send c min-client-width (/ 650 2))
  (send c min-client-height (/ 650 2))
  (send f show #t)

Drawing effects are not completely portable across platforms or across types of DC. Drawing in smoothed mode tends to produce more reliable and portable results than in unsmoothed mode, and drawing with paths tends to produce more reliable results even in unsmoothed mode. Drawing with a pen of width 0 or 1 in unsmoothed mode in an unscaled DC produces relatively consistent results for all platforms, but a pen width of 2 or drawing to a scaled DC looks significantly different in unsmoothed mode on different platforms and destinations.