lispref/frames.texi and xmenu.c

[Luc Teirlinck]

I propose the changes below to lispref/frames.texi and xmenu.texi.
They concern x-popup-{menu,dialog}.  I can install if desired.

I am not sure whether we should document (which the patches below do)
or fix one difference between `x-popup-dialog' and `x-popup-menu'.
When the user quits or pops down the menu, `x-popup-menu' just returns
nil, while `x-popup-dialog' actually quits and returns no value.  If I
remember correctly, the latter behavior is relatively recent and was
the result of a discussion on emacs-devel.  That behavior was
implemented because we did not want to have popping down the dialog or
quitting automatically invoke the action associated with answering
"n(o)" to a y(es)-or-n(o)-p question.  I still believe that this
change made sense.  The question is whether for consistency, a similar
change should be made for `x-popup-menu'.  Maybe this is too close to
a release for such a change.  `x-popup-menu' is usually not used for
simple two-answer questions and hence does not have the
y(es)-or-n(o)-p problem to the same extent.

As already said, the patches below just document the difference.

===File ~/lispref-frames.texi-diff==========================
*** frames.texi 06 Mar 2005 16:28:09 -0600      1.85
--- frames.texi 29 Apr 2005 19:46:57 -0500      
***************
*** 1360,1367 ****
  what selection the user makes.
  
  The argument @var{position} specifies where on the screen to put the
! menu.  It can be either a mouse button event (which says to put the menu
! where the user actuated the button) or a list of this form:
  
  @example
  ((@var{xoffset} @var{yoffset}) @var{window})
--- 1360,1368 ----
  what selection the user makes.
  
  The argument @var{position} specifies where on the screen to put the
! top left corner of the menu.  It can be either a mouse button event
! (which says to put the menu where the user actuated the button) or a
! list of this form:
  
  @example
  ((@var{xoffset} @var{yoffset}) @var{window})
***************
*** 1369,1384 ****
  
  @noindent
  where @var{xoffset} and @var{yoffset} are coordinates, measured in
! pixels, counting from the top left corner of @var{window}'s 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.
  
! The argument @var{menu} says what to display in the menu.  It can be a
! keymap or a list of keymaps (@pxref{Menu Keymaps}).  Alternatively, it
! can have the following form:
  
  @example
  (@var{title} @var{pane1} @var{pane2}...)
--- 1370,1392 ----
  
  @noindent
  where @var{xoffset} and @var{yoffset} are coordinates, measured in
! 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.
  
! 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.
! 
! Alternatively, @var{menu} can have the following form:
  
  @example
  (@var{title} @var{pane1} @var{pane2}...)
***************
*** 1388,1398 ****
  where each pane is a list of form
  
  @example
! (@var{title} (@var{line} . @var{item})...)
  @end example
  
! Each @var{line} should be a string, and each @var{item} should be the
! value to return if that @var{line} is chosen.
  @end defun
  
    @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
--- 1396,1411 ----
  where each pane is a list of form
  
  @example
! (@var{title} @var{item1} @var{item2}...)
  @end example
  
! Each item should normally be a cons cell (@var{line} . @var{value}),
! where @var{line} is a string, and @var{value} is the value to return if
! that @var{line} is chosen.  An item can also be a string; this makes a
! non-selectable line in the menu.
! 
! This function returns @code{nil} if the user quits or pops down the
! menu without making a valid choice.
  @end defun
  
    @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
***************
*** 1443,1451 ****
  
  The return value is @var{value} from the chosen alternative.
  
! An element of the list may be just a string instead of a cons cell
! @code{(@var{string} . @var{value})}.  That makes a box that cannot
! be selected.
  
  If @code{nil} appears in the list, it separates the left-hand items from
  the right-hand items; items that precede the @code{nil} appear on the
--- 1456,1464 ----
  
  The return value is @var{value} from the chosen alternative.
  
! As for @code{x-popup-menu}, an element of the list may be just a
! string instead of a cons cell @code{(@var{string} . @var{value})}.
! That makes a box that cannot be selected.
  
  If @code{nil} appears in the list, it separates the left-hand items from
  the right-hand items; items that precede the @code{nil} appear on the
