39. The Toolbar Utilities

The toolbar utilities are a set of Emacs commands and Lisp functions for convenient creation and management of toolbars. Common usages such as creating and adding toolbar buttons to invoke commands and keyboard macros are implemented as user commands. Convenience APIs are provided to create buttons, add them to toolbars, kill them from toolbars, and finding a particular button, or a button with certain content, in a toolbar.

The toolbar utilities are implemented in three files:

`toolbar-utils.el'

The toolbar utility APIs and user commands.

`edit-toolbar.el'

The near-WYSIWYG toolbar editor by Peter D. Pezaris.

`xemacs-toolbar.el'

The XEmacs compatibility API for programs that should also run under GNU Emacs.

The author would like to thank Jeff Miller and Peter D. Pezaris for the original API and the toolbar editor, respectively, and David Kastrup and Jamie Zawinski for the pedal-gluteal impetus that resulted in the recent revision of these libraries described in this manual.

39.1 Adding Buttons on the Fly

Group: edit-toolbar

Customize group of tools for interactive editing and non-interactive management of toolbars.

Variable: toolbar-button-default-position

Default position for adding toolbar buttons on the fly. The value may be a non-negative integer (0 is leftmost), or one of the symbols left, right, or extreme-right. left is synonymous with 0, and extreme-right is synonymous with (length toolbar). right specifies placing a new item at the right end of the flush-left group of buttons.

Default value: right. Customize type: sexp.

See also `toolbar-add-button', 39.3 APIs for Adding and Killing.

Command: toolbar-add-button-on-the-fly description command label &optional position locale

Add an button at position to the default toolbar of the selected window. Returns t.

The return value may change. Tell stephen@xemacs.org what value you think would be (most) useful.

description

A string describing the action, and displayed as help.

command

An interactive command (ie, a symbol with an interactive function definition) implementing the action.

label

A string used to label the button.

position

