use-bitmap-stream

Arguments: drawable

Returns (or sets with setf) whether a drawable uses a bitmap-stream on which output is drawn before being copied to the visible window of the control. To use a bitmap-stream, an application need only turn this property on, either by passing the :use-bitmap-stream initarg as true when creating the drawable, or calling (setf use-bitmap-stream) later. The drawable will automatically create a bitmap-stream of the proper size as needed.

If a drawable uses a bitmap-stream, it is returned by the bitmap-stream function. The function drawable-stream applied to a drawable returns the bitmap-stream if there is one.

A drawable will work just fine without a bitmap-stream, but a bitmap-stream may be used for various special reasons. Here are the steps involved for a few of these reasons after turning the use-bitmap-stream property on:

• To store what was drawn once and recopy it quickly to the window when needed (as with a bitmap-pane). When you do this, you should:
  1. Do not give the drawable an on-redisplay function. (An on-redisplay function should redraw the image when necessary. However, the bitmap-stream acts as a backing store, redisplaying automatically when necessary.)
  2. Retrieve the bitmap-stream by calling bitmap-stream on the drawable.
  3. Call clear-page on the bitmap-stream to erase any old drawing.
  4. Draw something on the bitmap-stream.
  5. Call invalidate on the drawable to display the drawing on the visible window.

  From now on, whenever the drawable is uncovered, its drawing will be refreshed from the bitmap-stream.

• To switch quickly from one ad hoc drawing to another.

  Simply repeat the above procedure a number of times when needed. This avoids the flashing that would be seen by erasing and drawing directly on the visible window.

• Animation effects, or changing the drawing at scheduled times.

  Supply an on-redisplay function along with use-bitmap-stream.

  Write the on-redisplay function so that it reads parameters that change, causing it to draw its drawing differently.

  When it is time to go to the next version of the drawing, call update-drawable on the drawable. This will cause the on-redisplay function to be called to draw the new version on the bitmap-stream and then copy the drawing quickly to the window.

  If the parameters are changed quickly, calling update-drawable each time, an animation effect can be achieved.

If use-bitmap-stream is toggled on and off, a new bitmap-stream is created only if the most recent one is not large enough either horizontally or vertically. So toggling this property should not be inefficient.

The bitmap-stream is also grown as needed automatically when the page size of the drawable is increased. This includes the case where (1) the scrollbar in either direction is not enabled, (2) no explicit page size has been given in that direction, and (3) the drawable itself is sized larger in that direction; in this case the default page size follows the interior size of the drawable, and the bitmap-stream is made larger as needed.

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.