| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
The toolbar utility APIs and user commands.
The near-WYSIWYG toolbar editor by Peter D. Pezaris.
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 | Quick and convenient. | |
| 39.2 The Toolbar Editor | Power tools for customization. | |
| 39.3 APIs for Adding and Killing | For Lisp programmers. | |
| 39.4 APIs for Search | Button, button, who’s got the button? | |
| 39.5 Toolbar API Portability to GNU Emacs | The ‘xemacs-toolbar.el’ library. |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Customize group of tools for interactive editing and non-interactive management of toolbars.
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’, APIs for Adding and Killing.
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.
A string describing the action, and displayed as help.
An interactive command (ie, a symbol with an interactive function definition) implementing the action.
A string used to label the button.
Optional. A position (a non-negative integer, or one of the
symbols left, right, or extreme-right.
Default: right.
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.
Add a button invoking a keyboard macro to the toolbar. The button is added at the end of the left group.
A keyboard macro name, or the empty string or nil to use a copy of the last keyboard macro defined.
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.
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.
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.
Toolbar thunk which executes the most recently defined keyboard macro.
Restores the default toolbar defined by initial-toolbar-spec.
There is also a cache of killed buttons in button-palette.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
‘edit-toolbar-quit’: Bury the ‘edit-toolbar’ buffer.
‘edit-toolbar-previous’: Select the previous item (line).
‘edit-toolbar-next’: Select the next item (line).
‘describe-mode’: Help.
‘edit-toolbar-set-function’: Set the command for the current button.
‘edit-toolbar-set-help’: Set the help string for the current button.
‘edit-toolbar-add-button’: Add a new empty button.
‘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.
‘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.
‘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.
‘edit-toolbar-copy’: Copy the selected button.
‘edit-toolbar-down’: Reorder the buttons by moving the selected button down (to the right on a horizontal toolbar).
‘edit-toolbar-up’: Reorder the buttons by moving the selected button up (to the left on a horizontal toolbar).
‘edit-toolbar-kill’: Kill the selected button.
‘edit-toolbar-save’: Save the current buffer to ‘~/.xemacs/.toolbar’ in a format that allows it to be reloaded.
‘edit-toolbar-restore’: Restore the original toolbar (ie, before this editing session started).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
List of buttons cut from toolbars.
Note this is actually a toolbar descriptor.
Add item to toolbar-spec at position, and return toolbar-spec. Uses functions that alter list structure.
A toolbar button or spacer specification (eg, from
toolbar-new-button or toolbar-new-spacer).
A toolbar descriptor (eg, from toolbar-new-toolbar).
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).
Return a checked toolbar button specification.
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.)
The (interactive) command to invoke when the button is pressed.
A string briefly describing the command, displayed in the echo area or as balloon help when the pointer enters the button.
Optional. If non-nil, specifies that the button should initially
be disabled.
See default-toolbar or the Lispref (see (lispref)Toolbars) for more information.
Returns a checked toolbar spacer “button”.
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.
Specifies the length, in pixels, of the blank area. If omitted, it defaults to a device-specific value (8 pixels for X devices).
Return a checked toolbar instantiator, a list of vectors.
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 (see (lispref)Toolbars) for more information.
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Return the position of a button containing item in its specification.
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.)
If non-nil, search it; otherwise search the default toolbar.
If non-nil, get toolbar’s descriptor in that locale,
otherwise use the global 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.
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.
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.
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.
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.