diff options
Diffstat (limited to 'devdocs/elisp/tool-bar.html')
| -rw-r--r-- | devdocs/elisp/tool-bar.html | 52 |
1 files changed, 52 insertions, 0 deletions
diff --git a/devdocs/elisp/tool-bar.html b/devdocs/elisp/tool-bar.html new file mode 100644 index 00000000..7e2ee544 --- /dev/null +++ b/devdocs/elisp/tool-bar.html @@ -0,0 +1,52 @@ + <h4 class="subsection">Tool bars</h4> <p>A <em>tool bar</em> is a row of clickable icons at the top of a frame, just below the menu bar. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Tool-Bars.html#Tool-Bars">Tool Bars</a> in <cite>The GNU Emacs Manual</cite>. Emacs normally shows a tool bar on graphical displays. </p> <p>On each frame, the frame parameter <code>tool-bar-lines</code> controls how many lines’ worth of height to reserve for the tool bar. A zero value suppresses the tool bar. If the value is nonzero, and <code>auto-resize-tool-bars</code> is non-<code>nil</code>, the tool bar expands and contracts automatically as needed to hold the specified contents. If the value is <code>grow-only</code>, the tool bar expands automatically, but does not contract automatically. </p> <p>The tool bar contents are controlled by a menu keymap attached to a fake function key called <tt class="key">TOOL-BAR</tt> (much like the way the menu bar is controlled). So you define a tool bar item using <code>define-key</code>, like this: </p> <div class="example"> <pre class="example">(define-key global-map [tool-bar <var>key</var>] <var>item</var>) +</pre> +</div> <p>where <var>key</var> is a fake function key to distinguish this item from other items, and <var>item</var> is a menu item key binding (see <a href="extended-menu-items">Extended Menu Items</a>), which says how to display this item and how it behaves. </p> <p>The usual menu keymap item properties, <code>:visible</code>, <code>:enable</code>, <code>:button</code>, and <code>:filter</code>, are useful in tool bar bindings and have their normal meanings. The <var>real-binding</var> in the item must be a command, not a keymap; in other words, it does not work to define a tool bar icon as a prefix key. </p> <p>The <code>:help</code> property specifies a help-echo string to display while the mouse is on that item. This is displayed in the same way as <code>help-echo</code> text properties (see <a href="special-properties#Help-display">Help display</a>). </p> <p>In addition, you should use the <code>:image</code> property; this is how you specify the image to display in the tool bar: </p> <dl compact> <dt><code>:image <var>image</var></code></dt> <dd> +<p><var>image</var> is either a single image specification (see <a href="images">Images</a>) or a vector of four image specifications. If you use a vector of four, one of them is used, depending on circumstances: </p> <dl compact> <dt>item 0</dt> <dd><p>Used when the item is enabled and selected. </p></dd> <dt>item 1</dt> <dd><p>Used when the item is enabled and deselected. </p></dd> <dt>item 2</dt> <dd><p>Used when the item is disabled and selected. </p></dd> <dt>item 3</dt> <dd><p>Used when the item is disabled and deselected. </p></dd> </dl> </dd> </dl> <p>The GTK+ and NS versions of Emacs ignores items 1 to 3, because disabled and/or deselected images are autocomputed from item 0. </p> <p>If <var>image</var> is a single image specification, Emacs draws the tool bar button in disabled state by applying an edge-detection algorithm to the image. </p> <p>The <code>:rtl</code> property specifies an alternative image to use for right-to-left languages. Only the GTK+ version of Emacs supports this at present. </p> <p>Like the menu bar, the tool bar can display separators (see <a href="menu-separators">Menu Separators</a>). Tool bar separators are vertical rather than horizontal, though, and only a single style is supported. They are represented in the tool bar keymap by <code>(menu-item "--")</code> entries; properties like <code>:visible</code> are not supported for tool bar separators. Separators are rendered natively in GTK+ and Nextstep tool bars; in the other cases, they are rendered using an image of a vertical line. </p> <p>The default tool bar is defined so that items specific to editing do not appear for major modes whose command symbol has a <code>mode-class</code> property of <code>special</code> (see <a href="major-mode-conventions">Major Mode Conventions</a>). Major modes may add items to the global bar by binding <code>[tool-bar +<var>foo</var>]</code> in their local map. It makes sense for some major modes to replace the default tool bar items completely, since not many can be accommodated conveniently, and the default bindings make this easy by using an indirection through <code>tool-bar-map</code>. </p> <dl> <dt id="tool-bar-map">Variable: <strong>tool-bar-map</strong> +</dt> <dd> +<p>By default, the global map binds <code>[tool-bar]</code> as follows: </p> <div class="example"> <pre class="example">(global-set-key [tool-bar] + `(menu-item ,(purecopy "tool bar") ignore + :filter tool-bar-make-keymap)) +</pre> +</div> <p>The function <code>tool-bar-make-keymap</code>, in turn, derives the actual tool bar map dynamically from the value of the variable <code>tool-bar-map</code>. Hence, you should normally adjust the default (global) tool bar by changing that map. Some major modes, such as Info mode, completely replace the global tool bar by making <code>tool-bar-map</code> buffer-local and setting it to a different keymap. </p> +</dd> +</dl> <p>There are two convenience functions for defining tool bar items, as follows. </p> <dl> <dt id="tool-bar-add-item">Function: <strong>tool-bar-add-item</strong> <em>icon def key &rest props</em> +</dt> <dd> +<p>This function adds an item to the tool bar by modifying <code>tool-bar-map</code>. The image to use is defined by <var>icon</var>, which is the base name of an XPM, XBM or PBM image file to be located by <code>find-image</code>. Given a value ‘<samp>"exit"</samp>’, say, <samp>exit.xpm</samp>, <samp>exit.pbm</samp> and <samp>exit.xbm</samp> would be searched for in that order on a color display. On a monochrome display, the search order is ‘<samp>.pbm</samp>’, ‘<samp>.xbm</samp>’ and ‘<samp>.xpm</samp>’. The binding to use is the command <var>def</var>, and <var>key</var> is the fake function key symbol in the prefix keymap. The remaining arguments <var>props</var> are additional property list elements to add to the menu item specification. </p> <p>To define items in some local map, bind <code>tool-bar-map</code> with <code>let</code> around calls of this function: </p> +<div class="example"> <pre class="example">(defvar foo-tool-bar-map + (let ((tool-bar-map (make-sparse-keymap))) + (tool-bar-add-item …) + … + tool-bar-map)) +</pre> +</div> </dd> +</dl> <dl> <dt id="tool-bar-add-item-from-menu">Function: <strong>tool-bar-add-item-from-menu</strong> <em>command icon &optional map &rest props</em> +</dt> <dd> +<p>This function is a convenience for defining tool bar items which are consistent with existing menu bar bindings. The binding of <var>command</var> is looked up in the menu bar in <var>map</var> (default <code>global-map</code>) and modified to add an image specification for <var>icon</var>, which is found in the same way as by <code>tool-bar-add-item</code>. The resulting binding is then placed in <code>tool-bar-map</code>, so use this function only for global tool bar items. </p> <p><var>map</var> must contain an appropriate keymap bound to <code>[menu-bar]</code>. The remaining arguments <var>props</var> are additional property list elements to add to the menu item specification. </p> +</dd> +</dl> <dl> <dt id="tool-bar-local-item-from-menu">Function: <strong>tool-bar-local-item-from-menu</strong> <em>command icon in-map &optional from-map &rest props</em> +</dt> <dd><p>This function is used for making non-global tool bar items. Use it like <code>tool-bar-add-item-from-menu</code> except that <var>in-map</var> specifies the local map to make the definition in. The argument <var>from-map</var> is like the <var>map</var> argument of <code>tool-bar-add-item-from-menu</code>. </p></dd> +</dl> <dl> <dt id="auto-resize-tool-bars">Variable: <strong>auto-resize-tool-bars</strong> +</dt> <dd> +<p>If this variable is non-<code>nil</code>, the tool bar automatically resizes to show all defined tool bar items—but not larger than a quarter of the frame’s height. </p> <p>If the value is <code>grow-only</code>, the tool bar expands automatically, but does not contract automatically. To contract the tool bar, the user has to redraw the frame by entering <kbd>C-l</kbd>. </p> <p>If Emacs is built with GTK+ or Nextstep, the tool bar can only show one line, so this variable has no effect. </p> +</dd> +</dl> <dl> <dt id="auto-raise-tool-bar-buttons">Variable: <strong>auto-raise-tool-bar-buttons</strong> +</dt> <dd><p>If this variable is non-<code>nil</code>, tool bar items display in raised form when the mouse moves over them. </p></dd> +</dl> <dl> <dt id="tool-bar-button-margin">Variable: <strong>tool-bar-button-margin</strong> +</dt> <dd><p>This variable specifies an extra margin to add around tool bar items. The value is an integer, a number of pixels. The default is 4. </p></dd> +</dl> <dl> <dt id="tool-bar-button-relief">Variable: <strong>tool-bar-button-relief</strong> +</dt> <dd><p>This variable specifies the shadow width for tool bar items. The value is an integer, a number of pixels. The default is 1. </p></dd> +</dl> <dl> <dt id="tool-bar-border">Variable: <strong>tool-bar-border</strong> +</dt> <dd><p>This variable specifies the height of the border drawn below the tool bar area. An integer specifies height as a number of pixels. If the value is one of <code>internal-border-width</code> (the default) or <code>border-width</code>, the tool bar border height corresponds to the corresponding frame parameter. </p></dd> +</dl> <p>You can define a special meaning for clicking on a tool bar item with the shift, control, meta, etc., modifiers. You do this by setting up additional items that relate to the original item through the fake function keys. Specifically, the additional items should use the modified versions of the same fake function key used to name the original item. </p> <p>Thus, if the original item was defined this way, </p> <div class="example"> <pre class="example">(define-key global-map [tool-bar shell] + '(menu-item "Shell" shell + :image (image :type xpm :file "shell.xpm"))) +</pre> +</div> <p>then here is how you can define clicking on the same tool bar image with the shift modifier: </p> <div class="example"> <pre class="example">(define-key global-map [tool-bar S-shell] 'some-command) +</pre> +</div> <p>See <a href="function-keys">Function Keys</a>, for more information about how to add modifiers to function keys. </p> <p>If you have functions that change whether a tool bar item is enabled or not, this status is not necessarily updated visually immediately. To force recalculation of the tool bar, call <code>force-mode-line-update</code> (see <a href="mode-line-format">Mode Line Format</a>). </p><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 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/Tool-Bar.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Tool-Bar.html</a> + </p> +</div> |