lisp/tool-bar.el

   1 ;;; tool-bar.el --- setting up the tool bar
   2 ;;
   3 ;; Copyright (C) 2000, 2001, 2002, 2003, 2004,
   4 ;;   2005, 2006, 2007, 2008 Free Software Foundation, Inc.
   5 ;;
   6 ;; Author: Dave Love <fx@gnu.org>
   7 ;; Keywords: mouse frames
   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 <http://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 use of the tool bar.
  47 With numeric ARG, display the tool bar if and only if ARG is positive.
  48
  49 See `tool-bar-add-item' and `tool-bar-add-item-from-menu' for
  50 conveniently adding tool bar items."
  51   :init-value nil
  52   :global t
  53   :group 'mouse
  54   :group 'frames
  55   (if tool-bar-mode
  56       (progn
  57         (dolist (frame (frame-list))
  58           (if (display-graphic-p frame)
  59               (set-frame-parameter frame 'tool-bar-lines 1)))
  60         (if (= 1 (length (default-value 'tool-bar-map))) ; not yet setup
  61             (tool-bar-setup)))
  62     (modify-all-frames-parameters (list (cons 'tool-bar-lines 0)))))
  63
  64 ;;;###autoload
  65 ;; Used in the Show/Hide menu, to have the toggle reflect the current frame.
  66 (defun toggle-tool-bar-mode-from-frame (&optional arg)
  67   "Toggle tool bar on or off, based on the status of the current frame.
  68 See `tool-bar-mode' for more information."
  69   (interactive (list (or current-prefix-arg 'toggle)))
  70   (if (eq arg 'toggle)
  71       (tool-bar-mode (if (> (frame-parameter nil 'tool-bar-lines) 0) 0 1))
  72     (tool-bar-mode arg)))
  73
  74 ;;;###autoload
  75 ;; We want to pretend the toolbar by standard is on, as this will make
  76 ;; customize consider disabling the toolbar a customization, and save
  77 ;; that.  We could do this for real by setting :init-value above, but
  78 ;; that would turn on the toolbar in MS Windows where it is currently
  79 ;; useless, and it would overwrite disabling the tool bar from X
  80 ;; resources.  If anyone want to implement this in a cleaner way,
  81 ;; please do so.
  82 ;; -- Per Abrahamsen <abraham@dina.kvl.dk> 2002-02-21.
  83 (put 'tool-bar-mode 'standard-value '(t))
  84
  85 (defvar tool-bar-map (make-sparse-keymap)
  86   "Keymap for the tool bar.
  87 Define this locally to override the global tool bar.")
  88
  89 (global-set-key [tool-bar]
  90                 '(menu-item "tool bar" ignore
  91                             :filter tool-bar-make-keymap))
  92
  93 (declare-function image-mask-p "image.c" (spec &optional frame))
  94
  95 (defconst tool-bar-keymap-cache (make-hash-table :weakness t :test 'equal))
  96
  97 (defun tool-bar-make-keymap (&optional ignore)
  98   "Generate an actual keymap from `tool-bar-map'.
  99 Its main job is to figure out which images to use based on the display's
 100 color capability and based on the available image libraries."
 101   (let ((key (cons (frame-terminal) tool-bar-map)))
 102     (or (gethash key tool-bar-keymap-cache)
 103         (puthash key (tool-bar-make-keymap-1) tool-bar-keymap-cache))))
 104
 105 (defun tool-bar-make-keymap-1 ()
 106   "Generate an actual keymap from `tool-bar-map', without caching."
 107   (mapcar (lambda (bind)
 108             (let (image-exp plist)
 109               (when (and (eq (car-safe (cdr-safe bind)) 'menu-item)
 110                          ;; For the format of menu-items, see node
 111                          ;; `Extended Menu Items' in the Elisp manual.
 112                          (setq plist (nthcdr (if (consp (nth 4 bind)) 5 4)
 113                                              bind))
 114                          (setq image-exp (plist-get plist :image))
 115                          (consp image-exp)
 116                          (not (eq (car image-exp) 'image))
 117                          (fboundp (car image-exp)))
 118                 (if (not (display-images-p))
 119                     (setq bind nil)
 120                   (let ((image (eval image-exp)))
 121                     (unless (and image (image-mask-p image))
 122                       (setq image (append image '(:mask heuristic))))
 123                     (setq bind (copy-sequence bind)
 124                           plist (nthcdr (if (consp (nth 4 bind)) 5 4)
 125                                         bind))
 126                     (plist-put plist :image image))))
 127               bind))
 128           tool-bar-map))
 129
 130 ;;;###autoload
 131 (defun tool-bar-add-item (icon def key &rest props)
 132   "Add an item to the tool bar.
 133 ICON names the image, DEF is the key definition and KEY is a symbol
 134 for the fake function key in the menu keymap.  Remaining arguments
 135 PROPS are additional items to add to the menu item specification.  See
 136 Info node `(elisp)Tool Bar'.  Items are added from left to right.
 137
 138 ICON is the base name of a file containing the image to use.  The
 139 function will first try to use low-color/ICON.xpm if `display-color-cells'
 140 is less or equal to 256, then ICON.xpm, then ICON.pbm, and finally
 141 ICON.xbm, using `find-image'.
 142
 143 Use this function only to make bindings in the global value of `tool-bar-map'.
 144 To define items in any other map, use `tool-bar-local-item'."
 145   (apply 'tool-bar-local-item icon def key tool-bar-map props))
 146
 147 ;;;###autoload
 148 (defun tool-bar-local-item (icon def key map &rest props)
 149   "Add an item to the tool bar in map MAP.
 150 ICON names the image, DEF is the key definition and KEY is a symbol
 151 for the fake function key in the menu keymap.  Remaining arguments
 152 PROPS are additional items to add to the menu item specification.  See
 153 Info node `(elisp)Tool Bar'.  Items are added from left to right.
 154
 155 ICON is the base name of a file containing the image to use.  The
 156 function will first try to use low-color/ICON.xpm if `display-color-cells'
 157 is less or equal to 256, then ICON.xpm, then ICON.pbm, and finally
 158 ICON.xbm, using `find-image'."
 159   (let* ((fg (face-attribute 'tool-bar :foreground))
 160          (bg (face-attribute 'tool-bar :background))
 161          (colors (nconc (if (eq fg 'unspecified) nil (list :foreground fg))
 162                         (if (eq bg 'unspecified) nil (list :background bg))))
 163          (xpm-spec (list :type 'xpm :file (concat icon ".xpm")))
 164          (xpm-lo-spec (list :type 'xpm :file
 165                             (concat "low-color/" icon ".xpm")))
 166          (pbm-spec (append (list :type 'pbm :file
 167                                  (concat icon ".pbm")) colors))
 168          (xbm-spec (append (list :type 'xbm :file
 169                                  (concat icon ".xbm")) colors))
 170          (image-exp `(find-image
 171                       (cond ((not (display-color-p))
 172                              ',(list pbm-spec xbm-spec xpm-lo-spec xpm-spec))
 173                             ((< (display-color-cells) 256)
 174                              ',(list xpm-lo-spec xpm-spec pbm-spec xbm-spec))
 175                             (t
 176                              ',(list xpm-spec pbm-spec xbm-spec))))))
 177     (define-key-after map (vector key)
 178       `(menu-item ,(symbol-name key) ,def :image ,image-exp ,@props))))
 179
 180 ;;;###autoload
 181 (defun tool-bar-add-item-from-menu (command icon &optional map &rest props)
 182   "Define tool bar binding for COMMAND in keymap MAP using the given ICON.
 183 This makes a binding for COMMAND in `tool-bar-map', copying its
 184 binding from the menu bar in MAP (which defaults to `global-map'), but
 185 modifies the binding by adding an image specification for ICON.  It
 186 finds ICON just like `tool-bar-add-item'.  PROPS are additional
 187 properties to add to the binding.
 188
 189 MAP must contain appropriate binding for `[menu-bar]' which holds a keymap.
 190
 191 Use this function only to make bindings in the global value of `tool-bar-map'.
 192 To define items in any other map, use `tool-bar-local-item-from-menu'."
 193   (apply 'tool-bar-local-item-from-menu command icon
 194          (default-value 'tool-bar-map) map props))
 195
 196 ;;;###autoload
 197 (defun tool-bar-local-item-from-menu (command icon in-map &optional from-map &rest props)
 198   "Define local tool bar binding for COMMAND using the given ICON.
 199 This makes a binding for COMMAND in IN-MAP, copying its binding from
 200 the menu bar in FROM-MAP (which defaults to `global-map'), but
 201 modifies the binding by adding an image specification for ICON.  It
 202 finds ICON just like `tool-bar-add-item'.  PROPS are additional
 203 properties to add to the binding.
 204
 205 FROM-MAP must contain appropriate binding for `[menu-bar]' which
 206 holds a keymap."
 207   (unless from-map
 208     (setq from-map global-map))
 209   (let* ((menu-bar-map (lookup-key from-map [menu-bar]))
 210          (keys (where-is-internal command menu-bar-map))
 211          (fg (face-attribute 'tool-bar :foreground))
 212          (bg (face-attribute 'tool-bar :background))
 213          (colors (nconc (if (eq fg 'unspecified) nil (list :foreground fg))
 214                         (if (eq bg 'unspecified) nil (list :background bg))))
 215          (xpm-spec (list :type 'xpm :file (concat icon ".xpm")))
 216          (xpm-lo-spec (list :type 'xpm :file
 217                             (concat "low-color/" icon ".xpm")))
 218          (pbm-spec (append (list :type 'pbm :file
 219                                  (concat icon ".pbm")) colors))
 220          (xbm-spec (append (list :type 'xbm :file
 221                                  (concat icon ".xbm")) colors))
 222          (image-exp `(find-image
 223                       (cond ((not (display-color-p))
 224                              ',(list pbm-spec xbm-spec xpm-lo-spec xpm-spec))
 225                             ((< (display-color-cells) 256)
 226                              ',(list xpm-lo-spec xpm-spec pbm-spec xbm-spec))
 227                             (t
 228                              ',(list xpm-spec pbm-spec xbm-spec)))))
 229          submap key)
 230     ;; We'll pick up the last valid entry in the list of keys if
 231     ;; there's more than one.
 232     (dolist (k keys)
 233       ;; We're looking for a binding of the command in a submap of
 234       ;; the menu bar map, so the key sequence must be two or more
 235       ;; long.
 236       (if (and (vectorp k)
 237                (> (length k) 1))
 238           (let ((m (lookup-key menu-bar-map (substring k 0 -1)))
 239                 ;; Last element in the bound key sequence:
 240                 (kk (aref k (1- (length k)))))
 241             (if (and (keymapp m)
 242                      (symbolp kk))
 243                 (setq submap m
 244                       key kk)))))
 245     (when (and (symbolp submap) (boundp submap))
 246       (setq submap (eval submap)))
 247     (let ((defn (assq key (cdr submap))))
 248       (if (eq (cadr defn) 'menu-item)
 249           (define-key-after in-map (vector key)
 250             (append (cdr defn) (list :image image-exp) props))
 251         (setq defn (cdr defn))
 252         (define-key-after in-map (vector key)
 253           (let ((rest (cdr defn)))
 254             ;; If the rest of the definition starts
 255             ;; with a list of menu cache info, get rid of that.
 256             (if (and (consp rest) (consp (car rest)))
 257                 (setq rest (cdr rest)))
 258             (append `(menu-item ,(car defn) ,rest)
 259                     (list :image image-exp) props)))))))
 260
 261 ;;; Set up some global items.  Additions/deletions up for grabs.
 262
 263 (defun tool-bar-setup ()
 264   ;; People say it's bad to have EXIT on the tool bar, since users
 265   ;; might inadvertently click that button.
 266   ;;(tool-bar-add-item-from-menu 'save-buffers-kill-emacs "exit")
 267   (tool-bar-add-item-from-menu 'find-file "new")
 268   (tool-bar-add-item-from-menu 'menu-find-file-existing "open")
 269   (tool-bar-add-item-from-menu 'dired "diropen")
 270   (tool-bar-add-item-from-menu 'kill-this-buffer "close")
 271   (tool-bar-add-item-from-menu 'save-buffer "save" nil
 272                                :visible '(or buffer-file-name
 273                                              (not (eq 'special
 274                                                       (get major-mode
 275                                                            'mode-class)))))
 276   (tool-bar-add-item-from-menu 'write-file "saveas" nil
 277                                :visible '(or buffer-file-name
 278                                              (not (eq 'special
 279                                                       (get major-mode
 280                                                            'mode-class)))))
 281   (tool-bar-add-item-from-menu 'undo "undo" nil
 282                                :visible '(not (eq 'special (get major-mode
 283                                                                 'mode-class))))
 284   (tool-bar-add-item-from-menu (lookup-key menu-bar-edit-menu [cut])
 285                                "cut" nil
 286                                :visible '(not (eq 'special (get major-mode
 287                                                                 'mode-class))))
 288   (tool-bar-add-item-from-menu (lookup-key menu-bar-edit-menu [copy])
 289                                "copy")
 290   (tool-bar-add-item-from-menu (lookup-key menu-bar-edit-menu [paste])
 291                                "paste" nil
 292                                :visible '(not (eq 'special (get major-mode
 293                                                                 'mode-class))))
 294   (tool-bar-add-item-from-menu 'nonincremental-search-forward "search")
 295   ;;(tool-bar-add-item-from-menu 'ispell-buffer "spell")
 296
 297   ;; There's no icon appropriate for News and we need a command rather
 298   ;; than a lambda for Read Mail.
 299   ;;(tool-bar-add-item-from-menu 'compose-mail "mail/compose")
 300
 301   (tool-bar-add-item-from-menu 'print-buffer "print")
 302
 303   ;; tool-bar-add-item-from-menu itself operates on
 304   ;; (default-value 'tool-bar-map), but when we don't use that function,
 305   ;; we must explicitly operate on the default value.
 306
 307   (let ((tool-bar-map (default-value 'tool-bar-map)))
 308     (tool-bar-add-item "preferences" 'customize 'customize
 309                        :help "Edit preferences (customize)")
 310
 311     (tool-bar-add-item "help" (lambda ()
 312                                 (interactive)
 313                                 (popup-menu menu-bar-help-menu))
 314                        'help
 315                        :help "Pop up the Help menu")))
 316
 317
 318 (provide 'tool-bar)
 319 ;; arch-tag: 15f30f0a-d0d7-4d50-bbb7-f48fd0c8582f
 320 ;;; tool-bar.el ends here