***************
*** 1455,1466 ****
  
  Dialog boxes always appear in the center of a frame; the argument
  @var{position} specifies which frame.  The possible values are as in
! @code{x-popup-menu}, but the precise coordinates don't matter; only the
! frame matters.
  
  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
  frame.
  @end defun
  
  @node Pointer Shapes
--- 1468,1484 ----
  
  Dialog boxes always appear in the center of a frame; the argument
  @var{position} specifies which frame.  The possible values are as in
! @code{x-popup-menu}, but the precise coordinates or the individual
! window don't matter; only the frame matters.
  
  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
  frame.
+ 
+ Quitting or popping down the dialog box without making a valid choice
+ produces a regular quit; the function returns no value in this case.
+ (Note that @code{x-popup-menu} returns @code{nil} in these situations.
+ @xref{Pop-Up Menus}.)
  @end defun
  
  @node Pointer Shapes
============================================================

===File ~/xmenu.c-diff======================================
*** xmenu.c     18 Apr 2005 07:32:54 -0500      1.285
--- xmenu.c     29 Apr 2005 19:56:06 -0500      
***************
*** 737,743 ****
  POSITION is a position specification.  This is either a mouse button event
  or a list ((XOFFSET YOFFSET) WINDOW)
  where XOFFSET and YOFFSET are positions in pixels from the top left
! corner of WINDOW's frame.  (WINDOW may be a frame object instead of a window.)
  This controls the position of the top left of the menu as a whole.
  If POSITION is t, it means to use the current mouse position.
  
--- 737,743 ----
  POSITION is a position specification.  This is either a mouse button event
  or a list ((XOFFSET YOFFSET) WINDOW)
  where XOFFSET and YOFFSET are positions in pixels from the top left
! corner of WINDOW.  (WINDOW may be a window or a frame object.)
  This controls the position of the top left of the menu as a whole.
  If POSITION is t, it means to use the current mouse position.
  
***************
*** 752,759 ****
  
  You can also use a list of keymaps as MENU.
    Then each keymap makes a separate pane.
! When MENU is a keymap or a list of keymaps, the return value
! is a list of events.
  
  Alternatively, you can specify a menu of multiple panes
    with a list of the form (TITLE PANE1 PANE2...),
--- 752,762 ----
  
  You can also use a list of keymaps as MENU.
    Then each keymap makes a separate pane.
! 
! When MENU is a keymap or a list of keymaps, the return value is the
! list of events corresponding to the user's choice. Note that
! `x-popup-menu' does not actually execute the command bound to that
! sequence of events.
  
  Alternatively, you can specify a menu of multiple panes
    with a list of the form (TITLE PANE1 PANE2...),
***************
*** 764,770 ****
  With this form of menu, the return value is VALUE from the chosen item.
  
  If POSITION is nil, don't display the menu at all, just precalculate the
! cached information about equivalent key sequences.  */)
       (position, menu)
       Lisp_Object position, menu;
  {
--- 767,778 ----
  With this form of menu, the return value is VALUE from the chosen item.
  
  If POSITION is nil, don't display the menu at all, just precalculate the
! cached information about equivalent key sequences.
! 
! This function returns nil if the user quits or pops down the menu
! without making a valid choice.  Note that this differs from
! `x-popup-dialog', which quits without returning a value in these
! situations.  */)
       (position, menu)
       Lisp_Object position, menu;
  {
***************
*** 1002,1008 ****
  An ITEM may also be just a string--that makes a nonselectable item.
  An ITEM may also be nil--that means to put all preceding items
  on the left of the dialog box and all following items on the right.
! \(By default, approximately half appear on each side.)  */)
       (position, contents)
       Lisp_Object position, contents;
  {
--- 1010,1021 ----
  An ITEM may also be just a string--that makes a nonselectable item.
  An ITEM may also be nil--that means to put all preceding items
  on the left of the dialog box and all following items on the right.
! \(By default, approximately half appear on each side.)
! 
! If the user pops down the dialog box without making a valid choice,
! then this produces a quit and the function returns no value.  Note
! that this differs from `x-popup-menu', which returns nil in this
! situation.  */)
       (position, contents)
       Lisp_Object position, contents;
  {
============================================================