1 ;;; ess-toolbar.el --- Support for a toolbar in ESS.
3 ;; Copyright (C) 1997--2004 A.J. Rossini, Rich M. Heiberger, Martin
4 ;; Maechler, Kurt Hornik, Rodney Sparapani, and Stephen Eglen.
6 ;; Original Author: Stephen Eglen
7 ;; Created: 06 May 2004
8 ;; Maintainers: ESS-core <ESS-core@stat.math.ethz.ch>
10 ;; This file is part of ESS
12 ;; GPL --> see beginning of ./ess-site.el
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!
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
22 ;;; To use this code, place the following in .emacs after you have
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.
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.
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.
45 ;; Also, I think the CVS GNU Emacs now has tool-bar support for the
50 (defgroup ess-toolbar nil
51 "ESS: toolbar support."
53 :link
'(emacs-commentary-link :tag
"Commentary" "ess-toolbar.el")
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."
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."
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."
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.
95 General toolbar items are also added to the ESS toolbar
96 iff `ess-toolbar-own-icons' is nil.
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."
104 :set
(lambda (symbol value
)
105 (set-default symbol value
)
106 (if (fboundp 'ess-make-toolbar
)
108 :type
'(repeat (list (function :tag
"Function to run")
110 (string :tag
"Tooltip"))))
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.")
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
))
124 (defvar ess-toolbar nil
125 "Toolbar items to be added to ESS editing buffers.")
127 (defun ess-make-toolbar ()
128 "Make the ESS toolbar."
129 (if (featurep 'xemacs
)
130 (ess-make-toolbar-xemacs)
131 (ess-make-toolbar-emacs)))
133 (defun ess-make-toolbar-emacs ()
134 "Make the ESS toolbar under Emacs."
136 (if (or ess-toolbar-own-icons
(null tool-bar-map
))
138 (copy-keymap tool-bar-map
)))
139 (let ((tool-bar-map ess-toolbar
)
140 (load-path (list ess-icon-directory
)))
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
)))
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
))
152 (defun ess-add-icon-xemacs (x)
153 "Return a 4-vector containing the spec for an ESS toolbar entry in XEmacs."
155 (toolbar-make-button-list
156 (expand-file-name (concat (cadr x
) ".xpm") ess-icon-directory
))
159 (caddr x
) ;doc string
162 (defvar ess-toolbar-xemacs-general
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"]
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.")
179 (defun ess-make-toolbar-xemacs ()
180 "Set up the ESS toolbar for XEmacs."
182 (append (if ess-toolbar-own-icons nil ess-toolbar-xemacs-general
)
183 (mapcar 'ess-add-icon-xemacs ess-toolbar-items
)))
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))
194 (set (make-local-variable 'tool-bar-map
) ess-toolbar
))))
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.
201 ;; After making the toolbar, if ESS toolbar is needed globally,
203 (if ess-toolbar-global
204 (if (featurep 'xemacs
)
207 (set-specifier default-toolbar ess-toolbar
)
208 (ess-write-to-dribble-buffer "Creating global XEmacs toolbar"))
210 (setq tool-bar-map ess-toolbar
)
211 (ess-write-to-dribble-buffer "Creating global Emacs toolbar"))
214 ;; Check for toolbar support - needed iff ess-use-toolbar is non-nil.
216 ;; XEmacs test for image support, adapted from vm-version.el:
217 (and (featurep 'xemacs
) (memq (device-type) '(x gtk mswindows
)))
219 ;; Emacs support for images:
220 (and (fboundp 'display-images-p
) (display-images-p))
221 ;; if above tests failed, give a warning.
223 (message "Toolbar support for ESS not available in this emacs.")
224 ;; Not sure if we want to delay startup of ESS.
229 (provide 'ess-toolbar
)