comparison src/macmenu.c @ 64606:ceb2de3f0f69

(Fx_popup_menu, Fx_popup_menu): Doc fixes.
author YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp>
date Sat, 23 Jul 2005 07:48:26 +0000
parents a8fa7c632ee4
children a0d1312ede66 890cc78a5a24
comparison
equal deleted inserted replaced
64605:7d52e474fac1 64606:ceb2de3f0f69
609 discard_menu_items (); 609 discard_menu_items ();
610 } 610 }
611 611
612 DEFUN ("x-popup-menu", Fx_popup_menu, Sx_popup_menu, 2, 2, 0, 612 DEFUN ("x-popup-menu", Fx_popup_menu, Sx_popup_menu, 2, 2, 0,
613 doc: /* Pop up a deck-of-cards menu and return user's selection. 613 doc: /* Pop up a deck-of-cards menu and return user's selection.
614 POSITION is a position specification. This is either a mouse button 614 POSITION is a position specification. This is either a mouse button event
615 event or a list ((XOFFSET YOFFSET) WINDOW) where XOFFSET and YOFFSET 615 or a list ((XOFFSET YOFFSET) WINDOW)
616 are positions in pixels from the top left corner of WINDOW's frame 616 where XOFFSET and YOFFSET are positions in pixels from the top left
617 \(WINDOW may be a frame object instead of a window). This controls the 617 corner of WINDOW. (WINDOW may be a window or a frame object.)
618 position of the center of the first line in the first pane of the 618 This controls the position of the top left of the menu as a whole.
619 menu, not the top left of the menu as a whole. If POSITION is t, it 619 If POSITION is t, it means to use the current mouse position.
620 means to use the current mouse position.
621 620
622 MENU is a specifier for a menu. For the simplest case, MENU is a keymap. 621 MENU is a specifier for a menu. For the simplest case, MENU is a keymap.
623 The menu items come from key bindings that have a menu string as well as 622 The menu items come from key bindings that have a menu string as well as
624 a definition; actually, the \"definition\" in such a key binding looks like 623 a definition; actually, the "definition" in such a key binding looks like
625 \(STRING . REAL-DEFINITION). To give the menu a title, put a string into 624 \(STRING . REAL-DEFINITION). To give the menu a title, put a string into
626 the keymap as a top-level element. 625 the keymap as a top-level element.
627 626
628 If REAL-DEFINITION is nil, that puts a nonselectable string in the menu. 627 If REAL-DEFINITION is nil, that puts a nonselectable string in the menu.
629 Otherwise, REAL-DEFINITION should be a valid key binding definition. 628 Otherwise, REAL-DEFINITION should be a valid key binding definition.
630 629
631 You can also use a list of keymaps as MENU. Then each keymap makes a 630 You can also use a list of keymaps as MENU.
632 separate pane. When MENU is a keymap or a list of keymaps, the return 631 Then each keymap makes a separate pane.
633 value is a list of events. 632
634 633 When MENU is a keymap or a list of keymaps, the return value is the
635 Alternatively, you can specify a menu of multiple panes with a list of 634 list of events corresponding to the user's choice. Note that
636 the form (TITLE PANE1 PANE2...), where each pane is a list of 635 `x-popup-menu' does not actually execute the command bound to that
637 form (TITLE ITEM1 ITEM2...). 636 sequence of events.
638 Each ITEM is normally a cons cell (STRING . VALUE); but a string can 637
639 appear as an item--that makes a nonselectable line in the menu. 638 Alternatively, you can specify a menu of multiple panes
639 with a list of the form (TITLE PANE1 PANE2...),
640 where each pane is a list of form (TITLE ITEM1 ITEM2...).
641 Each ITEM is normally a cons cell (STRING . VALUE);
642 but a string can appear as an item--that makes a nonselectable line
643 in the menu.
640 With this form of menu, the return value is VALUE from the chosen item. 644 With this form of menu, the return value is VALUE from the chosen item.
641 645
642 If POSITION is nil, don't display the menu at all, just precalculate the 646 If POSITION is nil, don't display the menu at all, just precalculate the
643 cached information about equivalent key sequences. */) 647 cached information about equivalent key sequences.
644 (position, menu) 648
649 If the user gets rid of the menu without making a valid choice, for
650 instance by clicking the mouse away from a valid choice or by typing
651 keyboard input, then this normally results in a quit and
652 `x-popup-menu' does not return. But if POSITION is a mouse button
653 event (indicating that the user invoked the menu with the mouse) then
654 no quit occurs and `x-popup-menu' returns nil. */)
655 (position, menu)
645 Lisp_Object position, menu; 656 Lisp_Object position, menu;
646 { 657 {
647 Lisp_Object keymap, tem; 658 Lisp_Object keymap, tem;
648 int xpos = 0, ypos = 0; 659 int xpos = 0, ypos = 0;
649 Lisp_Object title; 660 Lisp_Object title;
838 This is normally a mouse button event or a window or frame. 849 This is normally a mouse button event or a window or frame.
839 If POSITION is t, it means to use the frame the mouse is on. 850 If POSITION is t, it means to use the frame the mouse is on.
840 The dialog box appears in the middle of the specified frame. 851 The dialog box appears in the middle of the specified frame.
841 852
842 CONTENTS specifies the alternatives to display in the dialog box. 853 CONTENTS specifies the alternatives to display in the dialog box.
843 It is a list of the form (TITLE ITEM1 ITEM2...). 854 It is a list of the form (DIALOG ITEM1 ITEM2...).
844 Each ITEM is a cons cell (STRING . VALUE). 855 Each ITEM is a cons cell (STRING . VALUE).
845 The return value is VALUE from the chosen item. 856 The return value is VALUE from the chosen item.
846 857
847 An ITEM may also be just a string--that makes a nonselectable item. 858 An ITEM may also be just a string--that makes a nonselectable item.
848 An ITEM may also be nil--that means to put all preceding items 859 An ITEM may also be nil--that means to put all preceding items
849 on the left of the dialog box and all following items on the right. 860 on the left of the dialog box and all following items on the right.
850 \(By default, approximately half appear on each side.) 861 \(By default, approximately half appear on each side.)
851 862
852 If HEADER is non-nil, the frame title for the box is "Information", 863 If HEADER is non-nil, the frame title for the box is "Information",
853 otherwise it is "Question". */) 864 otherwise it is "Question".
854 (position, contents, header) 865
866 If the user gets rid of the dialog box without making a valid choice,
867 for instance using the window manager, then this produces a quit and
868 `x-popup-dialog' does not return. */)
869 (position, contents, header)
855 Lisp_Object position, contents, header; 870 Lisp_Object position, contents, header;
856 { 871 {
857 FRAME_PTR f = NULL; 872 FRAME_PTR f = NULL;
858 Lisp_Object window; 873 Lisp_Object window;
859 874