lispref/frames.texi and xmenu.c

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, but then again, we changed `x-popup-dialog')
As already said, the patches below just document the difference.

However, from :

     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.

I can not check, but does quitting or popping down that popup-menu
when `x-popup-dialog' is used in this situation quit or return nil?
If it returns nil then either this should be fixed (changing
`x-popup-dialog' would automatically do that) or the patch below
should be changed to reflect it.

===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;
  {
============================================================

Re: lispref/frames.texi and xmenu.c

[Andreas Schwab]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> --- 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}),

@code{(...)}

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: lispref/frames.texi and xmenu.c

[Luc Teirlinck]

Andreas Schwab wrote:

   > ! Each item should normally be a cons cell (@var{line} . @var{value}),

   @code{(...)}

Thanks, I fixed this.

Sincerely,

Luc.

Re: lispref/frames.texi and xmenu.c

[Luc Teirlinck]

>From my previous message;

   However, from :

	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.

I meant: 

  However from `(elisp)Dialog Boxes':


Sincerely,

Luc.

Re: lispref/frames.texi and xmenu.c

[Jan D.]

Luc Teirlinck wrote:

>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, but then again, we changed `x-popup-dialog')
>As already said, the patches below just document the difference.
>  
>

I think making x-popup-dialog and x-popup-menu should be made to behave 
the same.  However, since menus are used more in Emacs than dialogs, 
there is a bigger risk involved.

>However, from :
>
>     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.
>
>I can not check, but does quitting or popping down that popup-menu
>when `x-popup-dialog' is used in this situation quit or return nil?
>  
>

Quit.  But it does that by checking if the menu was invoked with the 
mouse.  If it was invoked by the mouse, we return nil, otherwise we 
quit.  So if a menu is popped up programatically by x-popup-menu, it 
will also quit even if it is not popped up as a dialog. This makes me 
wonder if there is code that expects nil from menus, since the code 
tries to keep that distinction.

    Jan D.

Re: lispref/frames.texi and xmenu.c

[Luc Teirlinck]

Jan D. wrote:

   Quit.  But it does that by checking if the menu was invoked with the 
   mouse.  If it was invoked by the mouse, we return nil, otherwise we 
   quit.

I was not worrying about menus invoked with the mouse.  It is OK for
those to return nil.

   So if a menu is popped up programatically by x-popup-menu, it 
   will also quit even if it is not popped up as a dialog.

In my tests (see the precise tests cases I sent to Eli), x-popup-menu
returned nil instead of quitting.  But since Richard's changes, it quits.

I do not believe that passing `t' for POSITION counts as "invoked with
the mouse", even though the menu pops up at the mouse position.  But
anyway, replacing `t' with (list '(0 0) (selected-window)) still used
to return nil (before Richards changes).

Sincerely,

Luc.

Re: lispref/frames.texi and xmenu.c

[Richard Stallman]

Studying the code, I see that the original x-popup-menu in the non-Xt
case does quit if the user cancels, except in the case where it was
invoked for a mouse click.  (This is determined by the POSITION
argument.)  When the code was adapted to Xt, that part of the
functionality was lost, it looks like.

Seeing this, I concluded that the right thing to do is to make all the
implementations of x-popup-menu quit also, under the same condition.
I implemented this in xmenu.c, but not in w32menu.c and macmenu.c.

Would you please document this behavior?

Aside from that issue, the manual changes are good, but

    ! The argument @var{menu} says what to display in the menu.
    ! 

please delete that blank line.


Regarding the doc strings:

    ! 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.  */)


    ! 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.  */)

There's no need for each function to talk about what the other does.
Just document what each function does when the user exits without a
selection.

Re: lispref/frames.texi and xmenu.c

[Luc Teirlinck]

Richard Stallman wrote:

   Seeing this, I concluded that the right thing to do is to make all the
   implementations of x-popup-menu quit also, under the same condition.
   I implemented this in xmenu.c, but not in w32menu.c and macmenu.c.

   Would you please document this behavior?

That worked and I will adapt the documentation accordingly.

Sincerely,

Luc.

Re: lispref/frames.texi and xmenu.c

[Luc Teirlinck]

Richard Stallman wrote:

   Seeing this, I concluded that the right thing to do is to make all the
   implementations of x-popup-menu quit also, under the same condition.
   I implemented this in xmenu.c, but not in w32menu.c and macmenu.c.

   Would you please document this behavior?

I did install my doc changes, _except_ those concerned with the above
problem.  After your changes, there still is an apparent difference
between `x-popup-menu' and `x-popup-dialog' in this respect, at least
on my system.  Is the following difference intentional?

