[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
lispref/frames.texi and xmenu.c
From: |
Luc Teirlinck |
Subject: |
lispref/frames.texi and xmenu.c |
Date: |
Sun, 1 May 2005 08:35:20 -0500 (CDT) |
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;
{
============================================================
- lispref/frames.texi and xmenu.c,
Luc Teirlinck <=
- Re: lispref/frames.texi and xmenu.c, Andreas Schwab, 2005/05/01
- Re: lispref/frames.texi and xmenu.c, Luc Teirlinck, 2005/05/01
- Re: lispref/frames.texi and xmenu.c, Jan D., 2005/05/01
- Re: lispref/frames.texi and xmenu.c, Eli Zaretskii, 2005/05/01
- Re: lispref/frames.texi and xmenu.c, Richard Stallman, 2005/05/01