From: Chong Yidong Date: Wed, 24 Oct 2012 03:48:50 +0000 (+0800) Subject: Improve documentation of easy-menu-define. X-Git-Tag: emacs-24.2.90~209^2~95 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=75e8f9d2decbbebf7ffc20d17ff8676077071255;p=emacs.git 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 --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 26765e7a384..9142ef49b12 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2012-10-24 Chong Yidong + + * keymaps.texi (Toolkit Differences): Node deleted. + (Easy Menu): New node. + 2012-10-23 Stefan Monnier * hooks.texi (Standard Hooks): Clarify that -hooks is deprecated. diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index d46cb071bf7..1d1dab8faac 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -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 diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 9fa6193a804..8fe729d50f2 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -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 diff --git a/lisp/ChangeLog b/lisp/ChangeLog index c84d0110fc7..5b709c76c74 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,7 @@ +2012-10-24 Chong Yidong + + * emacs-lisp/easymenu.el (easy-menu-define): Doc fix (Bug#12628). + 2012-10-24 Stefan Monnier * minibuffer.el (completion--all-sorted-completions-location): New var. diff --git a/lisp/emacs-lisp/easymenu.el b/lisp/emacs-lisp/easymenu.el index 939fab78942..26a1fce2309 100644 --- a/lisp/emacs-lisp/easymenu.el +++ b/lisp/emacs-lisp/easymenu.el @@ -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))