2.6 Drawing with LispWorks Graphics Ports

You can use Graphics Ports drawing in your CLIM application with the functions and macros described in this section. For more information about LispWorks Graphics Ports, see the CAPI User Guide and Reference Manual.

2.6.1 Arguments

gp-port is a symbol (not evaluated).
sheet is a CLIM sheet.
x, y, width, height are each integers or nil.
to-x, to-y, to-width, to-height, from-x, from-y, from-width, from-height are each integers or nil.
background is a graphics ports color specifier.
body is an implicit progn.
gp-drawing-func is a function that takes one argument, a gp-port.
pixmap is a graphics port pixmap.
image is a graphics ports BMP image.

2.6.2 API for Drawing with Graphics Ports (deprecated)

with-gp-drawing-to-sheet Macro

with-gp-drawing-to-sheet (gp-port sheet &key x y width height background) &body body

perform-gp-drawing Function

perform-gp-drawing sheet gp-drawing-func &key x y width height background

Summary: Binds gp-port to a graphics port, executes the body, and then copies the drawing on the port to the screen. x and y specify the position in the sheet to which the contents of the port are copied. They both default to 0. width and height specify the dimensions of the port. width defaults to the width of the sheet minus x, and height defaults to the height of the sheet minus y. background specifies the background of the port. It is a graphics port color specification, rather than a CLIM ink. See "The Color System" chapter in the CAPI User Guide and Reference Manual for details. Note that named colors can be specified by keywords like :red, :green and so on. background defaults to :white. with-gp-drawing-to-sheet creates the port using width and height and background, binds gp-port to it and evaluates the body. When the body finishes, it copies the contents to the sheet at the position specified by x and y. perform-gp-drawing is equivalent to:

(with-gp-drawing-to-sheet
 (gp-port sheet :x x :y y 
          :width width :height height
          :background background)
 (funcall gp-drawing-func gp-port))

Note: In general, body should contain calls to graphics ports drawing functions like gp:draw-string, with the port argument gp-port.

Note: Drawings into the port can exceed the dimensions. Any drawing beyond width and height is ignored.

Note: The coping completely overwrites the contents of the sheet in the rectangle specified by x, y, width and height.

Note: perform-gp-drawing is especially convenient when drawing something that also needs to be printed, because gp-drawing-func can also be used to do the drawing to a capi:printer-port.

In this example draw-some-strings draws a string with fonts in different sizes using gp:draw-string. This is purely a graphics ports function, without any relation to CLIM, and can be used to draw into a capi:output-pane, or to a capi:printer-port:

(defun draw-some-strings(port)
  (dotimes (x 10)
    (let ((font 
           (gp:find-best-font
            port 
            (gp:make-font-description :size (+ 6 (* x 3))))))
      (gp:draw-string port "A string " 30 (+ 40 (* x 30))
                      :font font))))

In this example we use draw-some-strings to draw into a CLIM stream (using *standard-output* here). Note that only the first few strings are visible, because we restrict the drawing to 100x100. The background is yellow and we also draw a pink circle under the strings:

(clim:with-gp-drawing-to-sheet (port *standard-output*
                                     :x 0 :y 100
                                     :width 100 :height 100
                                     :background :yellow)
  (gp:draw-circle port 50 50  50 :foreground :pink :filled t)
  (draw-some-strings port))

In this example perform-gp-drawing draws into a CLIM stream (again using *standard-output*). The drawing is offset by 100 in the x direction, but fills the full height:

(clim:perform-gp-drawing *standard-output*
                         'draw-some-strings
                         :x 100)

This form sends the same drawing to a printer specified by my-printer:

(capi:with-print-job (printer-port :printer my-printer)
  (draw-some-strings printer-port))