GNU Info

Info Node: (elisp)Pop-Up Menus

(elisp)Pop-Up Menus


Next: Dialog Boxes Prev: Mouse Position Up: Frames
Enter node , (file) or (file)node

Pop-Up Menus
============

   When using a window system, a Lisp program can pop up a menu so that
the user can choose an alternative with the mouse.

 - Function: x-popup-menu position menu
     This function displays a pop-up menu and returns an indication of
     what selection the user makes.

     The argument 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:

          ((XOFFSET YOFFSET) WINDOW)

     where XOFFSET and YOFFSET are coordinates, measured in pixels,
     counting from the top left corner of WINDOW's frame.

     If POSITION is `t', it means to use the current mouse position.
     If POSITION is `nil', it means to precompute the key binding
     equivalents for the keymaps specified in MENU, without actually
     displaying or popping up the menu.

     The argument MENU says what to display in the menu.  It can be a
     keymap or a list of keymaps (Note: Menu Keymaps).
     Alternatively, it can have the following form:

          (TITLE PANE1 PANE2...)

     where each pane is a list of form

          (TITLE (LINE . ITEM)...)

     Each LINE should be a string, and each ITEM should be the value to
     return if that LINE is chosen.

   *Usage note:* Don't use `x-popup-menu' to display a menu if you
could do the job with a prefix key defined with a menu keymap.  If you
use a menu keymap to implement a menu, `C-h c' and `C-h a' can see the
individual items in that menu and provide help for them.  If instead
you implement the menu by defining a command that calls `x-popup-menu',
the help facilities cannot know what happens inside that command, so
they cannot give any help for the menu's items.

   The menu bar mechanism, which lets you switch between submenus by
moving the mouse, cannot look within the definition of a command to see
that it calls `x-popup-menu'.  Therefore, if you try to implement a
submenu using `x-popup-menu', it cannot work with the menu bar in an
integrated fashion.  This is why all menu bar submenus are implemented
with menu keymaps within the parent menu, and never with
`x-popup-menu'.  Note: Menu Bar,

   If you want a menu bar submenu to have contents that vary, you should
still use a menu keymap to implement it.  To make the contents vary, add
a hook function to `menu-bar-update-hook' to update the contents of the
menu keymap as necessary.


automatically generated by info2www version 1.2.2.9