From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Luc Teirlinck Newsgroups: gmane.emacs.devel Subject: lispref/frames.texi and xmenu.c Date: Fri, 29 Apr 2005 21:02:47 -0500 (CDT) Message-ID: <200504300202.j3U22lV18102@raven.dms.auburn.edu> NNTP-Posting-Host: main.gmane.org X-Trace: sea.gmane.org 1114971394 2951 80.91.229.2 (1 May 2005 18:16:34 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 1 May 2005 18:16:34 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun May 01 20:16:32 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1DSIzJ-00076V-Bt for ged-emacs-devel@m.gmane.org; Sun, 01 May 2005 20:16:18 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1DSJ63-0001Sr-I6 for ged-emacs-devel@m.gmane.org; Sun, 01 May 2005 14:23:15 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1DSIKA-0008CF-9N for emacs-devel@gnu.org; Sun, 01 May 2005 13:33:46 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1DSIK8-0008BR-CO for emacs-devel@gnu.org; Sun, 01 May 2005 13:33:45 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1DSIAy-0003dN-2G for emacs-devel@gnu.org; Sun, 01 May 2005 13:24:16 -0400 Original-Received: from [199.232.41.67] (helo=mx20.gnu.org) by monty-python.gnu.org with esmtp (TLS-1.0:RSA_ARCFOUR_SHA:16) (Exim 4.34) id 1DSHhu-0005bP-RA for emacs-devel@gnu.org; Sun, 01 May 2005 12:54:15 -0400 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by mx20.gnu.org with esmtp (Exim 4.34) id 1DRhS2-00019C-BH for emacs-devel@gnu.org; Fri, 29 Apr 2005 22:11:26 -0400 Original-Received: from raven.dms.auburn.edu (raven.dms.auburn.edu [131.204.53.29]) by manatee.dms.auburn.edu (8.12.10/8.12.10) with ESMTP id j3U22oog018403 for ; Fri, 29 Apr 2005 21:02:50 -0500 (CDT) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.7p1+Sun/8.11.7) id j3U22lV18102; Fri, 29 Apr 2005 21:02:47 -0500 (CDT) X-Authentication-Warning: raven.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f Original-To: emacs-devel@gnu.org X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:36543 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:36543 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; { ============================================================