Commit 75e8f9d2 authored by Chong Yidong's avatar Chong Yidong
Browse files

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
parent 5c788776
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
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 ] ... ]
Where KEYWORD is one of the symbols defined below.
:keys KEYS
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 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.
: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'.
: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'.
:label FORM
[ NAME CALLBACK [ KEYWORD ARG ]... ]
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).
where NAME and CALLBACK have the same meanings as above, and each
optional KEYWORD and ARG pair should be one of the following:
:suffix FORM
: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.
FORM is an expression that will be dynamically evaluated and whose
value will be concatenated to the menu entry's label.
: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.
:style STYLE
: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'.
STYLE is a symbol describing the type of menu item. The following are
defined:
: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'.
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.
:label FORM
FORM is an expression that is dynamically evaluated and whose
value serves as the menu item's label (the default is NAME).
:selected SELECTED
:suffix FORM
FORM is an expression that is dynamically evaluated and whose
value is concatenated with the menu entry's label.
SELECTED is an expression; the checkbox or radio button is selected
whenever this expression's value is non-nil.
: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).
:help HELP
:selected SELECTED
SELECTED is an expression; the checkbox or radio button is
selected whenever the expression's value is non-nil.
HELP is a string, the help to display for the menu item.
: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.
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.
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))
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment