From: Eli Zaretskii Date: Thu, 3 Oct 2013 19:10:34 +0000 (+0300) Subject: More updates for documentation. X-Git-Tag: emacs-24.3.90~173^2^2~42^2~45^2~387^2~1328^2~12 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=981b26a63adc88532c7a39f87c871e98d6a59602;p=emacs.git More updates for documentation. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 2fa3fc13e31..c93f1b7c659 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,11 @@ +2013-10-03 Eli Zaretskii + + * keymaps.texi (Defining Menus, Mouse Menus, Menu Bar): Modify + wording to the effect that menus are supported on TTYs. + + * frames.texi (Pop-Up Menus, Dialog Boxes) + (Display Feature Testing): Update for menu support on TTYs. + 2013-09-22 Xue Fuqiao * nonascii.texi (Default Coding Systems): Typo fix. diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 370098c8b62..4935534d6eb 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -1741,8 +1741,10 @@ allows to know if the pointer has been hidden. @node Pop-Up Menus @section Pop-Up Menus - When using a window system, a Lisp program can pop up a menu so that -the user can choose an alternative with the mouse. + A Lisp program can pop up a menu so that the user can choose an +alternative with the mouse. On a text terminal, if the mouse is not +available, the user can choose an alternative using the keyboard +motion keys---@kbd{C-n}, @kbd{C-p}, or up- and down-arrow keys. @defun x-popup-menu position menu This function displays a pop-up menu and returns an indication of @@ -1763,20 +1765,22 @@ pixels, counting from the top left corner of @var{window}. @var{window} may be a window or a frame. If @var{position} is @code{t}, it means to use the current mouse -position. If @var{position} is @code{nil}, it means to precompute the -key binding equivalents for the keymaps specified in @var{menu}, -without actually displaying or popping up the menu. +position (or the top-left corner of the frame if the mouse is not +available on a text terminal). If @var{position} is @code{nil}, it +means to precompute the key binding equivalents for the keymaps +specified in @var{menu}, without actually displaying or popping up the +menu. The argument @var{menu} says what to display in the menu. It can be a keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the return value is the list of events corresponding to the user's choice. This list has more than one element if the choice occurred in a submenu. (Note that @code{x-popup-menu} does not actually execute the -command bound to that sequence of events.) On toolkits that support -menu titles, the title is taken from the prompt string of @var{menu} -if @var{menu} is a keymap, or from the prompt string of the first -keymap in @var{menu} if it is a list of keymaps (@pxref{Defining -Menus}). +command bound to that sequence of events.) On text terminals and +toolkits that support menu titles, the title is taken from the prompt +string of @var{menu} if @var{menu} is a keymap, or from the prompt +string of the first keymap in @var{menu} if it is a list of keymaps +(@pxref{Defining Menus}). Alternatively, @var{menu} can have the following form: @@ -1800,7 +1804,7 @@ cell; this makes a non-selectable menu item. If the user gets rid of the menu without making a valid choice, for instance by clicking the mouse away from a valid choice or by typing -keyboard input, then this normally results in a quit and +@kbd{C-g}, then this normally results in a quit and @code{x-popup-menu} does not return. But if @var{position} is a mouse button event (indicating that the user invoked the menu with the mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}. @@ -1872,7 +1876,8 @@ window don't matter; only the frame matters. If @var{header} is non-@code{nil}, the frame title for the box is @samp{Information}, otherwise it is @samp{Question}. The former is used -for @code{message-box} (@pxref{message-box}). +for @code{message-box} (@pxref{message-box}). (On text terminals, the +box title is not displayed.) In some configurations, Emacs cannot display a real dialog box; so instead it displays the same items in a pop-up menu in the center of the @@ -2284,9 +2289,9 @@ obtain information about displays. @defun display-popup-menus-p &optional display This function returns @code{t} if popup menus are supported on -@var{display}, @code{nil} if not. Support for popup menus requires that -the mouse be available, since the user cannot choose menu items without -a mouse. +@var{display}, @code{nil} if not. Support for popup menus requires +that the mouse be available, since the menu is popped up by clicking +the mouse on some portion of the Emacs display. @end defun @defun display-graphic-p &optional display diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index ef020364082..73d869d59fd 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -2023,7 +2023,7 @@ which is a string that appears as an element of the keymap. the menu's commands. Emacs displays the overall prompt string as the menu title in some cases, depending on the toolkit (if any) used for displaying menus.@footnote{It is required for menus which do not use a -toolkit, e.g., under MS-DOS.} Keyboard menus also display the +toolkit, e.g., on a text terminal.} Keyboard menus also display the overall prompt string. The easiest way to construct a keymap with a prompt string is to @@ -2371,16 +2371,17 @@ if the menu keymap contains a single nested keymap and no other menu items, the menu shows the contents of the nested keymap directly, not as a submenu. - However, if Emacs is compiled without X toolkit support, submenus -are not supported. Each nested keymap is shown as a menu item, but -clicking on it does not automatically pop up the submenu. If you wish -to imitate the effect of submenus, you can do that by giving a nested -keymap an item string which starts with @samp{@@}. This causes Emacs -to display the nested keymap using a separate @dfn{menu pane}; the -rest of the item string after the @samp{@@} is the pane label. If -Emacs is compiled without X toolkit support, menu panes are not used; -in that case, a @samp{@@} at the beginning of an item string is -omitted when the menu label is displayed, and has no other effect. + However, if Emacs is compiled without X toolkit support, or on text +terminals, submenus are not supported. Each nested keymap is shown as +a menu item, but clicking on it does not automatically pop up the +submenu. If you wish to imitate the effect of submenus, you can do +that by giving a nested keymap an item string which starts with +@samp{@@}. This causes Emacs to display the nested keymap using a +separate @dfn{menu pane}; the rest of the item string after the +@samp{@@} is the pane label. If Emacs is compiled without X toolkit +support, or if a menu is displayed on a text terminal, menu panes are +not used; in that case, a @samp{@@} at the beginning of an item string +is omitted when the menu label is displayed, and has no other effect. @node Keyboard Menus @subsection Menus and the Keyboard @@ -2485,10 +2486,10 @@ can do it this way: @subsection The Menu Bar @cindex menu bar - On graphical displays, there is usually a @dfn{menu bar} at the top -of each frame. @xref{Menu Bars,,,emacs, The GNU Emacs Manual}. Menu -bar items are subcommands of the fake ``function key'' -@code{menu-bar}, as defined in the active keymaps. + Emacs usually shows a @dfn{menu bar} at the top of each frame. +@xref{Menu Bars,,,emacs, The GNU Emacs Manual}. Menu bar items are +subcommands of the fake ``function key'' @code{menu-bar}, as defined +in the active keymaps. To add an item to the menu bar, invent a fake ``function key'' of your own (let's call it @var{key}), and make a binding for the key sequence @@ -2575,7 +2576,7 @@ in Documentation}. A @dfn{tool bar} is a row of clickable icons at the top of a frame, just below the menu bar. @xref{Tool Bars,,,emacs, The GNU Emacs -Manual}. +Manual}. Emacs normally shows a tool bar on graphical displays. On each frame, the frame parameter @code{tool-bar-lines} controls how many lines' worth of height to reserve for the tool bar. A zero