new repository

1 files changed, 29 insertions, 0 deletions

diff --git a/devdocs/elisp/menu-bar.html b/devdocs/elisp/menu-bar.html
new file mode 100644
index 00000000..238fca55
--- /dev/null
+++ b/devdocs/elisp/menu-bar.html
@@ -0,0 +1,29 @@
+ <h4 class="subsection">The Menu Bar</h4>  <p>Emacs usually shows a <em>menu bar</em> at the top of each frame. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Menu-Bars.html#Menu-Bars">Menu Bars</a> in <cite>The GNU Emacs Manual</cite>. Menu bar items are subcommands of the fake function key <tt class="key">MENU-BAR</tt>, as defined in the active keymaps. </p> <p>To add an item to the menu bar, invent a fake function key of your own (let’s call it <var>key</var>), and make a binding for the key sequence <code>[menu-bar <var>key</var>]</code>. Most often, the binding is a menu keymap, so that pressing a button on the menu bar item leads to another menu. </p> <p>When more than one active keymap defines the same function key for the menu bar, the item appears just once. If the user clicks on that menu bar item, it brings up a single, combined menu containing all the subcommands of that item—the global subcommands, the local subcommands, and the minor mode subcommands. </p> <p>The variable <code>overriding-local-map</code> is normally ignored when determining the menu bar contents. That is, the menu bar is computed from the keymaps that would be active if <code>overriding-local-map</code> were <code>nil</code>. See <a href="active-keymaps">Active Keymaps</a>. </p> <p>Here’s an example of setting up a menu bar item: </p> <div class="example"> <pre class="example">;; <span class="roman">Make a menu keymap (with a prompt string)</span>
+;; <span class="roman">and make it the menu bar item’s definition.</span>
+(define-key global-map [menu-bar words]
+  (cons "Words" (make-sparse-keymap "Words")))
+</pre>
+
+<pre class="example">;; <span class="roman">Define specific subcommands in this menu.</span>
+(define-key global-map
+  [menu-bar words forward]
+  '("Forward word" . forward-word))
+</pre>
+<pre class="example">(define-key global-map
+  [menu-bar words backward]
+  '("Backward word" . backward-word))
+</pre>
+</div> <p>A local keymap can cancel a menu bar item made by the global keymap by rebinding the same fake function key with <code>undefined</code> as the binding. For example, this is how Dired suppresses the ‘<samp>Edit</samp>’ menu bar item: </p> <div class="example"> <pre class="example">(define-key dired-mode-map [menu-bar edit] 'undefined)
+</pre>
+</div> <p>Here, <code>edit</code> is the symbol produced by a fake function key, it is used by the global map for the ‘<samp>Edit</samp>’ menu bar item. The main reason to suppress a global menu bar item is to regain space for mode-specific items. </p> <dl> <dt id="menu-bar-final-items">Variable: <strong>menu-bar-final-items</strong>
+</dt> <dd>
+<p>Normally the menu bar shows global items followed by items defined by the local maps. </p> <p>This variable holds a list of fake function keys for items to display at the end of the menu bar rather than in normal sequence. The default value is <code>(help-menu)</code>; thus, the ‘<samp>Help</samp>’ menu item normally appears at the end of the menu bar, following local menu items. </p>
+</dd>
+</dl> <dl> <dt id="menu-bar-update-hook">Variable: <strong>menu-bar-update-hook</strong>
+</dt> <dd><p>This normal hook is run by redisplay to update the menu bar contents, before redisplaying the menu bar. You can use it to update menus whose contents should vary. Since this hook is run frequently, we advise you to ensure that the functions it calls do not take much time in the usual case. </p></dd>
+</dl> <p>Next to every menu bar item, Emacs displays a key binding that runs the same command (if such a key binding exists). This serves as a convenient hint for users who do not know the key binding. If a command has multiple bindings, Emacs normally displays the first one it finds. You can specify one particular key binding by assigning an <code>:advertised-binding</code> symbol property to the command. See <a href="keys-in-documentation">Keys in Documentation</a>. </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/Menu-Bar.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Menu-Bar.html</a>
+  </p>
+</div>