Add arch taglines
[bpt/emacs.git] / lisp / emacs-lisp / easymenu.el
CommitLineData
6a05d05f 1;;; easymenu.el --- support the easymenu interface for defining a menu
029b623a 2
5e5b3d41 3;; Copyright (C) 1994, 1996, 1998, 1999, 2000 Free Software Foundation, Inc.
029b623a 4
8df69fb0 5;; Keywords: emulations
6a05d05f 6;; Author: Richard Stallman <rms@gnu.org>
8df69fb0 7
029b623a
RS
8;; This file is part of GNU Emacs.
9
10;; GNU Emacs is free software; you can redistribute it and/or modify
11;; it under the terms of the GNU General Public License as published by
12;; the Free Software Foundation; either version 2, or (at your option)
13;; any later version.
14
15;; GNU Emacs is distributed in the hope that it will be useful,
16;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18;; GNU General Public License for more details.
19
20;; You should have received a copy of the GNU General Public License
b578f267
EN
21;; along with GNU Emacs; see the file COPYING. If not, write to the
22;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
23;; Boston, MA 02111-1307, USA.
029b623a 24
b578f267
EN
25;;; Commentary:
26
27;; This is compatible with easymenu.el by Per Abrahamsen
28;; but it is much simpler as it doesn't try to support other Emacs versions.
29;; The code was mostly derived from lmenu.el.
029b623a
RS
30
31;;; Code:
32
545128a8
RS
33(defcustom easy-menu-precalculate-equivalent-keybindings t
34 "Determine when equivalent key bindings are computed for easy-menu menus.
35It can take some time to calculate the equivalent key bindings that are shown
36in a menu. If the variable is on, then this calculation gives a (maybe
37noticeable) delay when a mode is first entered. If the variable is off, then
38this delay will come when a menu is displayed the first time. If you never use
39menus, turn this variable off, otherwise it is probably better to keep it on."
40 :type 'boolean
41 :group 'menu
42 :version "20.3")
43
0847e165 44(defsubst easy-menu-intern (s)
9ef2bee6 45 (if (stringp s) (intern (downcase s)) s))
0847e165 46
5edf6b55
SM
47;;;###autoload
48(put 'easy-menu-define 'lisp-indent-function 'defun)
a8226f67 49;;;###autoload
8df69fb0 50(defmacro easy-menu-define (symbol maps doc menu)
029b623a 51 "Define a menu bar submenu in maps MAPS, according to MENU.
74c7e66d
RS
52
53If SYMBOL is non-nil, store the menu keymap in the value of SYMBOL,
54and define SYMBOL as a function to pop up the menu, with DOC as its doc string.
55If SYMBOL is nil, just store the menu keymap into MAPS.
029b623a
RS
56
57The first element of MENU must be a string. It is the menu bar item name.
3de63fb6
RS
58It may be followed by the following keyword argument pairs
59
024bda02 60 :filter FUNCTION
3de63fb6 61
024bda02
RS
62FUNCTION is a function with one argument, the menu. It returns the actual
63menu displayed.
64
3de63fb6
RS
65 :visible INCLUDE
66
67INCLUDE is an expression; this menu is only visible if this
68expression has a non-nil value. `:include' is an alias for `:visible'.
69
70 :active ENABLE
71
72ENABLE is an expression; the menu is enabled for selection
73whenever this expression's value is non-nil.
74
75The rest of the elements in MENU, are menu items.
029b623a 76
8df69fb0 77A menu item is usually a vector of three elements: [NAME CALLBACK ENABLE]
029b623a 78
a8226f67 79NAME is a string--the menu item name.
029b623a 80
a8226f67
RS
81CALLBACK is a command to run when the item is chosen,
82or a list to evaluate when the item is chosen.
029b623a 83
5a51e0a6
RS
84ENABLE is an expression; the item is enabled for selection
85whenever this expression's value is non-nil.
8df69fb0 86
6c2599ed 87Alternatively, a menu item may have the form:
1ba15fe6
RS
88
89 [ NAME CALLBACK [ KEYWORD ARG ] ... ]
90
024bda02 91Where KEYWORD is one of the symbols defined below.
1ba15fe6
RS
92
93 :keys KEYS
94
95KEYS is a string; a complex keyboard equivalent to this menu item.
96This is normally not needed because keyboard equivalents are usually
97computed automatically.
3de63fb6
RS
98KEYS is expanded with `substitute-command-keys' before it is used.
99
100 :key-sequence KEYS
101
d0acce1e 102KEYS is nil, a string or a vector; nil or a keyboard equivalent to this
3de63fb6 103menu item.
d0acce1e 104This is a hint that will considerably speed up Emacs' first display of
3de63fb6
RS
105a menu. Use `:key-sequence nil' when you know that this menu item has no
106keyboard equivalent.
1ba15fe6
RS
107
108 :active ENABLE
109
110ENABLE is an expression; the item is enabled for selection
111whenever this expression's value is non-nil.
112
3de63fb6
RS
113 :included INCLUDE
114
115INCLUDE is an expression; this item is only visible if this
116expression has a non-nil value.
117
d0acce1e 118 :suffix FORM
1ba15fe6 119
d0acce1e
SM
120FORM is an expression that will be dynamically evaluated and whose
121value will be concatenated to the menu entry's NAME.
1ba15fe6 122
41e6ca7a 123 :style STYLE
6c2599ed 124
1ba15fe6 125STYLE is a symbol describing the type of menu item. The following are
6c2599ed 126defined:
1ba15fe6 127
e6a6d697 128toggle: A checkbox.
3de63fb6 129 Prepend the name with `(*) ' or `( ) ' depending on if selected or not.
e6a6d697 130radio: A radio button.
3de63fb6 131 Prepend the name with `[X] ' or `[ ] ' depending on if selected or not.
4d6d04b5 132button: Surround the name with `[' and `]'. Use this for an item in the
3de63fb6
RS
133 menu bar itself.
134anything else means an ordinary menu item.
1ba15fe6
RS
135
136 :selected SELECTED
137
138SELECTED is an expression; the checkbox or radio button is selected
139whenever this expression's value is non-nil.
1ba15fe6 140
25112054
GM
141 :help HELP
142
143HELP is a string, the help to display for the menu item.
144
a8226f67
RS
145A menu item can be a string. Then that string appears in the menu as
146unselectable text. A string consisting solely of hyphens is displayed
147as a solid horizontal line.
029b623a 148
3de63fb6 149A menu item can be a list with the same format as MENU. This is a submenu."
024bda02 150 `(progn
efc13f46 151 ,(if symbol `(defvar ,symbol nil ,doc))
024bda02 152 (easy-menu-do-define (quote ,symbol) ,maps ,doc ,menu)))
1ba15fe6 153
f39223a6 154;;;###autoload
1ba15fe6
RS
155(defun easy-menu-do-define (symbol maps doc menu)
156 ;; We can't do anything that might differ between Emacs dialects in
157 ;; `easy-menu-define' in order to make byte compiled files
158 ;; compatible. Therefore everything interesting is done in this
6c2599ed 159 ;; function.
d0acce1e 160 (let ((keymap (easy-menu-create-menu (car menu) (cdr menu))))
74c7e66d
RS
161 (when symbol
162 (set symbol keymap)
163 (fset symbol
164 `(lambda (event) ,doc (interactive "@e")
165 ;; FIXME: XEmacs uses popup-menu which calls the binding
166 ;; while x-popup-menu only returns the selection.
167 (x-popup-menu event
168 (or (and (symbolp ,symbol)
169 (funcall
170 (or (plist-get (get ,symbol 'menu-prop)
171 :filter)
172 'identity)
173 (symbol-function ,symbol)))
174 ,symbol)))))
d0acce1e 175 (mapcar (lambda (map)
0847e165 176 (define-key map (vector 'menu-bar (easy-menu-intern (car menu)))
d0acce1e
SM
177 (cons 'menu-item
178 (cons (car menu)
179 (if (not (symbolp keymap))
180 (list keymap)
181 (cons (symbol-function keymap)
182 (get keymap 'menu-prop)))))))
183 (if (keymapp maps) (list maps) maps))))
184
185(defun easy-menu-filter-return (menu &optional name)
024bda02
RS
186 "Convert MENU to the right thing to return from a menu filter.
187MENU is a menu as computed by `easy-menu-define' or `easy-menu-create-menu' or
188a symbol whose value is such a menu.
189In Emacs a menu filter must return a menu (a keymap), in XEmacs a filter must
3de63fb6 190return a menu items list (without menu name and keywords).
d0acce1e
SM
191This function returns the right thing in the two cases.
192If NAME is provided, it is used for the keymap."
e899e3de
SM
193 (cond
194 ((and (not (keymapp menu)) (consp menu))
d0acce1e
SM
195 ;; If it's a cons but not a keymap, then it can't be right
196 ;; unless it's an XEmacs menu.
197 (setq menu (easy-menu-create-menu (or name "") menu)))
e899e3de
SM
198 ((vectorp menu)
199 ;; It's just a menu entry.
200 (setq menu (cdr (easy-menu-convert-item menu)))))
201 menu)
029b623a 202
815d2127 203;;;###autoload
024bda02
RS
204(defun easy-menu-create-menu (menu-name menu-items)
205 "Create a menu called MENU-NAME with items described in MENU-ITEMS.
206MENU-NAME is a string, the name of the menu. MENU-ITEMS is a list of items
207possibly preceded by keyword pairs as described in `easy-menu-define'."
208 (let ((menu (make-sparse-keymap menu-name))
25112054 209 prop keyword arg label enable filter visible help)
024bda02 210 ;; Look for keywords.
b9f5db90
DL
211 (while (and menu-items
212 (cdr menu-items)
213 (keywordp (setq keyword (car menu-items))))
c78fb6a6
RS
214 (setq arg (cadr menu-items))
215 (setq menu-items (cddr menu-items))
216 (cond
d0acce1e
SM
217 ((eq keyword :filter)
218 (setq filter `(lambda (menu)
219 (easy-menu-filter-return (,arg menu) ,menu-name))))
3de63fb6
RS
220 ((eq keyword :active) (setq enable (or arg ''nil)))
221 ((eq keyword :label) (setq label arg))
25112054 222 ((eq keyword :help) (setq help arg))
3de63fb6
RS
223 ((or (eq keyword :included) (eq keyword :visible))
224 (setq visible (or arg ''nil)))))
4d6d04b5
DL
225 (if (equal visible ''nil)
226 nil ; Invisible menu entry, return nil.
c78fb6a6
RS
227 (if (and visible (not (easy-menu-always-true visible)))
228 (setq prop (cons :visible (cons visible prop))))
229 (if (and enable (not (easy-menu-always-true enable)))
230 (setq prop (cons :enable (cons enable prop))))
231 (if filter (setq prop (cons :filter (cons filter prop))))
25112054 232 (if help (setq prop (cons :help (cons help prop))))
c78fb6a6 233 (if label (setq prop (cons nil (cons label prop))))
d0acce1e
SM
234 (if filter
235 ;; The filter expects the menu in its XEmacs form and the pre-filter
236 ;; form will only be passed to the filter anyway, so we'd better
237 ;; not convert it at all (it will be converted on the fly by
238 ;; easy-menu-filter-return).
239 (setq menu menu-items)
240 (setq menu (append menu (mapcar 'easy-menu-convert-item menu-items))))
c78fb6a6 241 (when prop
d0acce1e 242 (setq menu (easy-menu-make-symbol menu 'noexp))
c78fb6a6
RS
243 (put menu 'menu-prop prop))
244 menu)))
029b623a 245
024bda02 246
3de63fb6 247;; Known button types.
024bda02 248(defvar easy-menu-button-prefix
c78fb6a6 249 '((radio . :radio) (toggle . :toggle)))
024bda02 250
c78fb6a6 251(defun easy-menu-do-add-item (menu item &optional before)
d0acce1e 252 (setq item (easy-menu-convert-item item))
9ef2bee6 253 (easy-menu-define-key menu (easy-menu-intern (car item)) (cdr item) before))
d0acce1e
SM
254
255(defvar easy-menu-converted-items-table (make-hash-table :test 'equal))
256
257(defun easy-menu-convert-item (item)
4d6d04b5
DL
258 "Memoize the value returned by `easy-menu-convert-item-1' called on ITEM.
259This makes key-shortcut-caching work a *lot* better when this
260conversion is done from within a filter.
261This also helps when the NAME of the entry is recreated each time:
262since the menu is built and traversed separately, the lookup
263would always fail because the key is `equal' but not `eq'."
d0acce1e
SM
264 (or (gethash item easy-menu-converted-items-table)
265 (puthash item (easy-menu-convert-item-1 item)
266 easy-menu-converted-items-table)))
267
268(defun easy-menu-convert-item-1 (item)
efc13f46
RS
269 "Parse an item description and convert it to a menu keymap element.
270ITEM defines an item as in `easy-menu-define'."
25112054 271 (let (name command label prop remove help)
024bda02 272 (cond
2c5c9cb9
GM
273 ((stringp item) ; An item or separator.
274 (setq label item))
275 ((consp item) ; A sub-menu
c78fb6a6
RS
276 (setq label (setq name (car item)))
277 (setq command (cdr item))
278 (if (not (keymapp command))
279 (setq command (easy-menu-create-menu name command)))
280 (if (null command)
281 ;; Invisible menu item. Don't insert into keymap.
282 (setq remove t)
283 (when (and (symbolp command) (setq prop (get command 'menu-prop)))
284 (when (null (car prop))
285 (setq label (cadr prop))
286 (setq prop (cddr prop)))
287 (setq command (symbol-function command)))))
3de63fb6 288 ((vectorp item) ; An item.
545128a8
RS
289 (let* ((ilen (length item))
290 (active (if (> ilen 2) (or (aref item 2) ''nil) t))
291 (no-name (not (symbolp (setq command (aref item 1)))))
292 cache cache-specified)
c78fb6a6
RS
293 (setq label (setq name (aref item 0)))
294 (if no-name (setq command (easy-menu-make-symbol command)))
b9f5db90 295 (if (keywordp active)
c78fb6a6
RS
296 (let ((count 2)
297 keyword arg suffix visible style selected keys)
298 (setq active nil)
545128a8 299 (while (> ilen count)
024bda02
RS
300 (setq keyword (aref item count))
301 (setq arg (aref item (1+ count)))
302 (setq count (+ 2 count))
303 (cond
3de63fb6
RS
304 ((or (eq keyword :included) (eq keyword :visible))
305 (setq visible (or arg ''nil)))
c78fb6a6
RS
306 ((eq keyword :key-sequence)
307 (setq cache arg cache-specified t))
308 ((eq keyword :keys) (setq keys arg no-name nil))
309 ((eq keyword :label) (setq label arg))
310 ((eq keyword :active) (setq active (or arg ''nil)))
25112054 311 ((eq keyword :help) (setq prop (cons :help (cons arg prop))))
c78fb6a6
RS
312 ((eq keyword :suffix) (setq suffix arg))
313 ((eq keyword :style) (setq style arg))
314 ((eq keyword :selected) (setq selected (or arg ''nil)))))
3de63fb6
RS
315 (if suffix
316 (setq label
317 (if (stringp suffix)
318 (if (stringp label) (concat label " " suffix)
319 (list 'concat label (concat " " suffix)))
320 (if (stringp label)
321 (list 'concat (concat label " ") suffix)
322 (list 'concat label " " suffix)))))
323 (cond
324 ((eq style 'button)
325 (setq label (if (stringp label) (concat "[" label "]")
326 (list 'concat "[" label "]"))))
327 ((and selected
328 (setq style (assq style easy-menu-button-prefix)))
329 (setq prop (cons :button
330 (cons (cons (cdr style) selected) prop)))))
c78fb6a6
RS
331 (when (stringp keys)
332 (if (string-match "^[^\\]*\\(\\\\\\[\\([^]]+\\)]\\)[^\\]*$"
333 keys)
334 (let ((prefix
335 (if (< (match-beginning 0) (match-beginning 1))
336 (substring keys 0 (match-beginning 1))))
337 (postfix
338 (if (< (match-end 1) (match-end 0))
339 (substring keys (match-end 1))))
26647ce2 340 (cmd (intern (match-string 2 keys))))
545128a8
RS
341 (setq keys (and (or prefix postfix)
342 (cons prefix postfix)))
c78fb6a6 343 (setq keys
545128a8
RS
344 (and (or keys (not (eq command cmd)))
345 (cons cmd keys))))
c78fb6a6
RS
346 (setq cache-specified nil))
347 (if keys (setq prop (cons :keys (cons keys prop)))))
348 (if (and visible (not (easy-menu-always-true visible)))
349 (if (equal visible ''nil)
350 ;; Invisible menu item. Don't insert into keymap.
351 (setq remove t)
352 (setq prop (cons :visible (cons visible prop)))))))
353 (if (and active (not (easy-menu-always-true active)))
354 (setq prop (cons :enable (cons active prop))))
355 (if (and (or no-name cache-specified)
356 (or (null cache) (stringp cache) (vectorp cache)))
357 (setq prop (cons :key-sequence (cons cache prop))))))
a2c896c3 358 (t (error "Invalid menu item in easymenu")))
3a4f3f86
SM
359 ;; `intern' the name so as to merge multiple entries with the same name.
360 ;; It also makes it easier/possible to lookup/change menu bindings
361 ;; via keymap functions.
0847e165 362 (cons (easy-menu-intern name)
3a4f3f86
SM
363 (and (not remove)
364 (cons 'menu-item
365 (cons label
366 (and name
367 (cons command prop))))))))
3de63fb6 368
c78fb6a6 369(defun easy-menu-define-key (menu key item &optional before)
4d6d04b5 370 "Add binding in MENU for KEY => ITEM. Similar to `define-key-after'.
9ef2bee6
RS
371If KEY is not nil then delete any duplications.
372If ITEM is nil, then delete the definition of KEY.
373
374Optional argument BEFORE is nil or a key in MENU. If BEFORE is not nil,
375put binding before the item in MENU named BEFORE; otherwise,
376if a binding for KEY is already present in MENU, just change it;
377otherwise put the new binding last in MENU.
378BEFORE can be either a string (menu item name) or a symbol
379\(the fake function key for the menu item).
380KEY does not have to be a symbol, and comparison is done with equal."
c78fb6a6 381 (let ((inserted (null item)) ; Fake already inserted.
d8868253 382 tail done)
d5660985
RS
383 (while (not done)
384 (cond
385 ((or (setq done (or (null (cdr menu)) (keymapp (cdr menu))))
9ef2bee6 386 (and before (easy-menu-name-match before (cadr menu))))
c78fb6a6 387 ;; If key is nil, stop here, otherwise keep going past the
d5660985
RS
388 ;; inserted element so we can delete any duplications that come
389 ;; later.
c78fb6a6 390 (if (null key) (setq done t))
d5660985 391 (unless inserted ; Don't insert more than once.
c78fb6a6 392 (setcdr menu (cons (cons key item) (cdr menu)))
d5660985 393 (setq inserted t)
d8868253
RS
394 (setq menu (cdr menu)))
395 (setq menu (cdr menu)))
c78fb6a6 396 ((and key (equal (car-safe (cadr menu)) key))
d8868253
RS
397 (if (or inserted ; Already inserted or
398 (and before ; wanted elsewhere and
399 (setq tail (cddr menu)) ; not last item and not
400 (not (keymapp tail))
9ef2bee6
RS
401 (not (easy-menu-name-match
402 before (car tail))))) ; in position
c78fb6a6
RS
403 (setcdr menu (cddr menu)) ; Remove item.
404 (setcdr (cadr menu) item) ; Change item.
d8868253
RS
405 (setq inserted t)
406 (setq menu (cdr menu))))
407 (t (setq menu (cdr menu)))))))
6c2599ed 408
9ef2bee6
RS
409(defun easy-menu-name-match (name item)
410 "Return t if NAME is the name of menu item ITEM.
411NAME can be either a string, or a symbol."
412 (if (consp item)
95673002 413 (if (symbolp name)
9ef2bee6
RS
414 (eq (car-safe item) name)
415 (if (stringp name)
dd9b5663 416 ;; Match against the text that is displayed to the user.
26647ce2
SM
417 (or (condition-case nil (member-ignore-case name item)
418 (error nil)) ;`item' might not be a proper list.
dd9b5663
JR
419 ;; Also check the string version of the symbol name,
420 ;; for backwards compatibility.
26647ce2
SM
421 (eq (car-safe item) (intern name))
422 (eq (car-safe item) (easy-menu-intern name)))))))
9ef2bee6 423
c78fb6a6 424(defun easy-menu-always-true (x)
9ef2bee6 425 "Return true if form X never evaluates to nil."
c78fb6a6
RS
426 (if (consp x) (and (eq (car x) 'quote) (cadr x))
427 (or (eq x t) (not (symbolp x)))))
024bda02
RS
428
429(defvar easy-menu-item-count 0)
430
d0acce1e
SM
431(defun easy-menu-make-symbol (callback &optional noexp)
432 "Return a unique symbol with CALLBACK as function value.
433When non-nil, NOEXP indicates that CALLBACK cannot be an expression
434\(i.e. does not need to be turned into a function)."
024bda02
RS
435 (let ((command
436 (make-symbol (format "menu-function-%d" easy-menu-item-count))))
437 (setq easy-menu-item-count (1+ easy-menu-item-count))
438 (fset command
95673002 439 (if (or (keymapp callback) (functionp callback) noexp) callback
c78fb6a6 440 `(lambda () (interactive) ,callback)))
024bda02
RS
441 command))
442
168b2d0d 443;;;###autoload
024bda02 444(defun easy-menu-change (path name items &optional before)
88153c47 445 "Change menu found at PATH as item NAME to contain ITEMS.
fd43ede0
KH
446PATH is a list of strings for locating the menu that
447should contain a submenu named NAME.
448ITEMS is a list of menu items, as in `easy-menu-define'.
449These items entirely replace the previous items in that submenu.
450
451If the menu located by PATH has no submenu named NAME, add one.
452If the optional argument BEFORE is present, add it just before
453the submenu named BEFORE, otherwise add it at the end of the menu.
88153c47 454
024bda02
RS
455Either call this from `menu-bar-update-hook' or use a menu filter,
456to implement dynamic menus."
efc13f46 457 (easy-menu-add-item nil path (easy-menu-create-menu name items) before))
88153c47 458
024bda02
RS
459;; XEmacs needs the following two functions to add and remove menus.
460;; In Emacs this is done automatically when switching keymaps, so
545128a8
RS
461;; here easy-menu-remove is a noop and easy-menu-add only precalculates
462;; equivalent keybindings (if easy-menu-precalculate-equivalent-keybindings
463;; is on).
0f18f01c
SM
464(defalias 'easy-menu-remove 'ignore
465 "Remove MENU from the current menu bar.
466Contrary to XEmacs, this is a nop on Emacs since menus are automatically
467\(de)activated when the corresponding keymap is (de)activated.
468
469\(fn MENU)")
8df69fb0 470
545128a8 471(defun easy-menu-add (menu &optional map)
e899e3de
SM
472 "Add the menu to the menubar.
473This is a nop on Emacs since menus are automatically activated when the
474corresponding keymap is activated. On XEmacs this is needed to actually
475add the menu to the current menubar.
476Maybe precalculate equivalent key bindings.
08ad3342 477Do it only if `easy-menu-precalculate-equivalent-keybindings' is on."
545128a8
RS
478 (when easy-menu-precalculate-equivalent-keybindings
479 (if (and (symbolp menu) (not (keymapp menu)) (boundp menu))
480 (setq menu (symbol-value menu)))
481 (if (keymapp menu) (x-popup-menu nil menu))))
8df69fb0 482
9ef2bee6
RS
483(defun add-submenu (menu-path submenu &optional before in-menu)
484 "Add submenu SUBMENU in the menu at MENU-PATH.
485If BEFORE is non-nil, add before the item named BEFORE.
486If IN-MENU is non-nil, follow MENU-PATH in IN-MENU.
487This is a compatibility function; use `easy-menu-add-item'."
488 (easy-menu-add-item (or in-menu (current-global-map))
489 (cons "menu-bar" menu-path)
490 submenu before))
491
5e6656e0 492(defun easy-menu-add-item (map path item &optional before)
3de63fb6 493 "To the submenu of MAP with path PATH, add ITEM.
fd43ede0
KH
494
495If an item with the same name is already present in this submenu,
496then ITEM replaces it. Otherwise, ITEM is added to this submenu.
497In the latter case, ITEM is normally added at the end of the submenu.
498However, if BEFORE is a string and there is an item in the submenu
499with that name, then ITEM is added before that item.
5e6656e0 500
4a1186d3 501MAP should normally be a keymap; nil stands for the local menu-bar keymap.
5e6656e0
RS
502It can also be a symbol, which has earlier been used as the first
503argument in a call to `easy-menu-define', or the value of such a symbol.
504
024bda02 505PATH is a list of strings for locating the submenu where ITEM is to be
5e6656e0
RS
506added. If PATH is nil, MAP itself is used. Otherwise, the first
507element should be the name of a submenu directly under MAP. This
024bda02 508submenu is then traversed recursively with the remaining elements of PATH.
3de63fb6
RS
509
510ITEM is either defined as in `easy-menu-define' or a non-nil value returned
511by `easy-menu-item-present-p' or `easy-menu-remove-item' or a menu defined
512earlier by `easy-menu-define' or `easy-menu-create-menu'."
fd43ede0
KH
513 (setq map (easy-menu-get-map map path
514 (and (null map) (null path)
515 (stringp (car-safe item))
516 (car item))))
3de63fb6
RS
517 (if (and (consp item) (consp (cdr item)) (eq (cadr item) 'menu-item))
518 ;; This is a value returned by `easy-menu-item-present-p' or
519 ;; `easy-menu-remove-item'.
9ef2bee6
RS
520 (easy-menu-define-key map (easy-menu-intern (car item))
521 (cdr item) before)
3de63fb6
RS
522 (if (or (keymapp item)
523 (and (symbolp item) (keymapp (symbol-value item))))
524 ;; Item is a keymap, find the prompt string and use as item name.
525 (let ((tail (easy-menu-get-map item nil)) name)
526 (if (not (keymapp item)) (setq item tail))
527 (while (and (null name) (consp (setq tail (cdr tail)))
528 (not (keymapp tail)))
529 (if (stringp (car tail)) (setq name (car tail)) ; Got a name.
530 (setq tail (cdr tail))))
531 (setq item (cons name item))))
532 (easy-menu-do-add-item map item before)))
024bda02 533
5e6656e0
RS
534(defun easy-menu-item-present-p (map path name)
535 "In submenu of MAP with path PATH, return true iff item NAME is present.
536MAP and PATH are defined as in `easy-menu-add-item'.
024bda02 537NAME should be a string, the name of the element to be looked for."
3de63fb6 538 (easy-menu-return-item (easy-menu-get-map map path) name))
024bda02 539
5e6656e0
RS
540(defun easy-menu-remove-item (map path name)
541 "From submenu of MAP with path PATH remove item NAME.
542MAP and PATH are defined as in `easy-menu-add-item'.
024bda02 543NAME should be a string, the name of the element to be removed."
3de63fb6
RS
544 (setq map (easy-menu-get-map map path))
545 (let ((ret (easy-menu-return-item map name)))
9ef2bee6 546 (if ret (easy-menu-define-key map (easy-menu-intern name) nil))
3de63fb6
RS
547 ret))
548
549(defun easy-menu-return-item (menu name)
4d6d04b5
DL
550 "In menu MENU try to look for menu item with name NAME.
551If a menu item is found, return (NAME . item), otherwise return nil.
552If item is an old format item, a new format item is returned."
0847e165 553 (let ((item (lookup-key menu (vector (easy-menu-intern name))))
3de63fb6
RS
554 ret enable cache label)
555 (cond
3de63fb6
RS
556 ((stringp (car-safe item))
557 ;; This is the old menu format. Convert it to new format.
558 (setq label (car item))
559 (when (stringp (car (setq item (cdr item)))) ; Got help string
560 (setq ret (list :help (car item)))
561 (setq item (cdr item)))
562 (when (and (consp item) (consp (car item))
563 (or (null (caar item)) (numberp (caar item))))
564 (setq cache (car item)) ; Got cache
565 (setq item (cdr item)))
566 (and (symbolp item) (setq enable (get item 'menu-enable)) ; Got enable
567 (setq ret (cons :enable (cons enable ret))))
568 (if cache (setq ret (cons cache ret)))
0847e165
SM
569 (cons name (cons 'menu-enable (cons label (cons item ret)))))
570 (item ; (or (symbolp item) (keymapp item) (eq (car-safe item) 'menu-item))
571 (cons name item)) ; Keymap or new menu format
572 )))
024bda02 573
fd43ede0 574(defun easy-menu-get-map-look-for-name (name submap)
9ef2bee6 575 (while (and submap (not (easy-menu-name-match name (car submap))))
fd43ede0
KH
576 (setq submap (cdr submap)))
577 submap)
578
579(defun easy-menu-get-map (map path &optional to-modify)
4d6d04b5
DL
580 "Return a sparse keymap in which to add or remove an item.
581MAP and PATH are as defined in `easy-menu-add-item'.
fd43ede0 582
4d6d04b5
DL
583TO-MODIFY, if non-nil, is the name of the item the caller
584wants to modify in the map that we return.
585In some cases we use that to select between the local and global maps."
5edf6b55
SM
586 (setq map
587 (catch 'found
0847e165
SM
588 (let* ((key (vconcat (unless map '(menu-bar))
589 (mapcar 'easy-menu-intern path)))
5edf6b55
SM
590 (maps (mapcar (lambda (map)
591 (setq map (lookup-key map key))
592 (while (and (symbolp map) (keymapp map))
593 (setq map (symbol-function map)))
594 map)
595 (if map
596 (list (if (and (symbolp map)
597 (not (keymapp map)))
598 (symbol-value map) map))
e899e3de 599 (current-active-maps)))))
5edf6b55
SM
600 ;; Prefer a map that already contains the to-be-modified entry.
601 (when to-modify
602 (dolist (map maps)
dca6b77c 603 (when (and (keymapp map)
5edf6b55
SM
604 (easy-menu-get-map-look-for-name to-modify map))
605 (throw 'found map))))
606 ;; Use the first valid map.
607 (dolist (map maps)
dca6b77c 608 (when (keymapp map)
5edf6b55
SM
609 (throw 'found map)))
610 ;; Otherwise, make one up.
611 ;; Hardcoding current-local-map is lame, but it's difficult
612 ;; to know what the caller intended for us to do ;-(
613 (let* ((name (if path (format "%s" (car (reverse path)))))
614 (newmap (make-sparse-keymap name)))
615 (define-key (or map (current-local-map)) key
616 (if name (cons name newmap) newmap))
617 newmap))))
5e6656e0
RS
618 (or (keymapp map) (error "Malformed menu in easy-menu: (%s)" map))
619 map)
024bda02 620
029b623a
RS
621(provide 'easymenu)
622
ab5796a9 623;;; arch-tag: 2a04020d-90d2-476d-a7c6-71e072007a4a
029b623a 624;;; easymenu.el ends here