add-to-component-toolbar

Arguments: component-class-name pixmap-or-title &key after tooltip help-string

This function allows developers to extend the IDE to include their own classes. It adds a new button to the IDE's Component Toolbar to allow a specified control class to be interactively instantiated onto a form. The control class is also added to the list of component classes presented by the Form | Add Component menubar command. If the class is already represented on the Component Toolbar, then no button is added.

The new button will remain on the toolbar only as long as the current invocation of Allegro is still running, rather than being added back automatically the next time that Allegro starts up. If a project defines a custom control class, you may want to add a call to add-to-component-toolbar to one of the project's .cl source code files as a top-level form --- then the control class will be added to the toolbar if needed whenever the project is loaded. Alternately, a call to add-to-component-toolbar could be placed in the startup.cl file or in an *ide-startup-hook* function. (See About IDE startup in cgide.htm.)

component-class-name is either the name of a control class to be added or the symbol :gap. Specifying :gap inserts a small gap (with a thin bar drawn in it) between groups of buttons, as usual with a multi-picture-button range. A multi-picture-button will automatically filter out multiple contiguous gaps, so an application does not have to worry about whether a gap is already where one is desired.

The arguments are:

• pixmap-or-title: the value should be either a pixmap object to display on the toolbar's button for the control, or a string to display instead.
• after: the value may be the name of a control class that may already be on the toolbar, or the symbol :last, or nil. If it is a class name and there is a button on the toolbar for that class, then the new button is placed just to the right of the specified button. If it is the symbol :last, then the new button is placed after the last (rightmost) button. Otherwise the new button is placed at the left end of the toolbar.
• tooltip: the value should be a string to display in a tooltip when the mouse cursor pauses over the button. Defaults to the name of the class, except with spaces in place of dashes, and each word capitalized.
• help-string: the value should be a string to display in the IDE's status bar to indicate what the button will do if clicked. Defaults to a standard message about adding the particular type of control.

See remove-from-component-toolbar, which removes components (either your own or standard ones) from the toolbar.

Example:

;; Define a custom single-item-list.
(defclass pretty-item-list (single-item-list)()
  (:default-initargs
   :background-color cyan))

;; Define a pixmap to represent the custom control class.
(cache-pixmap
 (make-instance 'pixmap
   :name 'pretty-item-list
   :bits-per-pixel 4
   :colors (default-palette-vector *system*)
   :contents
   '(( 7  7  7  7  7  7  7  7  7  7  7  7  7  7  7  7)
     ( 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0)
     ( 0 14 14 14 14 14 14 14 14 14 14 14 14 14 14  0)

     ( 0 14  0 14  0 14  0 14 14 14 14 14 14 14 14  0)
     ( 0 14 14 14 14 14 14 14 14 14 14 14 14 14 14  0)
     ( 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0)
     ( 0  0 14  0 14  0 14  0 14  0  0  0  0  0  0  0)
     ( 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0)
     ( 0 14 14 14 14 14 14 14 14 14 14 14 14 14 14  0)
     ( 0 14  0 14  0 14  0 14 14 14 14 14 14 14 14  0)
     ( 0 14 14 14 14 14 14 14 14 14 14 14 14 14 14  0)
     ( 0  8  8  8  8  8  8  8  8  8  8  8  8  8  8  0)

     ( 0 14 14 14 14 14 14 14 14 14 14 14 14 14 14  0)
     ( 0 14  0 14  0 14  0 14 14 14 14 14 14 14 14  0)
     ( 0 14 14 14 14 14 14 14 14 14 14 14 14 14 14  0)
     ( 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0))))

;;; Add a button using the above pixmap to instantiate the custom control.
(ide:add-to-component-toolbar 'pretty-item-list
 (find-pixmap 'pretty-item-list) :after 'single-item-list)

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.