path: root/devdocs/elisp/pop_002dup-menus.html

 <h3 class="section">Pop-Up Menus</h3>  <p>A Lisp program can pop up a menu so that the user can choose an alternative with the mouse. On a text terminal, if the mouse is not available, the user can choose an alternative using the keyboard motion keys—<kbd>C-n</kbd>, <kbd>C-p</kbd>, or up- and down-arrow keys. </p> <dl> <dt id="x-popup-menu">Function: <strong>x-popup-menu</strong> <em>position menu</em>
</dt> <dd>
<p>This function displays a pop-up menu and returns an indication of what selection the user makes. </p> <p>The argument <var>position</var> 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: </p> <div class="example"> <pre class="example">((<var>xoffset</var> <var>yoffset</var>) <var>window</var>)
</pre>
</div> <p>where <var>xoffset</var> and <var>yoffset</var> are coordinates, measured in pixels, counting from the top left corner of <var>window</var>. <var>window</var> may be a window or a frame. </p> <p>If <var>position</var> is <code>t</code>, it means to use the current mouse position (or the top-left corner of the frame if the mouse is not available on a text terminal). If <var>position</var> is <code>nil</code>, it means to precompute the key binding equivalents for the keymaps specified in <var>menu</var>, without actually displaying or popping up the menu. </p> <p>The argument <var>menu</var> says what to display in the menu. It can be a keymap or a list of keymaps (see <a href="menu-keymaps">Menu Keymaps</a>). 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</code> does not actually execute the command bound to that sequence of events.) On text terminals and toolkits that support menu titles, the title is taken from the prompt string of <var>menu</var> if <var>menu</var> is a keymap, or from the prompt string of the first keymap in <var>menu</var> if it is a list of keymaps (see <a href="defining-menus">Defining Menus</a>). </p> <p>Alternatively, <var>menu</var> can have the following form: </p> <div class="example"> <pre class="example">(<var>title</var> <var>pane1</var> <var>pane2</var>...)
</pre>
</div> <p>where each pane is a list of form </p> <div class="example"> <pre class="example">(<var>title</var> <var>item1</var> <var>item2</var>...)
</pre>
</div> <p>Each <var>item</var> should be a cons cell, <code>(<var>line</var> . <var>value</var>)</code>, where <var>line</var> is a string and <var>value</var> is the value to return if that <var>line</var> is chosen. Unlike in a menu keymap, a <code>nil</code> <var>value</var> does not make the menu item non-selectable. Alternatively, each <var>item</var> can be a string rather than a cons cell; this makes a non-selectable menu item. </p> <p>If the user gets rid of the menu without making a valid choice, for instance by clicking the mouse away from a valid choice or by typing <kbd>C-g</kbd>, then this normally results in a quit and <code>x-popup-menu</code> does not return. But if <var>position</var> is a mouse button event (indicating that the user invoked the menu with the mouse) then no quit occurs and <code>x-popup-menu</code> returns <code>nil</code>. </p>
</dd>
</dl> <p><strong>Usage note:</strong> Don’t use <code>x-popup-menu</code> 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, <kbd>C-h c</kbd> and <kbd>C-h a</kbd> 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 <code>x-popup-menu</code>, the help facilities cannot know what happens inside that command, so they cannot give any help for the menu’s items. </p> <p>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 <code>x-popup-menu</code>. Therefore, if you try to implement a submenu using <code>x-popup-menu</code>, 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 <code>x-popup-menu</code>. See <a href="menu-bar">Menu Bar</a>. </p> <p>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 <code>menu-bar-update-hook</code> to update the contents of the menu keymap as necessary. </p><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Pop_002dUp-Menus.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Pop_002dUp-Menus.html</a>
  </p>
</div>