GNU Emacs Lisp Reference Manual

26.15: Pop-Up Menus

When using X windows, a Lisp program can pop up a menu which the user can choose from 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 (see 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 a prefix key with a menu keymap would do the job. 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. This is the reason why all the menu bar items are normally implemented with menu keymaps (see Menu Keymaps).