lisp/ess-toolbar.el

   1 ;;; ess-toolbar.el --- Support for a toolbar in ESS.
   2
   3 ;; Copyright (C) 1997--2004 A.J. Rossini, Rich M. Heiberger, Martin
   4 ;;      Maechler, Kurt Hornik, Rodney Sparapani, and Stephen Eglen.
   5
   6 ;; Original Author: Stephen Eglen
   7 ;; Created: 06 May 2004
   8 ;; Maintainers: ESS-core <ESS-core@stat.math.ethz.ch>
   9
  10 ;; This file is part of ESS
  11
  12 ;; GPL --> see beginning of ./ess-site.el
  13
  14 ;;; Commentary:
  15
  16 ;;; This code adds a toolbar to ESS modes for editing R and S code.
  17 ;;; Support can be added for other modes (e.g. STATA), just ask!
  18 ;;;
  19 ;;; This code is experimental, and runs best on Emacs 21 and XEmacs
  20 ;;; 21.  It has been tested only on Linux machines.  All feedback
  21 ;;; appreciated.
  22 ;;; To use this code, place the following in .emacs after you have
  23 ;;; loaded ess-site:
  24 ;;;
  25 ;;; (setq ess-use-toolbar t)
  26 ;;; (if (fboundp 'tool-bar-mode) (tool-bar-mode t))     ;Emacs 21.
  27 ;;; (require 'ess-toolbar)
  28 ;;; If you see a toolbar, but no icons, check out the value of
  29 ;;; ess-icon-directory.
  30 ;;;
  31 ;;; The toolbar can be customized in several ways.  To see options, do:
  32 ;;; M-x customize-group RET ess-toolbar RET
  33 ;;; If you change any of the variables, you may need to restart Emacs
  34 ;;; to see any effect.  See also the documentation for ess-toolbar-items
  35 ;;; if you wish to change its value.
  36 ;;;
  37 ;;; Technical issues.
  38 ;; Emacs vs XEmacs.
  39 ;; Of course, Emacs and XEmacs have different interfaces and handle
  40 ;; the toolbars in different ways.  The code here is rough, but
  41 ;; hopefully soon a compatibility toolbar library will be released
  42 ;; that will make the toolbar code more portable.  So, for now the
  43 ;; code should be regarded as proof of concept.
  44
  45 ;; Also, I think the CVS GNU Emacs now has tool-bar support for the
  46 ;; Mac OS X.
  47
  48 ;;; Code:
  49
  50 (defgroup ess-toolbar nil
  51   "ESS: toolbar support."
  52   :group 'ess
  53   :link '(emacs-commentary-link :tag "Commentary" "ess-toolbar.el")
  54   :prefix "ess-")
  55
  56 (defcustom ess-use-toolbar
  57   (if (featurep 'xemacs)
  58       (memq (device-type) '(x gtk mswindows))
  59     (and (fboundp 'display-images-p) (display-images-p)))
  60   "*Non-nil means ESS should support the toolbar.
  61 Currently works only under Emacs 21 and maybe XEmacs 21.4."
  62   :group 'ess-toolbar
  63   :type 'boolean)
  64
  65
  66 (defcustom ess-toolbar-own-icons nil
  67   "*Non-nil means that we only put our toolbar entries in ESS.
  68 Otherwise we get standard toolbar as well as ESS entries.
  69 Under Emacs, the standard toolbar items are copied from the default toolbar.
  70 Under XEmacs, the items stored in `ess-toolbar-xemacs-general' are added."
  71   :group 'ess-toolbar
  72   :type 'boolean)
  73
  74 (defcustom ess-toolbar-global nil
  75   "*Non-nil means that the ESS toolbar is available in all emacs buffers.
  76 Otherwise, the ESS toolbar is present only in R/S mode buffers.
  77 For beginners, this is probably better set to a non-nil value."
  78   :group 'ess-toolbar
  79   :type 'boolean)
  80
  81 (defcustom ess-toolbar-items
  82   '( (R   "startr"  "Start R process")
  83      (S   "spluslogo" "Start S process")
  84      (ess-eval-line-and-step   "rline" "Eval line & step")
  85      (ess-eval-region   "rregion" "Eval region")
  86      (ess-load-file   "rbuffer" "Load file")
  87      (ess-eval-function   "rfunction" "Eval function")
  88      (ess-switch-to-ESS   "switch_ess" "Switch to ESS buffer"))
  89   "Items to be added to the ESS toolbar.
  90 Each list element has three items:
  91 1. the name of the function to run
  92 2. the icon to be used (without .xpm extension)
  93 3. the tooltip doc string (XEmacs only; Emacs gets doc string from menu items.
  94
  95 General toolbar items are also added to the ESS toolbar
  96 iff `ess-toolbar-own-icons' is nil.
  97
  98 Setting this variable with setq doesn't take effect once you have
  99 loaded ess-site, unless you follow it by a call to
 100 `ess-make-toolbar' afterwards.  Instead, change its value using
 101 Custom, and then on all new ESS buffers you should see the
 102 toolbar has changed."
 103   :group 'ess-toolbar
 104   :set (lambda (symbol value)
 105          (set-default symbol value)
 106          (if (fboundp 'ess-make-toolbar)
 107              (ess-make-toolbar)))
 108   :type '(repeat (list (function :tag "Function to run")
 109                        (string  :tag "Icon")
 110                        (string  :tag "Tooltip"))))
 111
 112 (defvar ess-icon-directory
 113   (expand-file-name (concat ess-etc-directory "/icons"))
 114   "*Location for ESS icons.
 115 This variable should be set automatically by the ESS install process.
 116 Icons should be found in ESS/etc/icons/ directory.
 117 If `ess-icon-directory' is invalid, please report a bug.")
 118
 119 (unless (file-directory-p ess-icon-directory)
 120     (ess-write-to-dribble-buffer
 121         "`ess-icon-directory' does not exist; using `ess-etc-directory'.\n")
 122     (setq ess-icon-directory ess-etc-directory))
 123
 124 (defvar ess-toolbar nil
 125   "Toolbar items to be added to ESS editing buffers.")
 126
 127 (defun ess-make-toolbar ()
 128   "Make the ESS toolbar."
 129   (if (featurep 'xemacs)
 130       (ess-make-toolbar-xemacs)
 131     (ess-make-toolbar-emacs)))
 132
 133 (defun ess-make-toolbar-emacs ()
 134   "Make the ESS toolbar under Emacs."
 135   (setq ess-toolbar
 136         (if (or ess-toolbar-own-icons (null tool-bar-map))
 137             (make-sparse-keymap)
 138           (copy-keymap tool-bar-map)))
 139   (let ((tool-bar-map ess-toolbar)
 140         (load-path (list ess-icon-directory)))
 141
 142     ;; icons are found by examining load-path; hence by temporarily setting
 143     ;; load-path to our icons directory, they will be found.
 144     (mapc 'ess-add-icon-emacs ess-toolbar-items)))
 145
 146 (defun ess-add-icon-emacs (x)
 147   "Add an ESS item to the Emacs toolbar."
 148   ;; By using tool-bar-add-item-from-menu instead of tool-bar-add-item
 149   ;; we get the tooltips "for free" from ess-mode-map.
 150   (tool-bar-add-item-from-menu (car x) (cadr x) ess-mode-map))
 151
 152 (defun ess-add-icon-xemacs (x)
 153   "Return a 4-vector containing the spec for an ESS toolbar entry in XEmacs."
 154   (vector
 155    (toolbar-make-button-list
 156     (expand-file-name (concat (cadr x) ".xpm") ess-icon-directory))
 157    (car x)                              ;function
 158    t
 159    (caddr x)                            ;doc string
 160    ))
 161
 162 (defvar ess-toolbar-xemacs-general
 163   (list
 164    [toolbar-file-icon toolbar-open t "Open a file"]
 165    [toolbar-disk-icon toolbar-save t "Save buffer"]
 166    [toolbar-printer-icon generic-print-buffer t "Print buffer"]
 167    [toolbar-cut-icon toolbar-cut t "Kill region"]
 168    [toolbar-copy-icon toolbar-copy t "Copy region"]
 169    [toolbar-paste-icon toolbar-paste t "Paste from clipboard"]
 170    [toolbar-undo-icon toolbar-undo t "Undo edit"]
 171    [toolbar-replace-icon toolbar-replace t "Search & Replace"]
 172    [:style 3d]
 173    )
 174   "General Xemacs icons to be added iff `ess-toolbar-own-icons' is non-nil.
 175 These toolbar items were taken from the list that John Fox's code provided.
 176 Each vector is of length four specifying: 1 - icon; 2 - function to call;
 177 3 - whether to activate; 4 - doc string.")
 178
 179 (defun ess-make-toolbar-xemacs ()
 180   "Set up the ESS toolbar for XEmacs."
 181   (setq ess-toolbar
 182         (append (if ess-toolbar-own-icons nil ess-toolbar-xemacs-general)
 183                 (mapcar 'ess-add-icon-xemacs ess-toolbar-items)))
 184   )
 185
 186 (defun ess-add-toolbar ()
 187   "Add the ESS toolbar to a particular mode.
 188 The toolbar is added iff `ess-toolbar-global' is nil, else the toolbar
 189 is added globally when ess-toolbar.el is loaded."
 190   (if (and ess-toolbar (not ess-toolbar-global))
 191       (if (featurep 'xemacs)
 192           (set-specifier  default-toolbar ess-toolbar (current-buffer))
 193         ;; Support for Emacs
 194         (set (make-local-variable 'tool-bar-map) ess-toolbar))))
 195
 196 ;; Make the toolbars.  Each toolbar is hopefully made only when this file
 197 ;; is loaded; we don't need it to be remade every time.
 198 (if ess-use-toolbar
 199     (progn
 200       (ess-make-toolbar)
 201       ;; After making the toolbar, if ESS toolbar is needed globally,
 202       ;; add it here.
 203       (if ess-toolbar-global
 204           (if (featurep 'xemacs)
 205               ;; Xemacs
 206               (progn
 207                 (set-specifier  default-toolbar ess-toolbar)
 208                 (ess-write-to-dribble-buffer "Creating global XEmacs toolbar"))
 209             ;; Emacs
 210             (setq tool-bar-map ess-toolbar)
 211             (ess-write-to-dribble-buffer "Creating global Emacs toolbar"))
 212             )
 213
 214       ;; Check for toolbar support - needed iff ess-use-toolbar is non-nil.
 215       (or
 216        ;; XEmacs test for image support, adapted from vm-version.el:
 217        (and (featurep 'xemacs) (memq (device-type) '(x gtk mswindows)))
 218        ;;
 219        ;; Emacs support for images:
 220        (and (fboundp 'display-images-p) (display-images-p))
 221        ;; if above tests failed, give a warning.
 222        (progn
 223          (message "Toolbar support for ESS not available in this emacs.")
 224          ;; Not sure if we want to delay startup of ESS.
 225          ;;(sit-for 2)
 226          ))
 227       ))
 228
 229 (provide 'ess-toolbar)