Re: lispref/frames.texi and xmenu.c

[Luc Teirlinck <teirllm@dms.auburn.edu>]

Here are my proposed patches to lispref/frames.texi and xmenu.c.  As
always, I can install if desired.

My text assumes that in situations where `x-popup-dialog' has to
actually use a menu instead of a dialog box, doing

M-: (x-popup-dialog (read-event) '("PANE" ("LINE1" . 1)))

then clicking the mouse to make the menu pop up and then getting rid
of that menu without making a valid choice actually returns nil
without quitting.  (It produces a quit if a real dialog box is used.)
I can not check this, but I deduce from Jan's comments that this is
correct.

===File ~/lispref-frames.texi-diff==========================
*** frames.texi	01 May 2005 16:35:35 -0500	1.86
--- frames.texi	03 May 2005 17:26:27 -0500	
***************
*** 1402,1407 ****
--- 1402,1414 ----
  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.
+ 
+ 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
+ @code{x-popup-menu} returns no value.  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}.
  @end defun
  
    @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
***************
*** 1470,1475 ****
--- 1477,1490 ----
  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.
+ 
+ If the user gets rid of the dialog box without making a valid choice,
+ for instance using the window manager, then this normally results in a
+ quit and @code{x-popup-dialog} returns no value.  The only exception
+ occurs in those situations where Emacs has to use a menu instead of a
+ dialog box and @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-dialog} returns @code{nil}.
  @end defun
  
  @node Pointer Shapes
============================================================

===File ~/xmenu.c-diff======================================
*** xmenu.c	01 May 2005 16:37:06 -0500	1.287
--- xmenu.c	03 May 2005 17:41:38 -0500	
***************
*** 767,773 ****
  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,780 ----
  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.
! 
! 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
! `x-popup-menu' returns no value.  But if POSITION is a mouse button
! event (indicating that the user invoked the menu with the mouse) then
! no quit occurs and `x-popup-menu' returns nil.  */)
       (position, menu)
       Lisp_Object position, menu;
  {
***************
*** 1005,1011 ****
  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;
  {
--- 1012,1030 ----
  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.)
! 
! 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.
! 
! If the user gets rid of the dialog box without making a valid choice,
! for instance using the window manager, then this normally results in a
! quit and `x-popup-dialog' returns no value.  The only exception occurs
! in those situations where Emacs has to use a menu instead of a dialog
! box and POSITION is a mouse button event (indicating that the user
! invoked the menu with the mouse); then no quit occurs and
! `x-popup-dialog' returns nil.  */)
       (position, contents)
       Lisp_Object position, contents;
  {
============================================================