The documentation for `add-menu-button' starts like this:
`add-menu-button' is a compiled Lisp function
(add-menu-button MENU-PATH MENU-LEAF &optional BEFORE IN-MENU)
Add a menu item to some menu, creating the menu first if necessary.
If the named item exists already, it is changed.
MENU-PATH identifies the menu under which the new menu item should be inserted.
It is a list of strings; for example, ("File") names the top-level "File"
menu. ("File" "Foo") names a hypothetical submenu of "File".
MENU-LEAF is a menubar leaf node. See the documentation of `current-menubar'.
Now, I expected the keyword "menubar leaf node" to show up in the
documentation of `current-menubar'. No such luck (docs attached).
Can anyone enlighten me what this MENU-LEAF means? I need to know to
fix an outstanding Dired bug ...
`current-menubar' is a simple built-in variable.
The current menubar. This may be buffer-local.
When the menubar is changed, the function `set-menubar-dirty-flag' has to
be called for the menubar to be updated on the frame. See `set-menubar'
A menubar is a list of menus and menu-items.
A menu is a list of menu items, keyword-value pairs, strings, and submenus.
The first element of a menu must be a string, which is the name of the menu.
This is the string that will be displayed in the parent menu, if any. For
toplevel menus, it is ignored. This string is not displayed in the menu
Menu accelerators can be indicated in the string by putting the
sequence "%_" before the character corresponding to the key that will
invoke the menu or menu item. Uppercase and lowercase accelerators
are equivalent. The sequence "%%" is also special, and is translated
into a single %.
If no menu accelerator is present in the string, XEmacs will act as if
the first character has been tagged as an accelerator.
Immediately following the name string of the menu, various optional
keyword-value pairs are permitted: currently, :filter, :active, :included,
and :config. (See below.)
If an element of a menu (or menubar) is a string, then that string will be
presented as unselectable text.
If an element of a menu is a string consisting solely of hyphens, then that
item will be presented as a solid horizontal line.
If an element of a menu is a string beginning with "--:", it will be
presented as a line whose appearance is controlled by the rest of the
text in the string. The allowed line specs are system-dependent, and
currently work only under X Windows (with Lucid and Motif menubars);
otherwise, a solid horizontal line is presented, as if the string were
The possibilities are:
"--:shadowDoubleEtchedIn" (Lucid menubars only)
"--:shadowDoubleEtchedOut" (Lucid menubars only)
"--:shadowDoubleEtchedInDash" (Lucid menubars only)
"--:shadowDoubleEtchedOutDash" (Lucid menubars only)
If an element of a menu is a list, it is treated as a submenu. The name of
that submenu (the first element in the list) will be used as the name of the
item representing this menu on the parent.
If an element of a menubar is `nil', then it is used to represent the
division between the set of menubar-items which are flushleft and those
which are flushright.
Otherwise, the element must be a vector, which describes a menu item.
A menu item is of the following form:
[ "name" callback :<keyword> <value> :<keyword> <value> ... ]
The following forms are also accepted for compatibility, but deprecated:
[ "name" callback <active-p> ]
[ "name" callback <active-p> <suffix> ]
The name is the string to display on the menu; it is filtered through the
resource database, so it is possible for resources to override what string
is actually displayed. Menu accelerator indicators (the sequence `%_') are
also processed; see above. If the name is not a string, it will be
evaluated with `eval', and the result should be a string.
If the `callback' of a menu item is a symbol, then it must name a command.
It will be invoked with `call-interactively'. If it is a list, then it is
evaluated with `eval'.
In the deprecated forms, <active-p> is equivalent to using the :active
keyword, and <suffix> is equivalent to using the :suffix keyword.
The possible keywords are:
:active <form> The expression is evaluated just before the menu is
displayed, and the menu will be selectable only if
the result is non-nil.
:suffix <form> The expression is evaluated just before the menu is
displayed and the resulting string is appended to
the displayed name, providing a convenient way of
adding the name of a command's ``argument'' to the
menu, like ``Kill Buffer NAME''.
:keys "string" Normally, the keyboard equivalents of commands in
menus are displayed when the `callback' is a symbol.
This can be used to specify keys for more complex menu
items. It is passed through `substitute-command-keys'
:style <style> Specifies what kind of object this menu item is:
nil A normal menu item.
toggle A toggle button.
radio A radio button.
button A menubar button.
The only difference between toggle and radio buttons is
how they are displayed. But for consistency, a toggle
button should be used when there is one option whose
value can be turned on or off, and radio buttons should
be used when there is a set of mutually exclusive
options. When using a group of radio buttons, you
should arrange for no more than one to be marked as
selected at a time.
:selected <form> Meaningful only when STYLE is `toggle', `radio' or
`button'. This specifies whether the button will be in
the selected or unselected state.
:included <form> This can be used to control the visibility of a menu or
menu item. The form is evaluated and the menu or menu
item is only displayed if the result is non-nil.
:config <symbol> This is an efficient shorthand for
:included (memq symbol menubar-configuration)
See the variable `menubar-configuration'.
:filter <function> A menu filter can only be used at the beginning of a
submenu description (i.e. not in a menu item itself).
(Remember that most of the keywords can take evaluated
expressions as well as constants.) The filter is used to
incrementally create a submenu only when it is selected
by the user and not every time the menubar is activated.
The filter function is passed the list of menu items in
the submenu and must return the modified list to be
actually used. The filter MUST NOT destructively modify
the list of menu items passed to it. It is called only
when the menu is about to be displayed, so other menus
may already be displayed. Vile and terrible things will
happen if a menu filter function changes the current
buffer, window, or frame. It also should not raise,
lower, or iconify any frames. Basically, the filter
function should have no side-effects.
:key-sequence keys Used in FSF Emacs as an hint to an equivalent keybinding.
Ignored by XEmacs for easymenu.el compatibility.
(XEmacs computes this information automatically.)
:filter file-menu-filter ; file-menu-filter is a function that takes
; one argument (a list of menu items) and
; returns a list of menu items
[ "Save %_As..." write-file t ]
[ "%_Revert Buffer" revert-buffer (buffer-modified-p) ]
[ "R%_ead Only" toggle-read-only :style toggle
:selected buffer-read-only ]
See menubar-items.el for many more examples.
After the menubar is clicked upon, but before any menus are popped up,
the functions on the `activate-menubar-hook' are invoked to make top-level
changes to the menus and menubar. Note, however, that the use of menu
filters (using the :filter keyword) is usually a more efficient way to
dynamically alter or sensitize menus.
Cheers =8-} Mike
Friede, Völkerverständigung und überhaupt blabla