picture-button

Class

Package: common-graphics

Class

The class of a picture-button control

Control

Instance of the picture-button class. This control contains an icon that may be selected by the user. It is capable of a non-momentary pressed-in state.

The image that is to appear on a picture-button (or on a static-picture) widget may be specified with any one of the following properties (typically by passing the equivalent keyword argument such as :pixmap to make-instance when creating an instance of the widget):

Specify a pixmap object as the value of the pixmap property.
Specify an icon handle as the value of the pixmap-icon property.
Specify the name of a cached pixmap as the value of the pixmap-name property. (A pixmap is cached by calling cache-pixmap.)
Specify the pathname or path namestring of a .bmp or .ico file as the value of the pixmap-source property. When this option is specified programmatically, the pixmap will be loaded from the file when the widget is created at runtime; but when specified interactively in the inspector for a widget on a form, the pixmap will be loaded at design time and saved with project source code so that at runtime the .bmp or .ico file is not loaded or otherwise needed. This is most often the useful option when interactively building forms.
For compatibility with version 3.0.2 only: Specify the title property of a picture-button (or the value property of a static-picture) as either a pixmap, a list of a texture and a texture-info, the path namestring of a .bmp or .ico file, or an icon handle.

Further notes

If the :stretching option to make-instance is passed as non-nil, then the bitmapped image will stretch automatically to fit the size of the widget. If nil, it will be drawn at the size at which the image was defined. The default is t. See stretching.

Grouping picture-buttons in clusters

The :cluster entry on the dialog item plist can be used to group picture-button dialog items into clusters. If the user clicks on one button in the cluster, that button will be turned on, and all other buttons in the cluster turned off. For example, consider the following:

(make-instance 'picture-button ... :cluster 'cluster1) 
(make-instance 'picture-button ... :cluster 'cluster1) 
(make-instance 'picture-button ... :cluster 'cluster2) 
(make-instance 'picture-button ... :cluster 'cluster2)

It creates two picture-button clusters each with two picture buttons. :cluster entries are compared using eql.

Component overhead and clusters of picture-buttons

Using a multi-picture-button instead of clusters of picture-buttons will reduce the load on resources and reduce application size/complexity in most situations. Components are window-like objects and are relatively costly in terms of system resources.

Using click-off with picture-button controls

This control supports the click-off property. The :click-off option to make-instance can have the following values:

:yes: Users will be able to deselect the button by clicking on it when currently selected. This is the initial value for picture-buttons.

:no: Users can only deselect a selected button by selecting another button in the same cluster.

Nil: The default value for the specific class of control.

Note: this option affects only what happens when clicking on a button widget while it is selected; the state of the button can always be changed programmatically by calling (setf value).

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

Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.