multi-picture-button

Class

The class of the multi-picture-button control.

Control

An instance of the multi-picture-button class. This
control fills the need for toolbars and other instances of controls
where many icons may need to appear on a form at once. Graphic lines
and gaps separate the control icons into three main groupings in the
initial version of the control. This control is capable of a
non-momentary pressed-in state.

Using the multi-picture-button instead of
many individual bitmaps can reduce application overhead. Controls are
window-like objects; they can get focus and be affected by
events. They are costly in terms of system resources. It is a better
design strategy to use a multi-picture-button instead of a bank of
individual picture-button controls and save the overhead for another
part of the application where you might really want it.

Not every cell in the multi-picture button has to be clickable, some
can be purely for display.

Various properties of multi-picture-button controls

Among the properties of this control are:

button-3d-border:
determines whether each button on the multi-picture-button control has
the thick white-and-gray 3D border.

button-black-border: determines
whether each button on the multi-picture-button control has a thin
black border.

fill-order:
determines whether the control is filled length first or breadth first.

padding:
specifies the button padding, which is the space around the image in a
button and the button's border. padding applies to all sides, left,
right, top and bottom. (See also spacing, which specifies the
distance between buttons.)

Defining individual buttons on the control

The range of a
multi-picture-button control is a list of button-info objects and optionally
the keyword :gap. Each button-info is a CLOS object that
describes one of the individual buttons of the multi-picture-button
control. Setting the range (with setf) to a different list of button-infos will
update the set of displayed buttons. The symbol
:gap may also appear in the range list. That value
inserts a gap (of size gap-size) between the buttons
defined by the button-info instances on either
side of :gap. When button-3d-border is
:when-pressed in the multi-picture-button control,
the gap is further indicated by a vertical line.

The value of a
multi-picture-button is a list of the names of the buttons that are
currently pressed. Setting the value to a different list of button
names will cause those buttons to be pressed in and all other buttons
released.

What happens when a button is clicked?

When a button is clicked by the user, the
on-change event handler will be invoked.

The new-value argument is a list of all buttons that are pressed after
the click. If it is a longer list than the old-value argument, then a
button was pressed (rather than released) and it is guaranteed that
the clicked button is the first one in the list. The new-value
argument will be nil if a single button had
been pressed and was clicked to release it.

Creating an instance of a multi-picture-button control

This call to make-instance
returns an instance of a multi-picture-button. Properties can be
initialization keyword arguments (the keyword has the same name as the
property, with a prepended colon, e.g. :top for top). Additional arguments could be
provided. Their absence indicates the default value will be used. Note
that the value of the range argument (the last one) is a long list of
button-info
instances.