toolbar-button

toolbar-button Class

Summary

This class is used to create instances of toolbar buttons.

Package

capi

Superclasses

Initargs

`:callback`	A function that is called when the user presses the toolbar button and `popup-interface` is non-nil.
`:image`	Specifies the image to use for the toolbar button.
`:selected-image`	Specifies the image to use for the toolbar button when it is selected.
`:tooltip`	An optional string which is displayed, on Microsoft Windows, when the mouse moves over the button. `:tooltip` is deprecated.
`:help-key`	An object used for lookup of help. Default value `t`.
`:remapped`	Links the button to a menu item.
`:dropdown-menu`	A menu or `nil`.
`:dropdown-menu-function`
	A function of no arguments, or `nil`.
`:dropdown-menu-kind`
	One of the keywords `:button`, `:only` and `:delayed`.
`:popup-interface`	An interface or `nil`.

Accessors

toolbar-button-image
toolbar-button-selected-image
toolbar-button-dropdown-menu
toolbar-button-dropdown-menu-function
toolbar-button-dropdown-menu-kind
toolbar-button-popup-interface

Readers

help-key

Description

The class toolbar-button is used to create instances of toolbar buttons.

Toolbar buttons may be placed within toolbars and toolbar components. However, there is usually no need to create toolbar buttons explicitly; instead, the callbacks and images arguments to toolbar or toolbar-component can be used. To add tooltips, use the interface help-callback with help-key :tooltip.

In addition, an interface can have its own toolbar buttons, specified by its toolbar-items. No toolbar object is explicitly needed in that situation.

image and selected-image may each be one of the following:

A pathname or string	This specifies the filename of a file suitable for loading with load-image. Currently this must be a bitmap file.
A symbol	The symbol must either have been previously registered by means of a call to register-image-translation, or be one of the following symbols, which map to standard images: `:std-cut`, `:std-copy`, `:std-paste`, `:std-undo`, `:std-redo`, `:std-delete`, `:std-file-new`, `:std-file-open`, `:std-file-save`, `:std-print`, `:std-print-pre`, `:std-properties`, `:std-help`, `:std-find` and `:std-replace`. On Microsoft Windows, the following symbols are also recognized for view images: `:view-large-icons`, `:view-small-icons`, `:view-list`, `:view-details`, `:view-sort-name`, `:view-sort-size`, `:view-sort-date`, `:view-sort-type`, `:view-parent-folder`, `:view-net-connect`, `:view-net-disconnect` and `:view-new-folder`. Also on Microsoft Windows, these symbols are recognized for history images: `:hist-back`, `:hist-forward`, `:hist-favorites`, `:hist-addtofavorites` and `:hist-viewtree`.
An image object	For example, as returned by load-image.
An image locator object.
	This allows a single bitmap to be created which contains several button images side by side. See make-image-locator for more information. On Microsoft Windows, this also allows access to bitmaps stored as resources in a DLL.
An integer	This is a zero-based index into the `default-image-set` of the toolbar or toolbar component in which the toolbar button is used.

Each image should be of the correct size for the toolbar. By default, this is 16 pixels wide and 16 pixels high.

help-key is interpreted as described for element.

remapped, if non-nil, should match the name of a menu-item in the same interface as the button. Then, the action of pressing the button is remapped to selecting that menu-item and calling its callback. The default value of remapped is nil.

Toolbar buttons can be made with an associated dropdown menu by passing the :dropdown-menu or :dropdown-menu-function initargs.

If dropdown-menu is non-nil then it should be a menu object to display for the button.

If dropdown-menu-function is non-nil then it should be a function which will be called with the toolbar-button as its single argument. It should return a menu object to display for the button.

dropdown-menu-kind can have the following values:

`:button`	There is a separate smaller button for the dropdown menu next to the main button.
`:only`	There is no main button, only the smaller button for the dropdown.
`:delayed`	There is only one button and the menu is displayed when the user holds the mouse down over the button for some short delay. If the user clicks on the button then the normal `callback` is called.

Note: dropdown-menu-kind is not supported for toolbar buttons in the interface toolbar-items list.

popup-interface, if non-nil, should be an interface. When the user clicks on the toolbar button, the interface popup-interface is displayed near to the button. The normal callback is not called, but you can detect when the interface appears by using its activate-callback. popup-interface is useful for popping up windows with more complex interaction than a menu can provide. The default value of popup-interface is nil.

Note: popup-interface is not supported for toolbar buttons in the interface toolbar-items list.

Toolbar buttons can display text, which should be in the data or text slot inherited from item.

Note: display of text in toolbar buttons is implemented only on Motif and Cocoa.

Examples

A callback function:

(defun do-redo (data interface)
  (declare (ignorable data interface))
  (capi:display-message "Doing Redo"))

A simple interface:

(capi:define-interface redo ()
  ()
  (:panes
   (toolbar
    capi:toolbar
    :items
    (list
     (make-instance
      'capi:toolbar-component
      :items 
      (list (make-instance
             'capi:toolbar-button
             ;; remap it to the menu item
             :remapped  'redo-menu-item
             :image :std-redo))))))
  (:menu-bar a-menu)
  (:menus
   (a-menu
    "A menu"
    (("Redo" :name 'redo-menu-item
             :selection-callback 'do-redo
             :accelerator "accelerator-y"))))
  (:layouts
   (main
    capi:row-layout
    '(toolbar)))
  (:default-initargs
   :title "Redo"))

In this interface, pressing the toolbar button invokes the menu item callback:

(capi:display (make-instance 'redo))

This last example illustrates the use of :selected-image.

(capi:contain
 (make-instance
  'capi:toolbar
  :items 
  (list
   (make-instance
    'capi:toolbar-component
    :interaction :multiple-selection
    :items 
    (list (make-instance 'capi:toolbar-button
                         :image 0 
                         :selected-image 1))
    ))))