with-delayed-redraw

Arguments: (object &key invalidate invalidate-frame invalidate-children) &body body

Disables drawing on object and its child windows during the execution of body. object may be a window or a dialog-item (control). In effect, delay-redraw is called on object prior to the evaluation of body and resume-redraw is called after body completes.

with-delayed-redraw returns the values returned by the body.

This macro may be useful for preventing redundant redisplaying of windows, which can slow down an interface and be visually annoying. All output to the window or control will be prevented, whether it is the operating system redisplaying a control that it implements, or application code redisplaying a "regular" window.

The keyword arguments allow invalidation of the object's interior, frame, and/or child windows when the with-delayed-redraw form is exiting so that the window(s) will be notified to redisplay themselves once in their entirety after the body has executed. (Certain controls implemented in the operating system may redisplay themselves at the end anyway, making it unnecessary to pass any invalidate flags.)

Delaying redraws on bitmap panes

with-delayed-redraw has special behavior for a bitmap-pane. While drawing is disabled on the window itself, it is not disabled on the window's backing-store memory bitmap. This feature can be used to quickly switch a bitmap-pane to a new "scene" by drawing the new scene inside a with-delayed-redraw form, and passing the invalidate flag so that the memory bitmap is copied in one step to the visible window once the scene is drawn. This speeds up the drawing on the bitmap-pane, and removes the annoying flash that can occur when one scene is erased before the next is drawn.

For example, suppose bw is a bitmap-window and bp its bitmap-pane:

(setq bw (make-window :bw :class 'bitmap-window))
(setq bp (frame-child bw))

The following form draws colored circles over bp:

(progn (clear-page bp)
  (let ((lis (list red cyan yellow black green blue)))
     (dotimes (i 100)
        (let  ((color (nth (mod i 6) lis))
               (center (make-position 
                         (+ 50 (* 100 (truncate (/ i 10))))
                         (+ 50 (* 50 (mod i 10))))))
           (setf (foreground-color bp) color)
           (fill-circle bp center 40)))))

If you evaluate that form, you may (depending on your display and processor speed) see intermediate displays and/or flashes. Now do:

(clear-page bp)
(with-delayed-redraw (bp :invalidate t)
  (progn (clear-page bp)
    (let ((lis (list red cyan yellow black green blue)))
       (dotimes (i 100)
          (let  ((color (nth (mod i 6) lis))
                 (center (make-position 
                           (+ 50 (* 100 (truncate (/ i 10))))
                           (+ 50 (* 50 (mod i 10))))))
             (setf (foreground-color bp) color)
             (fill-circle bp center 40))))))

Note that the display updates all at once when it updates.

Microsoft Windows caveat

When a window other than a bitmap-pane is inside a with-delayed-redraw, Windows appears to suppress redrawing by claiming that the window is hidden. One odd symptom of that design is that if something is drawn on a window that is immediately behind a window that is inside a with-delayed-redraw, the drawing will appear on the screen as if the delayed window were not there at all. For this reason, the double-buffered feature may be a preferable alternative to with-delayed-redraw for windows other than bitmap-panes.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.