ClassPackage: cgToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 10.0
Unrevised from 9.0 to 10.0.
9.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:

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-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
Created 2015.5.21.

ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 10.0
Unrevised from 9.0 to 10.0.
9.0 version