double-buffered

Arguments: window-or-lisp-widget

Returns whether a window or a lisp-widget uses a memory bitmap to reduce flashing effects when the window is redisplayed. The value may be set either by calling (setf double-buffered) or by passing the :double-buffered initarg when using make-window to create the window or make-instance to create the lisp-widget.

window-or-lisp-widget should be either an instance of basic-pane or one of its subclasses, or an instance of lisp-widget or one of its subclasses. The value should be true to put the window into double-buffering mode, or nil to take it out of double-buffering mode. The default value is nil except for outline and grid-widget, where the default is t.

Double-buffering works by redirecting all drawing function calls to actually draw on the window's internal memory bitmap, and later copying the memory bitmap to the visible window in a single operation. This typically eliminates the flash that occurs when a window is first blanked out before redrawing its content. This flash is often noticable when the user interactively scrolls or resizes a window, or when the application programmatically updates the contents of a window for animation effects.

Drawing is redirected to the memory bitmap only when a drawing function is called inside a redisplay-window method that was called by Common Graphics (rather than the application calling it directly), or when the drawing function is called inside a with-double-buffering macro call. When an application updates the contents of a window, it normally should call invalidate on the window to trigger a redisplay (and then perhaps update-window to force the redisplay to happen immediately), and then Common Graphics will call the window's redisplay-window method. But if you really need to draw directly to a window and would still like double-buffering to occur, then this can be achieved by doing the drawing inside a call to with-double-buffering.

The double-buffered property may not be applied to os-widgets because Common Graphics does not have control over the drawing of them. In addition, the bitmap-pane window and the drawable and multi-picture-button lisp-widgets implement special types of double-buffering, and so this general double-buffering facility may not be used with instances of those classes. (If you do turn the double-buffered property on for them, a warning is signaled and the request is ignored.)

The double-buffered property will automatically create a memory bitmap that is the size of the window's interior, and replace it with a larger one when needed. A bitmap-pane, by contrast, creates a memory bitmap that is the size of the entire scrollable page (or canvas) of the window. So a bitmap-pane is more expensive in terms of memory usage, but will also remember an entire drawing so that the application does not need to redraw it at all when the window is exposed or scrolled.

Creating or resizing a double-buffered window could signal an error of type memory-bitmap-not-created if there is not enough memory for the memory bitmap.

GTK Note

This property has no effect on GTK, which always does its own double-buffering internally. All windows on GTK will therefore behave as if this property is true.

Example

There is a complete code example of using the double-buffered property for animation in the section Animation in cg-drawing.htm.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 8.1 page.
Created 2016.6.21.