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

Copyright (c) 1998-2006, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 6.2 page.
Created 2005.9.20.