[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r110645: Improve documentation of eas
From: |
Chong Yidong |
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r110645: Improve documentation of easy-menu-define. |
Date: |
Wed, 24 Oct 2012 11:48:50 +0800 |
User-agent: |
Bazaar (2.5.0) |
------------------------------------------------------------
revno: 110645
fixes bug: http://debbugs.gnu.org/12628
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Wed 2012-10-24 11:48:50 +0800
message:
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.
modified:
doc/lispref/ChangeLog
doc/lispref/elisp.texi
doc/lispref/keymaps.texi
lisp/ChangeLog
lisp/emacs-lisp/easymenu.el
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog 2012-10-23 15:06:07 +0000
+++ b/doc/lispref/ChangeLog 2012-10-24 03:48:50 +0000
@@ -1,3 +1,8 @@
+2012-10-24 Chong Yidong <address@hidden>
+
+ * keymaps.texi (Toolkit Differences): Node deleted.
+ (Easy Menu): New node.
+
2012-10-23 Stefan Monnier <address@hidden>
* hooks.texi (Standard Hooks): Clarify that -hooks is deprecated.
=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi 2012-09-30 09:18:38 +0000
+++ b/doc/lispref/elisp.texi 2012-10-24 03:48:50 +0000
@@ -800,17 +800,14 @@
* 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
=== modified file 'doc/lispref/keymaps.texi'
--- a/doc/lispref/keymaps.texi 2012-10-23 02:23:39 +0000
+++ b/doc/lispref/keymaps.texi 2012-10-24 03:48:50 +0000
@@ -1963,13 +1963,14 @@
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 @@
@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 @@
causes menu items for @code{make-read-only} and @code{make-writable} to
show the keyboard bindings for @code{read-only-mode}.
address@hidden Toolkit Differences
address@hidden 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.
-
address@hidden
-(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)))
address@hidden example
-
@node Mouse Menus
@subsection Menus and the Mouse
@@ -2813,3 +2787,125 @@
[work] '("Work" . work-command) 'break)
@end example
@end defun
+
address@hidden Easy Menu
address@hidden Easy Menu
+
+ The following macro provides a convenient way to define pop-up menus
+and/or menu bar menus.
+
address@hidden 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 address@hidden, 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.
address@hidden 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:
+
address@hidden @code
address@hidden :filter @var{function}
address@hidden 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.
+
address@hidden :visible @var{include}
address@hidden is an expression; if it evaluates to @code{nil}, the
+menu is made invisible. @code{:included} is an alias for
address@hidden:visible}.
+
address@hidden :active @var{enable}
address@hidden is an expression; if it evaluates to @code{nil}, the menu
+is not selectable. @code{:enable} is an alias for @code{:active}.
address@hidden table
+
+The remaining elements in @var{menu} are menu items.
+
+A menu item can be a vector of three elements, @address@hidden
address@hidden @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:
+
address@hidden
+ [ @var{name} @var{callback} [ @var{keyword} @var{arg} ]... ]
address@hidden smallexample
+
address@hidden
+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:
+
address@hidden @code
address@hidden :keys @var{keys}
address@hidden 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
address@hidden before it is displayed (@pxref{Keys in
+Documentation}).
+
address@hidden :key-sequence @var{keys}
address@hidden 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.
+
address@hidden :active @var{enable}
address@hidden is an expression; if it evaluates to @code{nil}, the item
+is make unselectable.. @code{:enable} is an alias for @code{:active}.
+
address@hidden :visible @var{include}
address@hidden is an expression; if it evaluates to @code{nil}, the
+item is made invisible. @code{:included} is an alias for
address@hidden:visible}.
+
address@hidden :label @var{form}
address@hidden is an expression that is evaluated to obtain a value which
+serves as the menu item's label (the default is @var{name}).
+
address@hidden :suffix @var{form}
address@hidden is an expression that is dynamically evaluated and whose
+value is concatenated with the menu entry's label.
+
address@hidden :style @var{style}
address@hidden is a symbol describing the type of menu item; it should be
address@hidden (a checkbox), or @code{radio} (a radio button), or
+anything else (meaning an ordinary menu item).
+
address@hidden :selected @var{selected}
address@hidden is an expression; the checkbox or radio button is
+selected whenever the expression's value is non-nil.
+
address@hidden :help @var{help}
address@hidden is a string describing the menu item.
address@hidden 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
address@hidden This is a submenu.
address@hidden 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}:
+
address@hidden
+(easy-menu-define words-menu global-map
+ "Menu for word navigation commands."
+ '("Words"
+ ["Forward word" forward-word]
+ ["Backward word" backward-word]))
address@hidden example
=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog 2012-10-24 03:18:32 +0000
+++ b/lisp/ChangeLog 2012-10-24 03:48:50 +0000
@@ -1,3 +1,7 @@
+2012-10-24 Chong Yidong <address@hidden>
+
+ * emacs-lisp/easymenu.el (easy-menu-define): Doc fix (Bug#12628).
+
2012-10-24 Stefan Monnier <address@hidden>
* minibuffer.el (completion--all-sorted-completions-location): New var.
=== modified file 'lisp/emacs-lisp/easymenu.el'
--- a/lisp/emacs-lisp/easymenu.el 2012-09-14 03:55:16 +0000
+++ b/lisp/emacs-lisp/easymenu.el 2012-10-24 03:48:50 +0000
@@ -44,110 +44,101 @@
;;;###autoload
(defmacro easy-menu-define (symbol maps doc menu)
- "Define a menu bar submenu in maps MAPS, according to MENU.
-
-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.
-
-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
-
-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; this menu is only visible if this
-expression has a non-nil value. `:included' is an alias for `:visible'.
-
- :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]
+ "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.
+
+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:
+
+ :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.
+
+ :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'.
+
+ :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'.
+
+The rest of the elements in MENU are menu items.
+A menu item can be a vector of three elements:
+
+ [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
-
-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).
-
- :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."
+ [ NAME CALLBACK [ KEYWORD ARG ]... ]
+
+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 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.
+
+ :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.
+
+ :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
+ FORM is an expression that is dynamically evaluated and whose
+ value serves as the menu item's label (the default is NAME).
+
+ :suffix FORM
+ FORM is an expression that is dynamically evaluated and whose
+ value is concatenated with the menu entry's label.
+
+ :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).
+
+ :selected SELECTED
+ SELECTED is an expression; the checkbox or radio button is
+ selected whenever the expression's value is non-nil.
+
+ :help HELP
+ HELP is a string, the help to display for the menu item.
+
+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.
+
+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))
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r110645: Improve documentation of easy-menu-define.,
Chong Yidong <=