drawable

Class

A vanilla control for drawing arbitrary custom drawings. The drawing
can either be performed at will or by an on-redisplay handler
function whenever a redisplay is needed. A bitmap-stream may
optionally be used by the control, either to remember what currently
should be drawn on the control or to draw updates with less flashing.

A drawable control allows a drawing field in a dialog. Other ways to
combine drawing with controls is to use a window with one pane a
bitmap-pane
and another a dialog, or to use a
bitmap-window
with a toolbar (on which controls can be placed). It is also possible
to place controls directly on a bitmap-pane, though in that case
certain features are lost, such as using the TAB key to move focus
from one control to another. (However, if that feature is less
important, putting controls directly on a bitmap-pane does allow for
faster redisplay.)

This widget has page-width, page-height, and scrollbars properties, which are usually
properties of windows rather than widgets. For a drawable widget,
these properties work just as they do with windows.

There are two issues with images on a drawable control: displaying
them in the first place and refreshing them when necessary (when, for
example, the control is covered and uncovered, or iconified and
expanded).

If use-bitmap-stream is nil, drawing
is done by the on-redisplay function. This
function (an example is given on the on-redisplay page) should do all
drawing necessary. Whenever redisplay is necessary, this function will
be called. Redisplay is forced by a call to update-drawable. It
is also forced when a drawable is covered and uncovered or when it is
iconified and expanded.

Whenever a drawable control needs to be redrawn, such as when it is
uncovered, redisplay-event is called on
it. The default redisplay-event method essentially just calls the
on-redisplay handler of
the drawable if it has one, and the on-redisplay handler is the more
typical place to place custom drawing code.

If use-bitmap-stream is true, there
will be a bitmap-stream associated with the
drawable control, returned by the function bitmap-stream applied to the
drawable. Drawing should be done to this bitmap-stream, and then the
drawable should be refreshed with a call to update-drawable. The
drawable will also be updated when it is covered and uncovered, or
iconified and expanded. (Note that drawing is not done directly on the
drawable. The bitmap-stream is not visible. It must be copied to the
drawable. Note that this copying can become expensive if the image is
large and redisplays are frequent.)

The function drawable-stream
returns the bitmap-stream of a drawable if there is one and the window
of the drawable otherwise.

The Navigator
Dialog has an example (on the Examples tab) of the drawable
widget called "An Animated 'Drawable' Control". It illustrates smooth
animation using the use-bitmap-stream option of the widget and a
timer to control the speed of the animation. Display the Navigator
dialog with the Help | Navigator menu command.