lisp/tool-bar.el

   1 ;;; tool-bar.el --- setting up the tool bar
   2
   3 ;; Copyright (C) 2000-2018 Free Software Foundation, Inc.
   4
   5 ;; Author: Dave Love <fx@gnu.org>
   6 ;; Keywords: mouse frames
   7 ;; Package: emacs
   8
   9 ;; This file is part of GNU Emacs.
  10
  11 ;; GNU Emacs is free software: you can redistribute it and/or modify
  12 ;; it under the terms of the GNU General Public License as published by
  13 ;; the Free Software Foundation, either version 3 of the License, or
  14 ;; (at your option) any later version.
  15
  16 ;; GNU Emacs is distributed in the hope that it will be useful,
  17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 ;; GNU General Public License for more details.
  20
  21 ;; You should have received a copy of the GNU General Public License
  22 ;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
  23
  24 ;;; Commentary:
  25
  26 ;; Provides `tool-bar-mode' to control display of the tool-bar and
  27 ;; bindings for the global tool bar with convenience functions
  28 ;; `tool-bar-add-item' and `tool-bar-add-item-from-menu'.
  29
  30 ;; The normal global binding for [tool-bar] (below) uses the value of
  31 ;; `tool-bar-map' as the actual keymap to define the tool bar.  Modes
  32 ;; may either bind items under the [tool-bar] prefix key of the local
  33 ;; map to add to the global bar or may set `tool-bar-map'
  34 ;; buffer-locally to override it.  (Some items are removed from the
  35 ;; global bar in modes which have `special' as their `mode-class'
  36 ;; property.)
  37
  38 ;; Todo: Somehow make tool bars easily customizable by the naive?
  39
  40 ;;; Code:
  41
  42 ;; The autoload cookie doesn't work when preloading.
  43 ;; Deleting it means invoking this command won't work
  44 ;; when you are on a tty.  I hope that won't cause too much trouble -- rms.
  45 (define-minor-mode tool-bar-mode
  46   "Toggle the tool bar in all graphical frames (Tool Bar mode).
  47
  48 See `tool-bar-add-item' and `tool-bar-add-item-from-menu' for
  49 conveniently adding tool bar items."
  50   :init-value t
  51   :global t
  52   ;; It's defined in C/cus-start, this stops the d-m-m macro defining it again.
  53   :variable tool-bar-mode
  54   (let ((val (if tool-bar-mode 1 0)))
  55     (dolist (frame (frame-list))
  56       (set-frame-parameter frame 'tool-bar-lines val))
  57     ;; If the user has given `default-frame-alist' a `tool-bar-lines'
  58     ;; parameter, replace it.
  59     (if (assq 'tool-bar-lines default-frame-alist)
  60         (setq default-frame-alist
  61               (cons (cons 'tool-bar-lines val)
  62                     (assq-delete-all 'tool-bar-lines
  63                                      default-frame-alist)))))
  64   (and tool-bar-mode
  65        (= 1 (length (default-value 'tool-bar-map))) ; not yet setup
  66        (tool-bar-setup)))
  67
  68 ;;;###autoload
  69 ;; Used in the Show/Hide menu, to have the toggle reflect the current frame.
  70 (defun toggle-tool-bar-mode-from-frame (&optional arg)
  71   "Toggle tool bar on or off, based on the status of the current frame.
  72 See `tool-bar-mode' for more information."
  73   (interactive (list (or current-prefix-arg 'toggle)))
  74   (if (eq arg 'toggle)
  75       (tool-bar-mode (if (> (frame-parameter nil 'tool-bar-lines) 0) 0 1))
  76     (tool-bar-mode arg)))
  77
  78 (defvar tool-bar-map (make-sparse-keymap)
  79   "Keymap for the tool bar.
  80 Define this locally to override the global tool bar.")
  81
  82 (global-set-key [tool-bar]
  83                 `(menu-item ,(purecopy "tool bar") ignore
  84                             :filter tool-bar-make-keymap))
  85
  86 (declare-function image-mask-p "image.c" (spec &optional frame))
  87
  88 (defconst tool-bar-keymap-cache (make-hash-table :weakness t :test 'equal))
  89
  90 (defun tool-bar-make-keymap (&optional _ignore)
  91   "Generate an actual keymap from `tool-bar-map'.
  92 Its main job is to figure out which images to use based on the display's
  93 color capability and based on the available image libraries."
  94   (let ((key (cons (frame-terminal) tool-bar-map)))
  95     (or (gethash key tool-bar-keymap-cache)
  96         (puthash key (tool-bar-make-keymap-1) tool-bar-keymap-cache))))
  97
  98 (defun tool-bar-make-keymap-1 ()
  99   "Generate an actual keymap from `tool-bar-map', without caching."
 100   (mapcar (lambda (bind)
 101             (let (image-exp plist)
 102               (when (and (eq (car-safe (cdr-safe bind)) 'menu-item)
 103                          ;; For the format of menu-items, see node
 104                          ;; `Extended Menu Items' in the Elisp manual.
 105                          (setq plist (nthcdr (if (consp (nth 4 bind)) 5 4)
 106                                              bind))
 107                          (setq image-exp (plist-get plist :image))
 108                          (consp image-exp)
 109                          (not (eq (car image-exp) 'image))
 110                          (fboundp (car image-exp)))
 111                 (if (not (display-images-p))
 112                     (setq bind nil)
 113                   (let ((image (eval image-exp)))
 114                     (unless (and image (image-mask-p image))
 115                       (setq image (append image '(:mask heuristic))))
 116                     (setq bind (copy-sequence bind)
 117                           plist (nthcdr (if (consp (nth 4 bind)) 5 4)
 118                                         bind))
 119                     (plist-put plist :image image))))
 120               bind))
 121           tool-bar-map))
 122
 123 ;;;###autoload
 124 (defun tool-bar-add-item (icon def key &rest props)
 125   "Add an item to the tool bar.
 126 ICON names the image, DEF is the key definition and KEY is a symbol
 127 for the fake function key in the menu keymap.  Remaining arguments
 128 PROPS are additional items to add to the menu item specification.  See
 129 Info node `(elisp)Tool Bar'.  Items are added from left to right.
 130
 131 ICON is the base name of a file containing the image to use.  The
 132 function will first try to use low-color/ICON.xpm if `display-color-cells'
 133 is less or equal to 256, then ICON.xpm, then ICON.pbm, and finally
 134 ICON.xbm, using `find-image'.
 135
 136 Use this function only to make bindings in the global value of `tool-bar-map'.
 137 To define items in any other map, use `tool-bar-local-item'."
 138   (apply 'tool-bar-local-item icon def key tool-bar-map props))
 139
 140 (defun tool-bar--image-expression (icon)
 141   "Return an expression that evaluates to an image spec for ICON."
 142   (let* ((fg (face-attribute 'tool-bar :foreground))
 143          (bg (face-attribute 'tool-bar :background))
 144          (colors (nconc (if (eq fg 'unspecified) nil (list :foreground fg))
 145                         (if (eq bg 'unspecified) nil (list :background bg))))
 146          (xpm-spec (list :type 'xpm :file (concat icon ".xpm")))
 147          (xpm-lo-spec (list :type 'xpm :file
 148                             (concat "low-color/" icon ".xpm")))
 149          (pbm-spec (append (list :type 'pbm :file
 150                                  (concat icon ".pbm")) colors))
 151          (xbm-spec (append (list :type 'xbm :file
 152                                  (concat icon ".xbm")) colors)))
 153     `(find-image (cond ((not (display-color-p))
 154                         ',(list pbm-spec xbm-spec xpm-lo-spec xpm-spec))
 155                        ((< (display-color-cells) 256)
 156                         ',(list xpm-lo-spec xpm-spec pbm-spec xbm-spec))
 157                        (t
 158                         ',(list xpm-spec pbm-spec xbm-spec))))))
 159
 160 ;;;###autoload
 161 (defun tool-bar-local-item (icon def key map &rest props)
 162   "Add an item to the tool bar in map MAP.
 163 ICON names the image, DEF is the key definition and KEY is a symbol
 164 for the fake function key in the menu keymap.  Remaining arguments
 165 PROPS are additional items to add to the menu item specification.  See
 166 Info node `(elisp)Tool Bar'.  Items are added from left to right.
 167
 168 ICON is the base name of a file containing the image to use.  The
 169 function will first try to use low-color/ICON.xpm if `display-color-cells'
 170 is less or equal to 256, then ICON.xpm, then ICON.pbm, and finally
 171 ICON.xbm, using `find-image'."
 172   (let* ((image-exp (tool-bar--image-expression icon)))
 173     (define-key-after map (vector key)
 174       `(menu-item ,(symbol-name key) ,def :image ,image-exp ,@props))
 175     (force-mode-line-update)))
 176
 177 ;;;###autoload
 178 (defun tool-bar-add-item-from-menu (command icon &optional map &rest props)
 179   "Define tool bar binding for COMMAND in keymap MAP using the given ICON.
 180 This makes a binding for COMMAND in `tool-bar-map', copying its
 181 binding from the menu bar in MAP (which defaults to `global-map'), but
 182 modifies the binding by adding an image specification for ICON.  It
 183 finds ICON just like `tool-bar-add-item'.  PROPS are additional
 184 properties to add to the binding.
 185
 186 MAP must contain appropriate binding for `[menu-bar]' which holds a keymap.
 187
 188 Use this function only to make bindings in the global value of `tool-bar-map'.
 189 To define items in any other map, use `tool-bar-local-item-from-menu'."
 190   (apply 'tool-bar-local-item-from-menu command icon
 191          (default-value 'tool-bar-map) map props))
 192
 193 ;;;###autoload
 194 (defun tool-bar-local-item-from-menu (command icon in-map &optional from-map &rest props)
 195   "Define local tool bar binding for COMMAND using the given ICON.
 196 This makes a binding for COMMAND in IN-MAP, copying its binding from
 197 the menu bar in FROM-MAP (which defaults to `global-map'), but
 198 modifies the binding by adding an image specification for ICON.  It
 199 finds ICON just like `tool-bar-add-item'.  PROPS are additional
 200 properties to add to the binding.
 201
 202 FROM-MAP must contain appropriate binding for `[menu-bar]' which
 203 holds a keymap."
 204   (unless from-map
 205     (setq from-map global-map))
 206   (let* ((menu-bar-map (lookup-key from-map [menu-bar]))
 207          (keys (where-is-internal command menu-bar-map))
 208          (image-exp (tool-bar--image-expression icon))
 209          submap key)
 210     ;; We'll pick up the last valid entry in the list of keys if
 211     ;; there's more than one.
 212     ;; FIXME: Aren't they *all* "valid"??  --Stef
 213     (dolist (k keys)
 214       ;; We're looking for a binding of the command in a submap of
 215       ;; the menu bar map, so the key sequence must be two or more
 216       ;; long.
 217       (if (and (vectorp k)
 218                (> (length k) 1))
 219           (let ((m (lookup-key menu-bar-map (substring k 0 -1)))
 220                 ;; Last element in the bound key sequence:
 221                 (kk (aref k (1- (length k)))))
 222             (if (and (keymapp m)
 223                      (symbolp kk))
 224                 (setq submap m
 225                       key kk)))))
 226     (when (and (symbolp submap) (boundp submap))
 227       (setq submap (eval submap)))
 228     (let ((defn (assq key (cdr submap))))
 229       (if (eq (cadr defn) 'menu-item)
 230           (define-key-after in-map (vector key)
 231             (append (cdr defn) (list :image image-exp) props))
 232         (setq defn (cdr defn))
 233         (define-key-after in-map (vector key)
 234           (let ((rest (cdr defn)))
 235             ;; If the rest of the definition starts
 236             ;; with a list of menu cache info, get rid of that.
 237             (if (and (consp rest) (consp (car rest)))
 238                 (setq rest (cdr rest)))
 239             (append `(menu-item ,(car defn) ,rest)
 240                     (list :image image-exp) props))))
 241       (force-mode-line-update))))
 242
 243 ;;; Set up some global items.  Additions/deletions up for grabs.
 244
 245 (defun tool-bar-setup ()
 246   (setq tool-bar-separator-image-expression
 247         (tool-bar--image-expression "separator"))
 248   (tool-bar-add-item-from-menu 'find-file "new" nil :label "New File"
 249                                :vert-only t)
 250   (tool-bar-add-item-from-menu 'menu-find-file-existing "open" nil
 251                                :label "Open" :vert-only t)
 252   (tool-bar-add-item-from-menu 'dired "diropen" nil :vert-only t)
 253   (tool-bar-add-item-from-menu 'kill-this-buffer "close" nil :vert-only t)
 254   (tool-bar-add-item-from-menu 'save-buffer "save" nil
 255                                :label "Save")
 256   (define-key-after (default-value 'tool-bar-map) [separator-1] menu-bar-separator)
 257   (tool-bar-add-item-from-menu 'undo "undo" nil)
 258   (define-key-after (default-value 'tool-bar-map) [separator-2] menu-bar-separator)
 259   (tool-bar-add-item-from-menu (lookup-key menu-bar-edit-menu [cut])
 260                                "cut" nil :vert-only t)
 261   (tool-bar-add-item-from-menu (lookup-key menu-bar-edit-menu [copy])
 262                                "copy" nil :vert-only t)
 263   (tool-bar-add-item-from-menu (lookup-key menu-bar-edit-menu [paste])
 264                                "paste" nil :vert-only t)
 265   (define-key-after (default-value 'tool-bar-map) [separator-3] menu-bar-separator)
 266   (tool-bar-add-item-from-menu 'isearch-forward "search"
 267                                nil :label "Search" :vert-only t)
 268   ;;(tool-bar-add-item-from-menu 'ispell-buffer "spell")
 269
 270   ;; There's no icon appropriate for News and we need a command rather
 271   ;; than a lambda for Read Mail.
 272   ;;(tool-bar-add-item-from-menu 'compose-mail "mail/compose")
 273
 274   ;; Help button on a tool bar is rather non-standard...
 275   ;; (let ((tool-bar-map (default-value 'tool-bar-map)))
 276   ;;   (tool-bar-add-item "help" (lambda ()
 277   ;;                            (interactive)
 278   ;;                            (popup-menu menu-bar-help-menu))
 279   ;;                   'help
 280   ;;                   :help "Pop up the Help menu"))
 281 )
 282
 283 (if (featurep 'move-toolbar)
 284     (defcustom tool-bar-position 'top
 285       "Specify on which side the tool bar shall be.
 286 Possible values are `top' (tool bar on top), `bottom' (tool bar at bottom),
 287 `left' (tool bar on left) and `right' (tool bar on right).
 288 Customize `tool-bar-mode' if you want to show or hide the tool bar."
 289       :version "24.1"
 290       :type '(choice (const top)
 291                      (const bottom)
 292                      (const left)
 293                      (const right))
 294       :group 'frames
 295       :initialize 'custom-initialize-default
 296       :set (lambda (sym val)
 297              (set-default sym val)
 298              (modify-all-frames-parameters
 299               (list (cons 'tool-bar-position val))))))
 300
 301
 302 (provide 'tool-bar)
 303
 304 ;;; tool-bar.el ends here