picture-button

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.

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:

• nil: users can only deselect the button by clicking on another button in the same cluster (or by setting the value programmatically).
• t: users can deselect the button by clicking on it again once it has been selected, i.e., the control will toggle on and off.

Note: :click-off 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.

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

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
Created 2015.5.21.