Mercurial > hg > xemacs-beta

comparison man/lispref/menus.texi @ 70:131b0175ea99 r20-0b30

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r20-0b30
author cvs
date Mon, 13 Aug 2007 09:02:59 +0200
parents 05472e90ae02
children 2d532a89d707
comparison
equal deleted inserted replaced
69:804d1389bcd6 70:131b0175ea99
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, 1997 Free Software Foundation, Inc. 3 @c Copyright (C) 1990, 1991, 1992, 1993 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
19 * Buffers Menu:: The menu that displays the list of buffers. 18 * Buffers Menu:: The menu that displays the list of buffers.
20 @end menu 19 @end menu
21 20
22 @node Menu Format 21 @node Menu Format
23 @section Format of Menus 22 @section Format of Menus
37 except in the case of the top level pop-up menu, where there is no 36 except in the case of the top level pop-up menu, where there is no
38 parent. In this case, the string will be displayed at the top of the 37 parent. In this case, the string will be displayed at the top of the
39 menu if @code{popup-menu-titles} is non-@code{nil}. 38 menu if @code{popup-menu-titles} is non-@code{nil}.
40 39
41 Immediately following the first element there may optionally be up 40 Immediately following the first element there may optionally be up
42 to four keyword-value pairs, as follows: 41 to three keyword-value pairs, as follows:
43 42
44 @table @code 43 @table @code
45 @item :included @var{form} 44 @item :included @var{form}
46 This can be used to control the visibility of a menu. The form is 45 This can be used to control the visibility of a menu. The form is
47 evaluated and the menu will be omitted if the result is @code{nil}. 46 evaluated and the menu will be omitted if the result is @code{nil}.
58 It is called only when the menu is about to be displayed, so other menus 57 It is called only when the menu is about to be displayed, so other menus
59 may already be displayed. Vile and terrible things will happen if a 58 may already be displayed. Vile and terrible things will happen if a
60 menu filter function changes the current buffer, window, or frame. It 59 menu filter function changes the current buffer, window, or frame. It
61 also should not raise, lower, or iconify any frames. Basically, the 60 also should not raise, lower, or iconify any frames. Basically, the
62 filter function should have no side-effects. 61 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}.
68 @end table 62 @end table
69 63
70 The rest of the menu consists of elements as follows: 64 The rest of the menu consists of elements as follows:
71 65
72 @itemize @bullet 66 @itemize @bullet
220 will be omitted entirely. 214 will be omitted entirely.
221 215
222 @item :config @var{symbol} 216 @item :config @var{symbol}
223 This is an efficient shorthand for @code{:included (memq @var{symbol} 217 This is an efficient shorthand for @code{:included (memq @var{symbol}
224 menubar-configuration)}. See the variable @code{menubar-configuration}. 218 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}.
230 @end table 219 @end table
231 220
232 @defvar menubar-configuration 221 @defvar menubar-configuration
233 This variable holds a list of symbols, against which the value of the 222 This variable holds a list of symbols, against which the value of the
234 @code{:config} tag for each menubar item will be compared. If a menubar 223 @code{:config} tag for each menubar item will be compared. If a menubar
585 574
586 @defun popup-menubar-menu event 575 @defun popup-menubar-menu event
587 This function pops up a copy of menu that also appears in the menubar. 576 This function pops up a copy of menu that also appears in the menubar.
588 @end defun 577 @end defun
589 578
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
720 @node Buffers Menu 579 @node Buffers Menu
721 @section Buffers Menu 580 @section Buffers Menu
722 @cindex buffers menu 581 @cindex buffers menu
723 582
724 The following options control how the @samp{Buffers} menu is displayed. 583 The following options control how the @samp{Buffers} menu is displayed.