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.

See About how to get sample code for creating controls in cgide.htm, which explains how to use the IDE to create such code.

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.

A diagram of window and widget classes is shown in Widget and window classes in cgide.htm.

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.