Mercurial > hg > xemacs-beta

comparison man/lispref/menus.texi @ 54:05472e90ae02 r19-16-pre2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-16-pre2
author cvs
date Mon, 13 Aug 2007 08:57:55 +0200
parents ac2d302a0011
children 131b0175ea99
comparison
equal deleted inserted replaced
53:875393c1a535 54:05472e90ae02
1 @c -*-texinfo-*- 1 @c -*-texinfo-*-
2 @c This is part of the XEmacs Lisp Reference Manual. 2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1997 Free Software Foundation, Inc.
4 @c Copyright (C) 1995 Sun Microsystems. 4 @c Copyright (C) 1995 Sun Microsystems.
5 @c See the file lispref.texi for copying conditions. 5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/menu.info 6 @setfilename ../../info/menu.info
7 @node Menus, Dialog Boxes, Keymaps, Top 7 @node Menus, Dialog Boxes, Keymaps, Top
8 @chapter Menus 8 @chapter Menus
13 * Menubar Format:: How to specify a menubar. 13 * Menubar Format:: How to specify a menubar.
14 * Menubar:: Functions for controlling the menubar. 14 * Menubar:: Functions for controlling the menubar.
15 * Modifying Menus:: Modifying a menu description. 15 * Modifying Menus:: Modifying a menu description.
16 * Pop-Up Menus:: Functions for specifying pop-up menus. 16 * Pop-Up Menus:: Functions for specifying pop-up menus.
17 * Menu Filters:: Filter functions for the default menubar. 17 * Menu Filters:: Filter functions for the default menubar.
18 * Menu Accelerators:: Using and controlling menu accelerator keys
18 * Buffers Menu:: The menu that displays the list of buffers. 19 * Buffers Menu:: The menu that displays the list of buffers.
19 @end menu 20 @end menu
20 21
21 @node Menu Format 22 @node Menu Format
22 @section Format of Menus 23 @section Format of Menus
36 except in the case of the top level pop-up menu, where there is no 37 except in the case of the top level pop-up menu, where there is no
37 parent. In this case, the string will be displayed at the top of the 38 parent. In this case, the string will be displayed at the top of the
38 menu if @code{popup-menu-titles} is non-@code{nil}. 39 menu if @code{popup-menu-titles} is non-@code{nil}.
39 40
40 Immediately following the first element there may optionally be up 41 Immediately following the first element there may optionally be up
41 to three keyword-value pairs, as follows: 42 to four keyword-value pairs, as follows:
42 43
43 @table @code 44 @table @code
44 @item :included @var{form} 45 @item :included @var{form}
45 This can be used to control the visibility of a menu. The form is 46 This can be used to control the visibility of a menu. The form is
46 evaluated and the menu will be omitted if the result is @code{nil}. 47 evaluated and the menu will be omitted if the result is @code{nil}.
57 It is called only when the menu is about to be displayed, so other menus 58 It is called only when the menu is about to be displayed, so other menus
58 may already be displayed. Vile and terrible things will happen if a 59 may already be displayed. Vile and terrible things will happen if a
59 menu filter function changes the current buffer, window, or frame. It 60 menu filter function changes the current buffer, window, or frame. It
60 also should not raise, lower, or iconify any frames. Basically, the 61 also should not raise, lower, or iconify any frames. Basically, the
61 filter function should have no side-effects. 62 filter function should have no side-effects.
63
64 @item :accelerator @var{key}
65 A menu accelerator is a keystroke which can be pressed while the menu is
66 visible which will immediately activate the item. @var{key} must be a char
67 or the symbol name of a key. @xref{Menu Accelerators}.
62 @end table 68 @end table
63 69
64 The rest of the menu consists of elements as follows: 70 The rest of the menu consists of elements as follows:
65 71
66 @itemize @bullet 72 @itemize @bullet
214 will be omitted entirely. 220 will be omitted entirely.
215 221
216 @item :config @var{symbol} 222 @item :config @var{symbol}
217 This is an efficient shorthand for @code{:included (memq @var{symbol} 223 This is an efficient shorthand for @code{:included (memq @var{symbol}
218 menubar-configuration)}. See the variable @code{menubar-configuration}. 224 menubar-configuration)}. See the variable @code{menubar-configuration}.
225
226 @item :accelerator @var{key}
227 A menu accelerator is a keystroke which can be pressed while the menu is
228 visible which will immediately activate the item. @var{key} must be a char
229 or the symbol name of a key. @xref{Menu Accelerators}.
219 @end table 230 @end table
220 231
221 @defvar menubar-configuration 232 @defvar menubar-configuration
222 This variable holds a list of symbols, against which the value of the 233 This variable holds a list of symbols, against which the value of the
223 @code{:config} tag for each menubar item will be compared. If a menubar 234 @code{:config} tag for each menubar item will be compared. If a menubar
574 585
575 @defun popup-menubar-menu event 586 @defun popup-menubar-menu event
576 This function pops up a copy of menu that also appears in the menubar. 587 This function pops up a copy of menu that also appears in the menubar.
577 @end defun 588 @end defun
578 589
590 @node Menu Accelerators
591 @section Menu Accelerators
592 @cindex menu accelerators
593 @cindex keyboard menu accelerators
594
595 Menu accelerators are keyboard shortcuts for accessing the menubar.
596 Accelerator keys can be specified for menus as well as for menu items. An
597 accelerator key for a menu is used to activate that menu when it appears as a
598 submenu of another menu. An accelerator key for a menu item is used to
599 activate that item.
600
601 @menu
602 * Creating Menu Accelerators:: How to add accelerator keys to a menu.
603 * Keyboard Menu Traversal:: How to use and modify the keys which are used
604 to traverse the menu structure.
605 * Menu Accelerator Functions:: Functions for working with menu accelerators.
606 @end menu
607
608 @node Creating Menu Accelerators
609 @subsection Creating Menu Accelerators
610
611 Menu accelerators are specified as part of the menubar format using the
612 :accelerator tag to specify a key or by placing "%_" in the menu or menu item
613 name prior to the letter which is to be used as the accelerator key. The
614 advantage of the second method is that the menu rendering code then knows to
615 draw an underline under that character, which is the canonical way of
616 indicating an accelerator key to a user.
617
618 For example, the command
619
620 @example
621 (add-submenu nil '("%_Test"
622 ["One" (insert "1") :accelerator ?1 :active t]
623 ["%_Two" (insert "2") t]
624 ["%_3" (insert "3") t]))
625 @end example
626
627 will add a new menu to the top level menubar. The new menu can be reached
628 by pressing "t" while the top level menubar is active. When the menu is
629 active, pressing "1" will activate the first item and insert the character
630 "1" into the buffer. Pressing "2" will activate the second item and insert
631 the character "2" into the buffer. Pressing "3" will activate the third item
632 and insert the character "3" into the buffer.
633
634 It is possible to activate the top level menubar itself using accelerator keys.
635 @xref{Menu Accelerator Functions}.
636
637 @node Keyboard Menu Traversal
638 @subsection Keyboard Menu Traversal
639
640 In addition to immediately activating a menu or menu item, the keyboard can
641 be used to traverse the menus without activating items. The keyboard arrow
642 keys, the return key and the escape key are defined to traverse the menus in a
643 way that should be familiar to users of any of a certain family of popular PC
644 operating systems.
645
646 This behaviour can be changed by modifying the bindings in
647 menu-accelerator-map. At this point, the online help is your best bet
648 for more information about how to modify the menu traversal keys.
649
650 @node Menu Accelerator Functions
651 @subsection Menu Accelerator Functions
652
653 @defun accelerate-menu
654 Make the menubar immediately active and place the cursor on the left most entry
655 in the top level menu. Menu items can be selected as usual.
656 @end defun
657
658 @defvar menu-accelerator-enabled
659 Whether menu accelerator keys can cause the menubar to become active.
660
661 If @code{menu-force} or @code{menu-fallback}, then menu accelerator keys can
662 be used to activate the top level menu. Once the menubar becomes active, the
663 accelerator keys can be used regardless of the value of this variable.
664
665 @code{menu-force} is used to indicate that the menu accelerator key takes
666 precedence over bindings in the current keymap(s). @code{menu-fallback} means
667 that bindings in the current keymap take precedence over menu accelerator keys.
668 Thus a top level menu with an accelerator of "T" would be activated on a
669 keypress of Meta-t if @var{menu-accelerator-enabled} is @code{menu-force}.
670 However, if @var{menu-accelerator-enabled} is @code{menu-fallback}, then
671 Meta-t will not activate the menubar and will instead run the function
672 transpose-words, to which it is normally bound.
673
674 The default value is @code{nil}.
675
676 See also @var{menu-accelerator-modifiers} and @var{menu-accelerator-prefix}.
677 @end defvar
678
679 @defvar menu-accelerator-map
680 Keymap consulted to determine the commands to run in response to keypresses
681 occurring while the menubar is active. @xref{Keyboard Menu Traversal}.
682 @end defvar
683
684 @defvar menu-accelerator-modifiers
685 A list of modifier keys which must be pressed in addition to a valid menu
686 accelerator in order for the top level menu to be activated in response to
687 a keystroke. The default value of @code{(meta)} mirrors the useage of the alt key
688 as a menu accelerator in popular PC operating systems.
689
690 The modifier keys in @var{menu-accelerator-modifiers} must match exactly the
691 modifiers present in the keypress. The only exception is that the shift
692 modifier is accepted in conjunction with alphabetic keys even if it is not
693 a menu accelerator modifier.
694
695 See also @var{menu-accelerator-enabled} and @var{menu-accelerator-prefix}.
696 @end defvar
697
698 @defvar menu-accelerator-prefix
699 Prefix key(s) that must be typed before menu accelerators will be activated.
700 Must be a valid key descriptor.
701
702 The default value is @code{nil}.
703 @end defvar
704
705 @example
706 (setq menu-accelerator-prefix ?\C-x)
707 (setq menu-accelerator-modifiers '(meta control))
708 (setq menu-accelerator-enabled 'menu-force)
709 (add-submenu nil '("%_Test"
710 ["One" (insert "1") :accelerator ?1 :active t]
711 ["%_Two" (insert "2") t]
712 ["%_3" (insert "3") t]))
713 @end example
714
715 will add the menu "Test" to the top level menubar. Pressing C-x followed by
716 C-M-T will activate the menubar and display the "Test" menu. Pressing
717 C-M-T by itself will not activate the menubar. Neither will pressing C-x
718 followed by anything else.
719
579 @node Buffers Menu 720 @node Buffers Menu
580 @section Buffers Menu 721 @section Buffers Menu
581 @cindex buffers menu 722 @cindex buffers menu
582 723
583 The following options control how the @samp{Buffers} menu is displayed. 724 The following options control how the @samp{Buffers} menu is displayed.