Optional. A position (a non-negative integer, or one of the symbols left, right, or extreme-right.

Default: right.

locale

Optional. A specifier locale, defaulting to the current buffer. If current-buffer-only is not what you want, and you don't understand specifier locales, use global. It's safe and probably does what you want.

Command: toolbar-add-kbd-macro mac icon is-file

Add a button invoking a keyboard macro to the toolbar. The button is added at the end of the left group.

mac

A keyboard macro name, or the empty string or nil to use a copy of the last keyboard macro defined.

icon

A string specifying the icon to be used. If is-file is non-nil, it is interpreted as the name of an image file, and searched for using locate-data-file. Otherwise it is used verbatim as a label.

is-file

Determines the treatment of icon (q.v.).

Used interactively, prompts for the macro name mac and an icon. is-file is non-nil if a prefix argument was used.

Function: toolbar-add-execute-macro-button

Add a button to the global toolbar to execute the last keyboard macro.

Unlike toolbar-add-kbd-macro, this does not copy the macro. The macro executed will change with redefinitions.

Due to a simple implementation, this button will not appear in buffers with local toolbars if invoked after the toolbar is installed. If you like this button, it's probably best to invoke this function in your init file.

Function: toolbar-execute-last-kbd-macro

Toolbar thunk which executes the most recently defined keyboard macro.

Command: restore-initial-toolbar

Restores the default toolbar defined by initial-toolbar-spec.

There is also a cache of killed buttons in button-palette.

39.2 The Toolbar Editor

To use `edit-toolbar.el', simply type M-x edit-toolbar RET.

For help on the various commands you can type ? in a `edit-toolbar' buffer. To save a modified toolbar type C-x C-s in an `edit-toolbar' buffer. If you want to use a saved toolbar in your future XEmacs sessions, add the following line of code to your init file:

  (load "~/.xemacs/.toolbar")

Here is a table of commands and bindings available in `edit-toolbar-mode'. These commands are also available from the `Edit Toolbar' menu.

q

`edit-toolbar-quit': Bury the `edit-toolbar' buffer.

p

DEL

`edit-toolbar-previous': Select the previous item (line).

n

SPC

RET

`edit-toolbar-next': Select the next item (line).

?

`describe-mode': Help.

f

`edit-toolbar-set-function': Set the command for the current button.

h

`edit-toolbar-set-help': Set the help string for the current button.

a

`edit-toolbar-add-button': Add a new empty button.

2

`edit-toolbar-add-separator-2D-narrow': Add a new narrow 2D fixed-width spacer.

@

`edit-toolbar-add-separator-2D-wide': Add a new wide 2D fixed-width spacer.

3

`edit-toolbar-add-separator-3D-narrow': Add a new narrow 3D fixed-width spacer.

#

`edit-toolbar-add-separator-3D-wide': Add a new wide 3D fixed-width spacer.

R

`edit-toolbar-add-separator-right-left': Place the filler separator, which expands to create a flush-left group of buttons and spacers and a flush-right group.

c

`edit-toolbar-copy': Copy the selected button.

d

`edit-toolbar-down': Reorder the buttons by moving the selected button down (to the right on a horizontal toolbar).

u

`edit-toolbar-up': Reorder the buttons by moving the selected button up (to the left on a horizontal toolbar).

k

`edit-toolbar-kill': Kill the selected button.

s

C-x C-s

`edit-toolbar-save': Save the current buffer to `~/.xemacs/.toolbar' in a format that allows it to be reloaded.

r

`edit-toolbar-restore': Restore the original toolbar (ie, before this editing session started).

39.3 APIs for Adding and Killing

Variable: button-palette

List of buttons cut from toolbars.

Note this is actually a toolbar descriptor.

Function: toolbar-add-item toolbar-spec item &optional position

Add item to toolbar-spec at position, and return toolbar-spec. Uses functions that alter list structure.

item

A toolbar button or spacer specification (eg, from toolbar-new-button or toolbar-new-spacer).

toolbar-spec

A toolbar descriptor (eg, from toolbar-new-toolbar).

position

Optional. A non-negative integer, with 0 being the extreme left and \(length toolbar-spec) the extreme right. The symbols left, right, and extreme-right are also accepted. left is synonymous with 0. right places item at the right end of the left group of buttons. extreme-right places item at the extreme right of the toolbar, creating a right group if one does not exist.

#### This function does not yet support inserting the group delimiter nil as an explicit item.

position may be greater than (length toolbar-spec), in which case it is truncated to (length toolbar-spec). Note that (length toolbar-spec) is not synonymous with right or extreme-right (extreme-right will create a right group if it doesn't already exist).

Function: toolbar-new-button icon-spec command help-string &optional initially-disabled

Return a checked toolbar button specification.

icon-spec

A list of glyphs (from make-glyph), a glyph, or a string to use as the button's icon. If a string or single glyph, it will be used for the button-up glyph. If a list, it may contain 1 to 6 glyphs, which XEmacs will use for button up, button down, button disabled, button up with caption, button down with caption, and button disabled with caption, in that order. Missing or nil glyphs will be defaulted. (#### Strings as list elements are not supported but could be.)

command

The (interactive) command to invoke when the button is pressed.

help-string

A string briefly describing the command, displayed in the echo area or as balloon help when the pointer enters the button.

initially-disabled

Optional. If non-nil, specifies that the button should initially be disabled.

See default-toolbar or the Lispref (@xref{Toolbars, , , lispref}) for more information.

Function: toolbar-new-spacer style &optional size

Returns a checked toolbar spacer "button".

style

One of the symbols 2d or 3d, indicating whether the area is displayed without shadows (giving it a flat appearance), or with shadows (giving it a raised, 3-D appearance). There is no default. #### We may set a default style. Tell stephen@xemacs.org which you use.

size

Specifies the length, in pixels, of the blank area. If omitted, it defaults to a device-specific value (8 pixels for X devices).

Function: make-toolbar-instantiator &optional toolbar-spec domain

Return a checked toolbar instantiator, a list of vectors.

toolbar-spec

May be a list of buttons (ie, a toolbar descriptor, see default-toolbar), a toolbar specifier object, a symbol whose value is a toolbar specifier object, or nil. If nil, returns a null list. If a toolbar specifier object or variable containing one, the specification for DOMAIN is used. If non-nil, DOMAIN must be a window, a frame, or a device, otherwise it defaults to the selected window (see specifier-instance). The list thus generated is checked and returned.

If toolbar-spec is a list, it is copied; it is safe to pass other packages' toolbar initializers to this function. However, you probably do not want to change any of the objects in the returned specification. They are returned as is, not copied.

See default-toolbar or the Lispref (@xref{Toolbars, , , lispref}) for more information.

Function: toolbar-kill-item-pos pos &optional toolbar locale

Kill the item at position pos of toolbar in locale. Killed buttons are prepended to button-palette.

locale defaults to global. If there are multiple specs for locale, take the first one.

This function currently does not accept symbolic positions a la toolbar-add-item. Use toolbar-find-item to locate whole buttons and spacers, and toolbar-find-button to locate buttons by characteristics. See also toolbar-find-button-by-icon, toolbar-find-button-by-command, and toolbar-find-button-by-help-string.

39.4 APIs for Search

Function: toolbar-find-button item &optional toolbar locale

Return the position of a button containing item in its specification.

item

May specify a button, spacer, icon, command, help string, or nil. If item is nil, find the separator between the group of buttons to be left justified, and the group to be right justified. (Distinctions among the various "search key types" are somewhat heuristic but are probably reliable enough to use in library code.)

toolbar

If non-nil, search it; otherwise search the default toolbar.

locale

If non-nil, get toolbar's descriptor in that locale, otherwise use the global locale.

Function: toolbar-find-item item &optional toolbar locale

Return the position of item, a button, spacer, or nil. toolbar and locale determine the descriptor to be searched.

If item is nil, find the separator between the group of buttons to be left justified, and the group to be right justified. If there are several matching items, the first is returned. If none is found, return nil.

Function: toolbar-find-button-by-icon icon &optional toolbar locale

Return the position of a button with icon icon. icon must be a list of glyphs or a symbols whose value is a list of glyphs. toolbar and locale determine the descriptor to be searched.

If there are several matching buttons, the first is returned.

Function: toolbar-find-button-by-command cmd &optional toolbar locale

Return the position of a button invoking command CMD. toolbar and locale determine the descriptor to be searched.

If there are several matching buttons, the first is returned.

Function: toolbar-find-button-by-help-string str &optional toolbar locale

Return the position of a button with help-string str. toolbar and locale determine the descriptor to be searched.

If there are several matching buttons, the first is returned. This function will not find spacers.

Function: toolbar-find-button-by-element object index toolbar locale &optional thunk

Return the position of a button containing object in element index. toolbar and locale determine the descriptor to be searched.

Optional argument thunk is a function of one argument which is used to normalize object for comparison.

If there are several matching buttons, the first is returned. This function will not find spacers.

39.5 Toolbar API Portability to GNU Emacs

The `xemacs-toolbar.el' library provides XEmacs toolbar compatibility functions for GNU Emacs.

Third-party maintainers may use the same APIs in GNU Emacs as in XEmacs. Simply provide this library with your own code, and load it conditionally:

  (if (featurep 'xemacs)
      (require 'toolbar-utils)
    (require 'toolbar-utils "xemacs-toolbar"))

XEmacs features that are not present in GNU Emacs will be ignored, and various arguments with different semantics will be defaulted appropriately.

User commands such as toolbar-add-kbd-macro and advanced features such as the toolbar editor and the button cache are not presently provided.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.