path: root/devdocs/elisp/easy-menu.html

 <h4 class="subsection">Easy Menu</h4> <p>The following macro provides a convenient way to define pop-up menus and/or menu bar menus. </p> <dl> <dt id="easy-menu-define">Macro: <strong>easy-menu-define</strong> <em>symbol maps doc menu</em>
</dt> <dd>
<p>This macro defines a pop-up menu and/or menu bar submenu, whose contents are given by <var>menu</var>. </p> <p>If <var>symbol</var> is non-<code>nil</code>, it should be a symbol; then this macro defines <var>symbol</var> as a function for popping up the menu (see <a href="pop_002dup-menus">Pop-Up Menus</a>), with <var>doc</var> as its documentation string. <var>symbol</var> should not be quoted. </p> <p>Regardless of the value of <var>symbol</var>, if <var>maps</var> is a keymap, the menu is added to that keymap, as a top-level menu for the menu bar (see <a href="menu-bar">Menu Bar</a>). It can also be a list of keymaps, in which case the menu is added separately to each of those keymaps. </p> <p>The first element of <var>menu</var> must be a string, which serves as the menu label. It may be followed by any number of the following keyword-argument pairs: </p> <dl compact> <dt><code>:filter <var>function</var></code></dt> <dd>
<p><var>function</var> must be a function which, if called with one argument—the list of the other menu items—returns the actual items to be displayed in the menu. </p> </dd> <dt><code>:visible <var>include</var></code></dt> <dd>
<p><var>include</var> is an expression; if it evaluates to <code>nil</code>, the menu is made invisible. <code>:included</code> is an alias for <code>:visible</code>. </p> </dd> <dt><code>:active <var>enable</var></code></dt> <dd><p><var>enable</var> is an expression; if it evaluates to <code>nil</code>, the menu is not selectable. <code>:enable</code> is an alias for <code>:active</code>. </p></dd> </dl> <p>The remaining elements in <var>menu</var> are menu items. </p> <p>A menu item can be a vector of three elements, <code>[<var>name</var>
<var>callback</var> <var>enable</var>]</code>. <var>name</var> is the menu item name (a string). <var>callback</var> is a command to run, or an expression to evaluate, when the item is chosen. <var>enable</var> is an expression; if it evaluates to <code>nil</code>, the item is disabled for selection. </p> <p>Alternatively, a menu item may have the form: </p> <div class="example"> <pre class="example">   [ <var>name</var> <var>callback</var> [ <var>keyword</var> <var>arg</var> ]... ]
</pre>
</div> <p>where <var>name</var> and <var>callback</var> have the same meanings as above, and each optional <var>keyword</var> and <var>arg</var> pair should be one of the following: </p> <dl compact> <dt><code>:keys <var>keys</var></code></dt> <dd>
<p><var>keys</var> is a string to display as keyboard equivalent to the menu item. This is normally not needed, as keyboard equivalents are computed automatically. <var>keys</var> is expanded with <code>substitute-command-keys</code> before it is displayed (see <a href="keys-in-documentation">Keys in Documentation</a>). </p> </dd> <dt><code>:key-sequence <var>keys</var></code></dt> <dd>
<p><var>keys</var> is a hint indicating which key sequence to display as keyboard equivalent, in case the command is bound to several key sequences. It has no effect if <var>keys</var> is not bound to same command as this menu item. </p> </dd> <dt><code>:active <var>enable</var></code></dt> <dd>
<p><var>enable</var> is an expression; if it evaluates to <code>nil</code>, the item is made unselectable. <code>:enable</code> is an alias for <code>:active</code>. </p> </dd> <dt><code>:visible <var>include</var></code></dt> <dd>
<p><var>include</var> is an expression; if it evaluates to <code>nil</code>, the item is made invisible. <code>:included</code> is an alias for <code>:visible</code>. </p> </dd> <dt><code>:label <var>form</var></code></dt> <dd>
<p><var>form</var> is an expression that is evaluated to obtain a value which serves as the menu item’s label (the default is <var>name</var>). </p> </dd> <dt><code>:suffix <var>form</var></code></dt> <dd>
<p><var>form</var> is an expression that is dynamically evaluated and whose value is concatenated with the menu entry’s label. </p> </dd> <dt><code>:style <var>style</var></code></dt> <dd>
<p><var>style</var> is a symbol describing the type of menu item; it should be <code>toggle</code> (a checkbox), or <code>radio</code> (a radio button), or anything else (meaning an ordinary menu item). </p> </dd> <dt><code>:selected <var>selected</var></code></dt> <dd>
<p><var>selected</var> is an expression; the checkbox or radio button is selected whenever the expression’s value is non-<code>nil</code>. </p> </dd> <dt><code>:help <var>help</var></code></dt> <dd><p><var>help</var> is a string describing the menu item. </p></dd> </dl> <p>Alternatively, a menu item can be a string. Then that string appears in the menu as unselectable text. A string consisting of dashes is displayed as a separator (see <a href="menu-separators">Menu Separators</a>). </p> <p>Alternatively, a menu item can be a list with the same format as <var>menu</var>. This is a submenu. </p>
</dd>
</dl> <p>Here is an example of using <code>easy-menu-define</code> to define a menu similar to the one defined in the example in <a href="menu-bar">Menu Bar</a>: </p> <div class="example"> <pre class="example">(easy-menu-define words-menu global-map
  "Menu for word navigation commands."
  '("Words"
     ["Forward word" forward-word]
     ["Backward word" backward-word]))
</pre>
</div><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/Easy-Menu.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Easy-Menu.html</a>
  </p>
</div>