ELISP> (x-popup-menu (read-event) '("TITLE" ("PANE" . ("LINE1" . 1))))

Then click the mouse, the menu pops up, make it disappear by clicking
the mouse away from the menu.  Result: the function returns nil,
fitting your above description.

Now do:

ELISP> (x-popup-dialog (read-event) '("PANE" . ("LINE1" . 1)))

Click the mouse, the dialog pops up,. make it disappear using the
window manager (on my system, I can not make it disappear by clicking
away from the menu).  Result: a quit, no return value.

Sincerely,

Luc.

Re: lispref/frames.texi and xmenu.c

[Richard Stallman]

    I did install my doc changes, _except_ those concerned with the above
    problem.  After your changes, there still is an apparent difference
    between `x-popup-menu' and `x-popup-dialog' in this respect, at least
    on my system.  Is the following difference intentional?

    ELISP> (x-popup-menu (read-event) '("TITLE" ("PANE" . ("LINE1" . 1))))

    Then click the mouse, the menu pops up, make it disappear by clicking
    the mouse away from the menu.  Result: the function returns nil,
    fitting your above description.

    ELISP> (x-popup-dialog (read-event) '("PANE" . ("LINE1" . 1)))

    Click the mouse, the dialog pops up,. make it disappear using the
    window manager (on my system, I can not make it disappear by clicking
    away from the menu).  Result: a quit, no return value.

That's exactly the behavior I described to you.
Yes, it is intentional.

Re: lispref/frames.texi and xmenu.c

[Luc Teirlinck]

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;
  {
============================================================

Re: lispref/frames.texi and xmenu.c

[Richard Stallman]

    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.

I think that assumption is not true.  From reading the code,
x-popup-dialog ALWAYS quits if the user doesn't make a valid choice.

Re: lispref/frames.texi and xmenu.c

[Luc Teirlinck]

Richard Stallman wrote:

   I think that assumption is not true.  From reading the code,
   x-popup-dialog ALWAYS quits if the user doesn't make a valid choice.

That is good, since it gives a lot more consistent behavior.  What
about the following patches, which take this into account?

===File ~/lispref-frames.texi-diff-2========================
*** frames.texi	01 May 2005 16:35:35 -0500	1.86
--- frames.texi	04 May 2005 17:16:03 -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,1486 ----
  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 produces a quit and
+ @code{x-popup-dialog} returns no value.
  @end defun
  
  @node Pointer Shapes
============================================================

===File ~/xmenu.c-diff-2====================================
*** xmenu.c	01 May 2005 16:37:06 -0500	1.287
--- xmenu.c	04 May 2005 21:43:24 -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,1022 ----
  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 gets rid of the dialog box without making a valid choice,
! for instance using the window manager, then this produces a quit and
! `x-popup-dialog' returns no value.  */)
       (position, contents)
       Lisp_Object position, contents;
  {
============================================================

Re: lispref/frames.texi and xmenu.c

[Richard Stallman]

    + keyboard input, then this normally results in a quit and
    + @code{x-popup-menu} returns no value.

Instead of "returns no value", say "does not return".
(There is no such thing in Lisp as "returning no value").

The same issue arises 3 more times in your changes.

With that change, these changes are good.

Re: lispref/frames.texi and xmenu.c

[Luc Teirlinck]

>From my original message:

ELISP> (x-popup-menu (read-event) '("TITLE" ("PANE" . ("LINE1" . 1))))

and

ELISP> (x-popup-dialog (read-event) '("PANE" . ("LINE1" . 1)))

There should not be a "." after the "PANE" in either of the two.
But, after removing that ".", my prior description remains valid.

Sincerely,

Luc.

Re: lispref/frames.texi and xmenu.c

[Eli Zaretskii]

> Date: Sun, 1 May 2005 08:35:20 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>      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.
> 
> I can not check, but does quitting or popping down that popup-menu
> when `x-popup-dialog' is used in this situation quit or return nil?

Please post a test case, a Lisp code that can be eval'ed and
instructions to follow, and I will tell you what happens.

(There's one thing one should remember when dealing with xmenu issues:
on some configurations, I think precisely those which the manual has
in mind, there's no such thing as ``popping down the menu''; one needs
to click something for the menu to disappear.)

Re: lispref/frames.texi and xmenu.c

[Luc Teirlinck]

Eli Zaretskii wrote:

   > I can not check, but does quitting or popping down that popup-menu
   > when `x-popup-dialog' is used in this situation quit or return nil?

   Please post a test case, a Lisp code that can be eval'ed and
   instructions to follow, and I will tell you what happens.

   (There's one thing one should remember when dealing with xmenu issues:
   on some configurations, I think precisely those which the manual has
   in mind, there's no such thing as ``popping down the menu''; one needs
   to click something for the menu to disappear.)

The situation has completely changed (on GNU/Linux) since Richard
installed a patch.

But there still might be problems on other operating systems.

Richard Stallman wrote:

   Studying the code, I see that the original x-popup-menu in the non-Xt
   case does quit if the user cancels, except in the case where it was
   invoked for a mouse click.  (This is determined by the POSITION
   argument.)  When the code was adapted to Xt, that part of the
   functionality was lost, it looks like.

   Seeing this, I concluded that the right thing to do is to make all the
   implementations of x-popup-menu quit also, under the same condition.
   I implemented this in xmenu.c, but not in w32menu.c and macmenu.c.

The things to test are (after updating your CVS to include Richard's
changes):

M-: (x-popup-menu t '("TITLE" ("PANE" . ("LINE1" . 1))))

and then making the menu disappear by clicking away from the menu (I
referred abusively to this as "popping down") should quit instead of
returning nil.

On GNU/Linux this returned nil before Richard's change, but it quits
now.

The same for:

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

and then making the dialog disappear using the window mananger (or by
clicking away from the dialog, assuming this actually makes the dialog
disappear.  (Should also quit, not return nil).

On GNU/Linux, this already quit before Richard's recent change, but it
returned nil in 21.3.

Sincerely,

Luc.

Re: lispref/frames.texi and xmenu.c

[Luc Teirlinck]

>From my earlier message:

   M-: (x-popup-menu t '("TITLE" ("PANE" . ("LINE1" . 1))))

and

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

That was a typo.  There should not be a "." after the "PANE" in either
of the two.  (But if all one does is make the menu disappear, it
should not make any difference.)

Sincerely,

Luc.

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;
  {
============================================================

Re: lispref/frames.texi and xmenu.c

[Luc Teirlinck]

My message to which this is a reply is an older version of a patch I
resent (with some changes), mistakenly believing that the older
version was completely lost.  Please disregard the older (Friday
evening) version.

Sincerely,

Luc.