Improve documentation of easy-menu-define.
* lisp/emacs-lisp/easymenu.el (easy-menu-define): Doc fix. * doc/lispref/keymaps.texi (Toolkit Differences): Node deleted. (Easy Menu): New node. Fixes: debbugs:12628
This commit is contained in:
Chong Yidong
parent
5c78877693
commit
75e8f9d2de
5 changed files with 213 additions and 120 deletions
|
|
@ -1,3 +1,8 @@
|
|||
2012-10-24 Chong Yidong <cyd@gnu.org>
|
||||
|
||||
* keymaps.texi (Toolkit Differences): Node deleted.
|
||||
(Easy Menu): New node.
|
||||
|
||||
2012-10-23 Stefan Monnier <monnier@iro.umontreal.ca>
|
||||
|
||||
* hooks.texi (Standard Hooks): Clarify that -hooks is deprecated.
|
||||
|
|
|
|||
|
|
@ -800,17 +800,14 @@ Menu Keymaps
|
|||
* Menu Bar:: How to customize the menu bar.
|
||||
* Tool Bar:: A tool bar is a row of images.
|
||||
* Modifying Menus:: How to add new items to a menu.
|
||||
* Easy Menu:: A convenience macro for defining menus.
|
||||
|
||||
Defining Menus
|
||||
|
||||
* Simple Menu Items:: A simple kind of menu key binding,
|
||||
limited in capabilities.
|
||||
* Extended Menu Items:: More powerful menu item definitions
|
||||
let you specify keywords to enable
|
||||
various features.
|
||||
* Simple Menu Items:: A simple kind of menu key binding.
|
||||
* Extended Menu Items:: More complex menu item definitions.
|
||||
* Menu Separators:: Drawing a horizontal line through a menu.
|
||||
* Alias Menu Items:: Using command aliases in menu items.
|
||||
* Toolkit Differences:: Not all toolkits provide the same features.
|
||||
|
||||
Major and Minor Modes
|
||||
|
||||
|
|
|
|||
|
|
@ -1963,13 +1963,14 @@ is active for the next input event, that activates the keyboard menu
|
|||
feature.
|
||||
|
||||
@menu
|
||||
* Defining Menus:: How to make a keymap that defines a menu.
|
||||
* Mouse Menus:: How users actuate the menu with the mouse.
|
||||
* Keyboard Menus:: How users actuate the menu with the keyboard.
|
||||
* Menu Example:: Making a simple menu.
|
||||
* Menu Bar:: How to customize the menu bar.
|
||||
* Tool Bar:: A tool bar is a row of images.
|
||||
* Modifying Menus:: How to add new items to a menu.
|
||||
* Defining Menus:: How to make a keymap that defines a menu.
|
||||
* Mouse Menus:: How users actuate the menu with the mouse.
|
||||
* Keyboard Menus:: How users actuate the menu with the keyboard.
|
||||
* Menu Example:: Making a simple menu.
|
||||
* Menu Bar:: How to customize the menu bar.
|
||||
* Tool Bar:: A tool bar is a row of images.
|
||||
* Modifying Menus:: How to add new items to a menu.
|
||||
* Easy Menu:: A convenience macro for making menus.
|
||||
@end menu
|
||||
|
||||
@node Defining Menus
|
||||
|
|
@ -2015,17 +2016,12 @@ an existing menu, you can specify its position in the menu using
|
|||
@code{define-key-after} (@pxref{Modifying Menus}).
|
||||
|
||||
@menu
|
||||
* Simple Menu Items:: A simple kind of menu key binding,
|
||||
limited in capabilities.
|
||||
* Extended Menu Items:: More powerful menu item definitions
|
||||
let you specify keywords to enable
|
||||
various features.
|
||||
* Simple Menu Items:: A simple kind of menu key binding.
|
||||
* Extended Menu Items:: More complex menu item definitions.
|
||||
* Menu Separators:: Drawing a horizontal line through a menu.
|
||||
* Alias Menu Items:: Using command aliases in menu items.
|
||||
* Toolkit Differences:: Not all toolkits provide the same features.
|
||||
@end menu
|
||||
|
||||
|
||||
@node Simple Menu Items
|
||||
@subsubsection Simple Menu Items
|
||||
|
||||
|
|
@ -2312,28 +2308,6 @@ itself). To request this, give the alias symbol a non-@code{nil}
|
|||
causes menu items for @code{make-read-only} and @code{make-writable} to
|
||||
show the keyboard bindings for @code{read-only-mode}.
|
||||
|
||||
@node Toolkit Differences
|
||||
@subsubsection Toolkit Differences
|
||||
|
||||
The various toolkits with which you can build Emacs do not all support
|
||||
the same set of features for menus. Some code works as expected with
|
||||
one toolkit, but not under another.
|
||||
|
||||
One example is menu actions or buttons in a top-level menu bar. The
|
||||
following works with the Lucid toolkit or on MS Windows, but not with
|
||||
GTK or Nextstep, where clicking on the item has no effect.
|
||||
|
||||
@example
|
||||
(defun menu-action-greet ()
|
||||
(interactive)
|
||||
(message "Hello Emacs User!"))
|
||||
|
||||
(defun top-level-menu ()
|
||||
(interactive)
|
||||
(define-key lisp-interaction-mode-map [menu-bar m]
|
||||
'(menu-item "Action Button" menu-action-greet)))
|
||||
@end example
|
||||
|
||||
@node Mouse Menus
|
||||
@subsection Menus and the Mouse
|
||||
|
||||
|
|
@ -2813,3 +2787,125 @@ menu of Shell mode, after the item @code{break}:
|
|||
[work] '("Work" . work-command) 'break)
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
@node Easy Menu
|
||||
@subsection Easy Menu
|
||||
|
||||
The following macro provides a convenient way to define pop-up menus
|
||||
and/or menu bar menus.
|
||||
|
||||
@defmac easy-menu-define symbol maps doc menu
|
||||
This macro defines a pop-up menu and/or menu bar submenu, whose
|
||||
contents are given by @var{menu}.
|
||||
|
||||
If @var{symbol} is non-@code{nil}, it should be a symbol; then this
|
||||
macro defines @var{symbol} as a function for popping up the menu
|
||||
(@pxref{Pop-Up Menus}), with @var{doc} as its documentation string.
|
||||
@var{symbol} should not be quoted.
|
||||
|
||||
Regardless of the value of @var{symbol}, if @var{maps} is a keymap,
|
||||
the menu is added to that keymap, as a top-level menu for the menu bar
|
||||
(@pxref{Menu Bar}). It can also be a list of keymaps, in which case
|
||||
the menu is added separately to each of those keymaps.
|
||||
|
||||
The first element of @var{menu} must be a string, which serves as the
|
||||
menu label. It may be followed by any number of the following
|
||||
keyword-argument pairs:
|
||||
|
||||
@table @code
|
||||
@item :filter @var{function}
|
||||
@var{function} must be a function which, if called with one
|
||||
argument---the list of the other menu items---returns the actual items
|
||||
to be displayed in the menu.
|
||||
|
||||
@item :visible @var{include}
|
||||
@var{include} is an expression; if it evaluates to @code{nil}, the
|
||||
menu is made invisible. @code{:included} is an alias for
|
||||
@code{:visible}.
|
||||
|
||||
@item :active @var{enable}
|
||||
@var{enable} is an expression; if it evaluates to @code{nil}, the menu
|
||||
is not selectable. @code{:enable} is an alias for @code{:active}.
|
||||
@end table
|
||||
|
||||
The remaining elements in @var{menu} are menu items.
|
||||
|
||||
A menu item can be a vector of three elements, @code{[@var{name}
|
||||
@var{callback} @var{enable}]}. @var{name} is the menu item name (a
|
||||
string). @var{callback} is a command to run, or an expression to
|
||||
evaluate, when the item is chosen. @var{enable} is an expression; if
|
||||
it evaluates to @code{nil}, the item is disabled for selection.
|
||||
|
||||
Alternatively, a menu item may have the form:
|
||||
|
||||
@smallexample
|
||||
[ @var{name} @var{callback} [ @var{keyword} @var{arg} ]... ]
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
where @var{name} and @var{callback} have the same meanings as above,
|
||||
and each optional @var{keyword} and @var{arg} pair should be one of
|
||||
the following:
|
||||
|
||||
@table @code
|
||||
@item :keys @var{keys}
|
||||
@var{keys} is a keyboard equivalent to the menu item (a string). This
|
||||
is normally not needed, as keyboard equivalents are computed
|
||||
automatically. @var{keys} is expanded with
|
||||
@code{substitute-command-keys} before it is displayed (@pxref{Keys in
|
||||
Documentation}).
|
||||
|
||||
@item :key-sequence @var{keys}
|
||||
@var{keys} is a hint for speeding up Emacs's first display of the
|
||||
menu. It should be nil if you know that the menu item has no keyboard
|
||||
equivalent; otherwise it should be a string or vector specifying a
|
||||
keyboard equivalent for the menu item.
|
||||
|
||||
@item :active @var{enable}
|
||||
@var{enable} is an expression; if it evaluates to @code{nil}, the item
|
||||
is make unselectable.. @code{:enable} is an alias for @code{:active}.
|
||||
|
||||
@item :visible @var{include}
|
||||
@var{include} is an expression; if it evaluates to @code{nil}, the
|
||||
item is made invisible. @code{:included} is an alias for
|
||||
@code{:visible}.
|
||||
|
||||
@item :label @var{form}
|
||||
@var{form} is an expression that is evaluated to obtain a value which
|
||||
serves as the menu item's label (the default is @var{name}).
|
||||
|
||||
@item :suffix @var{form}
|
||||
@var{form} is an expression that is dynamically evaluated and whose
|
||||
value is concatenated with the menu entry's label.
|
||||
|
||||
@item :style @var{style}
|
||||
@var{style} is a symbol describing the type of menu item; it should be
|
||||
@code{toggle} (a checkbox), or @code{radio} (a radio button), or
|
||||
anything else (meaning an ordinary menu item).
|
||||
|
||||
@item :selected @var{selected}
|
||||
@var{selected} is an expression; the checkbox or radio button is
|
||||
selected whenever the expression's value is non-nil.
|
||||
|
||||
@item :help @var{help}
|
||||
@var{help} is a string describing the menu item.
|
||||
@end table
|
||||
|
||||
Alternatively, a menu item can be a string. Then that string appears
|
||||
in the menu as unselectable text. A string consisting of dashes is
|
||||
displayed as a separator (@pxref{Menu Separators}).
|
||||
|
||||
Alternatively, a menu item can be a list with the same format as
|
||||
@var{menu}. This is a submenu.
|
||||
@end defmac
|
||||
|
||||
Here is an example of using @code{easy-menu-define} to define a menu
|
||||
similar to the one defined in the example in @ref{Menu Bar}:
|
||||
|
||||
@example
|
||||
(easy-menu-define words-menu global-map
|
||||
"Menu for word navigation commands."
|
||||
'("Words"
|
||||
["Forward word" forward-word]
|
||||
["Backward word" backward-word]))
|
||||
@end example
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
2012-10-24 Chong Yidong <cyd@gnu.org>
|
||||
|
||||
* emacs-lisp/easymenu.el (easy-menu-define): Doc fix (Bug#12628).
|
||||
|
||||
2012-10-24 Stefan Monnier <monnier@iro.umontreal.ca>
|
||||
|
||||
* minibuffer.el (completion--all-sorted-completions-location): New var.
|
||||
|
|
|
|||
|
|
@ -44,110 +44,101 @@ menus, turn this variable off, otherwise it is probably better to keep it on.")
|
|||
|
||||
;;;###autoload
|
||||
(defmacro easy-menu-define (symbol maps doc menu)
|
||||
"Define a menu bar submenu in maps MAPS, according to MENU.
|
||||
"Define a pop-up menu and/or menu bar menu specified by MENU.
|
||||
If SYMBOL is non-nil, define SYMBOL as a function to pop up the
|
||||
submenu defined by MENU, with DOC as its doc string.
|
||||
|
||||
If SYMBOL is non-nil, store the menu keymap in the value of SYMBOL,
|
||||
and define SYMBOL as a function to pop up the menu, with DOC as its doc string.
|
||||
If SYMBOL is nil, just store the menu keymap into MAPS.
|
||||
MAPS, if non-nil, should be a keymap or a list of keymaps; add
|
||||
the submenu defined by MENU to the keymap or each of the keymaps,
|
||||
as a top-level menu bar item.
|
||||
|
||||
The first element of MENU must be a string. It is the menu bar item name.
|
||||
It may be followed by the following keyword argument pairs
|
||||
The first element of MENU must be a string. It is the menu bar
|
||||
item name. It may be followed by the following keyword argument
|
||||
pairs:
|
||||
|
||||
:filter FUNCTION
|
||||
:filter FUNCTION
|
||||
FUNCTION must be a function which, if called with one
|
||||
argument---the list of the other menu items---returns the
|
||||
items to actually display.
|
||||
|
||||
FUNCTION is a function with one argument, the rest of menu items.
|
||||
It returns the remaining items of the displayed menu.
|
||||
:visible INCLUDE
|
||||
INCLUDE is an expression. The menu is visible if the
|
||||
expression evaluates to a non-nil value. `:included' is an
|
||||
alias for `:visible'.
|
||||
|
||||
:visible INCLUDE
|
||||
:active ENABLE
|
||||
ENABLE is an expression. The menu is enabled for selection
|
||||
if the expression evaluates to a non-nil value. `:enable' is
|
||||
an alias for `:active'.
|
||||
|
||||
INCLUDE is an expression; this menu is only visible if this
|
||||
expression has a non-nil value. `:included' is an alias for `:visible'.
|
||||
The rest of the elements in MENU are menu items.
|
||||
A menu item can be a vector of three elements:
|
||||
|
||||
:active ENABLE
|
||||
|
||||
ENABLE is an expression; the menu is enabled for selection whenever
|
||||
this expression's value is non-nil. `:enable' is an alias for `:active'.
|
||||
|
||||
The rest of the elements in MENU, are menu items.
|
||||
|
||||
A menu item is usually a vector of three elements: [NAME CALLBACK ENABLE]
|
||||
[NAME CALLBACK ENABLE]
|
||||
|
||||
NAME is a string--the menu item name.
|
||||
|
||||
CALLBACK is a command to run when the item is chosen,
|
||||
or a list to evaluate when the item is chosen.
|
||||
CALLBACK is a command to run when the item is chosen, or an
|
||||
expression to evaluate when the item is chosen.
|
||||
|
||||
ENABLE is an expression; the item is enabled for selection
|
||||
whenever this expression's value is non-nil.
|
||||
ENABLE is an expression; the item is enabled for selection if the
|
||||
expression evaluates to a non-nil value.
|
||||
|
||||
Alternatively, a menu item may have the form:
|
||||
|
||||
[ NAME CALLBACK [ KEYWORD ARG ] ... ]
|
||||
[ NAME CALLBACK [ KEYWORD ARG ]... ]
|
||||
|
||||
Where KEYWORD is one of the symbols defined below.
|
||||
where NAME and CALLBACK have the same meanings as above, and each
|
||||
optional KEYWORD and ARG pair should be one of the following:
|
||||
|
||||
:keys KEYS
|
||||
:keys KEYS
|
||||
KEYS is a string; a keyboard equivalent to the menu item.
|
||||
This is normally not needed because keyboard equivalents are
|
||||
usually computed automatically. KEYS is expanded with
|
||||
`substitute-command-keys' before it is used.
|
||||
|
||||
KEYS is a string; a complex keyboard equivalent to this menu item.
|
||||
This is normally not needed because keyboard equivalents are usually
|
||||
computed automatically.
|
||||
KEYS is expanded with `substitute-command-keys' before it is used.
|
||||
:key-sequence KEYS
|
||||
KEYS is a hint for speeding up Emacs's first display of the
|
||||
menu. It should be nil if you know that the menu item has no
|
||||
keyboard equivalent; otherwise it should be a string or
|
||||
vector specifying a keyboard equivalent for the menu item.
|
||||
|
||||
:key-sequence KEYS
|
||||
:active ENABLE
|
||||
ENABLE is an expression; the item is enabled for selection
|
||||
whenever this expression's value is non-nil. `:enable' is an
|
||||
alias for `:active'.
|
||||
|
||||
KEYS is nil, a string or a vector; nil or a keyboard equivalent to this
|
||||
menu item.
|
||||
This is a hint that will considerably speed up Emacs's first display of
|
||||
a menu. Use `:key-sequence nil' when you know that this menu item has no
|
||||
keyboard equivalent.
|
||||
:visible INCLUDE
|
||||
INCLUDE is an expression; this item is only visible if this
|
||||
expression has a non-nil value. `:included' is an alias for
|
||||
`:visible'.
|
||||
|
||||
:active ENABLE
|
||||
:label FORM
|
||||
FORM is an expression that is dynamically evaluated and whose
|
||||
value serves as the menu item's label (the default is NAME).
|
||||
|
||||
ENABLE is an expression; the item is enabled for selection whenever
|
||||
this expression's value is non-nil. `:enable' is an alias for `:active'.
|
||||
:suffix FORM
|
||||
FORM is an expression that is dynamically evaluated and whose
|
||||
value is concatenated with the menu entry's label.
|
||||
|
||||
:visible INCLUDE
|
||||
:style STYLE
|
||||
STYLE is a symbol describing the type of menu item; it should
|
||||
be `toggle' (a checkbox), or `radio' (a radio button), or any
|
||||
other value (meaning an ordinary menu item).
|
||||
|
||||
INCLUDE is an expression; this item is only visible if this
|
||||
expression has a non-nil value. `:included' is an alias for `:visible'.
|
||||
:selected SELECTED
|
||||
SELECTED is an expression; the checkbox or radio button is
|
||||
selected whenever the expression's value is non-nil.
|
||||
|
||||
:label FORM
|
||||
:help HELP
|
||||
HELP is a string, the help to display for the menu item.
|
||||
|
||||
FORM is an expression that will be dynamically evaluated and whose
|
||||
value will be used for the menu entry's text label (the default is NAME).
|
||||
Alternatively, a menu item can be a string. Then that string
|
||||
appears in the menu as unselectable text. A string consisting
|
||||
solely of dashes is displayed as a menu separator.
|
||||
|
||||
:suffix FORM
|
||||
|
||||
FORM is an expression that will be dynamically evaluated and whose
|
||||
value will be concatenated to the menu entry's label.
|
||||
|
||||
:style STYLE
|
||||
|
||||
STYLE is a symbol describing the type of menu item. The following are
|
||||
defined:
|
||||
|
||||
toggle: A checkbox.
|
||||
Prepend the name with `(*) ' or `( ) ' depending on if selected or not.
|
||||
radio: A radio button.
|
||||
Prepend the name with `[X] ' or `[ ] ' depending on if selected or not.
|
||||
button: Surround the name with `[' and `]'. Use this for an item in the
|
||||
menu bar itself.
|
||||
anything else means an ordinary menu item.
|
||||
|
||||
:selected SELECTED
|
||||
|
||||
SELECTED is an expression; the checkbox or radio button is selected
|
||||
whenever this expression's value is non-nil.
|
||||
|
||||
:help HELP
|
||||
|
||||
HELP is a string, the help to display for the menu item.
|
||||
|
||||
A menu item can be a string. Then that string appears in the menu as
|
||||
unselectable text. A string consisting solely of hyphens is displayed
|
||||
as a solid horizontal line.
|
||||
|
||||
A menu item can be a list with the same format as MENU. This is a submenu."
|
||||
Alternatively, a menu item can be a list with the same format as
|
||||
MENU. This is a submenu."
|
||||
(declare (indent defun) (debug (symbolp body)))
|
||||
`(progn
|
||||
,(if symbol `(defvar ,symbol nil ,doc))
|
||||
|
|
|
|||
Loading…
Reference in a new issue