+2013-10-03 Eli Zaretskii <eliz@gnu.org>
+
+ * 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 <xfq.free@gmail.com>
* nonascii.texi (Default Coding Systems): Typo fix.
@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
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:
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}.
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
@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
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
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
@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
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