12.1 Displaying graphics

In order to display your own drawings, you need to provide a function to the output-pane that is called to redraw sections of the pane when they are exposed. This function is called the display-callback, and it is automatically called in the correct process. When the CAPI needs to redisplay a region of an output-pane, it calls that output pane's display-callback function, passing it the pane and the region in question.

For example, to create a pane that has a circle drawn inside it, do the following:

(defun draw-a-circle (pane x y width height)
  (gp:draw-circle pane 100 100 50))
 
(contain
 (make-instance
  'output-pane
  :display-callback 'draw-a-circle)
 :best-width 300
 :best-height 300)

Notice that the callback in this example ignores the region that needs redrawing and just redraws everything. This is possible because the CAPI clips the drawing to the region that needs redisplaying, and hence only the needed part of the drawing gets done. For maximum efficiency, it would be better to only draw the minimum area necessary.

The arguments :best-width and :best-height specify the initial width and height of the interface. More detail can be found in the manual page for interface.

Now that we can create output panes with our own display functions, we can create a new class of window by using defclass as follows.

(defclass circle-pane (output-pane)
  ()
  (:default-initargs
   :display-callback 'draw-a-circle))
 
(contain (make-instance 'circle-pane))

Compatibility Note: you must ensure that all drawing occurs inside the display-callback. In previous versions of LispWorks, we documented examples where drawing was done outside the display-callback, but this was always a bad idea because it was not coordinated updates triggered by the window system. On macOS Big Sur and later, drawing outside the display-callback will not work and may cause errors.