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 conttrols

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: deterines whether the control is filled length first or breadth first.
• padding: specifies the button buttons, which is the space arounf 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.
• 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.

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.

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. :width). 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.

Copyright (c) 1998-2001, Franz Inc. Berkeley, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.1 update # 1. This page was not revised.
Created 2001.12.15.