Class | Package: cg | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version

## 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.
- draw-focus: determines whether a focus rectangle is drawn.
- 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.)
- pressed-color-mapper: specifies the colors used in a pressed button.
- recessed: determines whether buttons appear recessed or appear to protrude.
- retain-scroll-arrows-always: determines whether a multi-picture-button control will have scroll arrows drawn even when all of the buttons fit into the control's region.
- spacing: determines the spacing between buttons. See also padding which specifies the distance between a button's image and the button's border.
- hidden-buttons: a list of hidden buttons.
- unavailable-buttons: a list of unavailable buttons.
- unavailable-color-mapper: determines colors used for unavailable buttons.
- use-default-tooltips: controls whether the tooltip string should be taken from the button-info name.
- multiple-selections controls whether more than one button can be pressed down at the same time. When `nil`, this will automatically unpress any other buttons when a new button is pressed.
- unpress-automatically: unpress-automatically will cause any button that was pressed interactively to be unpressed just after the widget's on-change function (if any) has run.

See also multi-picture-button-scroll, multi-picture-button-scroll-interval, and update-multi-picture-button.

### 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.

See also unpress-automatically, which causes the button to be unpressed after the on-change function is run.

### 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.

    (make-instance 'multi-picture-button
                       :font
                       (make-font-ex nil "MS Sans Serif" 11 nil)
                       :left 430
                       :name :multi-picture-button-1
                       :top 84
                       :unavailable-color-mapper
                        (list (cons black gray) (cons dark-gray gray)
                             (cons dark-blue gray) (cons dark-green gray)
                             (cons dark-red gray) (cons dark-cyan gray)
                             (cons dark-yellow gray)
                             (cons dark-magenta gray) (cons red dark-red)
                             (cons green dark-green) (cons blue dark-blue)
                             (cons yellow dark-yellow)
                             (cons cyan dark-cyan)
                             (cons magenta dark-magenta))
                       :range (list (make-instance 'button-info
                               :name :new
                               :pixmap-name :new
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string "Open a blank editor window")
                             (make-instance 'button-info
                               :name :open
                               :pixmap-name :open
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string "Edit a file")
                             (make-instance 'button-info
                               :name :save
                               :pixmap-name :save
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string "Save the selected window")
                             (make-instance 'button-info
                               :name :load
                               :pixmap-name :load
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string "Load a lisp file")
                             :gap
                             (make-instance 'button-info
                               :name :red
                               :pixmap-name nil
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color red
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string "Use red")
                             (make-instance 'button-info
                               :name :green
                               :pixmap-name nil
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color green
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string "Use green")
                             (make-instance 'button-info
                               :name :blue
                               :pixmap-name nil
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color blue
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string "Use blue")
                             (make-instance 'button-info
                               :name :yellow
                               :pixmap-name nil
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color yellow
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string "Use yellow")
                             (make-instance 'button-info
                               :name :cyan
                               :pixmap-name nil
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color cyan
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string "Use cyan")
                             (make-instance 'button-info
                               :name :magenta
                               :pixmap-name nil
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color magenta
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string "Use magenta")
                             (make-instance 'button-info
                               :name :one
                               :pixmap-name nil
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title "One"
                               :width 26
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string nil)
                             (make-instance 'button-info
                               :name :two
                               :pixmap-name nil
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title "Two"
                               :width 26
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string nil)
                             (make-instance 'button-info
                               :name :incremental-evaluation
                               :pixmap-name :incremental-evaluation
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string nil)
                             (make-instance 'button-info
                               :name :incremental-compile
                               :pixmap-name :incremental-compile
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string nil)
                             (make-instance 'button-info
                               :name :evaluate-clipboard
                               :pixmap-name :evaluate-clipboard
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string nil)
                             (make-instance 'button-info
                               :name :inspect
                               :pixmap-name :inspect
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string nil)
                             (make-instance 'button-info
                               :name :find-in-file
                               :pixmap-name :find-in-file
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string nil)
                             (make-instance 'button-info
                               :name :find-definition
                               :pixmap-name :find-definition
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string nil)
                             :gap
                             (make-instance 'button-info
                               :name :trace
                               :pixmap-name :trace
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string nil)
                             (make-instance 'button-info
                               :name :breakpoint
                               :pixmap-name :breakpoint
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string nil)
                             (make-instance 'button-info
                               :name :profile
                               :pixmap-name :profile
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string nil)
                             (make-instance 'button-info
                               :name :create
                               :pixmap-name :basic-pane
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string nil)
                             (make-instance 'button-info
                               :name :edit-file
                               :pixmap-name :edit-file
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string nil)
                             (make-instance 'button-info
                               :name :apropos
                               :pixmap-name :apropos
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string nil)
                             (make-instance 'button-info
                               :name :print
                               :pixmap-name :print
                               :pixmap-source nil
                               :pixmap-icon nil
                               :background-color nil
                               :foreground-color nil
                               :title nil
                               :width nil
                               :height nil
                               :stretching t
                               :tooltip nil
                               :help-string nil))
                     )

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 example above came from placing a `multi-picture-button` on a form and looking at the resulting .bil file.

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

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.

|  | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version