]> code.delx.au - gnu-emacs-elpa/blob - packages/spinner/spinner.el
Merge commit '5a2e0fd355fea83e3c172402b965a1aa826fcc0c' from swiper
[gnu-emacs-elpa] / packages / spinner / spinner.el
1 ;;; spinner.el --- Add spinners and progress-bars to the mode-line for ongoing operations -*- lexical-binding: t; -*-
2
3 ;; Copyright (C) 2015 Free Software Foundation, Inc.
4
5 ;; Author: Artur Malabarba <emacs@endlessparentheses.com>
6 ;; Version: 1.3
7 ;; URL: https://github.com/Malabarba/spinner.el
8 ;; Keywords: processes mode-line
9
10 ;; This program is free software; you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
14
15 ;; This program is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
19
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with this program. If not, see <http://www.gnu.org/licenses/>.
22
23 ;;; Commentary:
24 ;;
25 ;; 1 Usage
26 ;; ═══════
27 ;;
28 ;; First of all, don’t forget to add `(spinner "VERSION")' to your
29 ;; package’s dependencies.
30 ;;
31 ;;
32 ;; 1.1 Major-modes
33 ;; ───────────────
34 ;;
35 ;; 1. Just call `(spinner-start)' and a spinner will be added to the
36 ;; mode-line.
37 ;; 2. Call `(spinner-stop)' on the same buffer when you want to remove
38 ;; it.
39 ;;
40 ;; The default spinner is a line drawing that rotates. You can pass an
41 ;; argument to `spinner-start' to specify which spinner you want. All
42 ;; possibilities are listed in the `spinner-types' variable, but here are
43 ;; a few examples for you to try:
44 ;;
45 ;; • `(spinner-start 'vertical-breathing 10)'
46 ;; • `(spinner-start 'minibox)'
47 ;; • `(spinner-start 'moon)'
48 ;; • `(spinner-start 'triangle)'
49 ;;
50 ;; You can also define your own as a vector of strings (see the examples
51 ;; in `spinner-types').
52 ;;
53 ;;
54 ;; 1.2 Minor-modes
55 ;; ───────────────
56 ;;
57 ;; Minor-modes can create a spinner with `make-spinner' and then add it
58 ;; to their mode-line lighter. They can then start the spinner by setting
59 ;; a variable and calling `spinner-start-timer'. Finally, they can stop
60 ;; the spinner (and the timer) by just setting the same variable to nil.
61 ;;
62 ;; Here’s an example for a minor-mode named `foo'. Assuming that
63 ;; `foo--lighter' is used as the mode-line lighter, the following code
64 ;; will add an *inactive* global spinner to the mode-line.
65 ;; ┌────
66 ;; │ (defvar foo--spinner (make-spinner 'rotating-line))
67 ;; │ (defconst foo--lighter
68 ;; │ '(" foo" (:eval (spinner-print foo--spinner))))
69 ;; └────
70 ;;
71 ;; 1. To activate the spinner, just call `(spinner-start foo--spinner)'.
72 ;; It will show up on the mode-line and start animating.
73 ;; 2. To get rid of it, call `(spinner-stop foo--spinner)'. It will then
74 ;; disappear again.
75 ;;
76 ;; Some minor-modes will need spinners to be buffer-local. To achieve
77 ;; that, just make the `foo--spinner' variable buffer-local and use the
78 ;; third argument of the `make-spinner' function. The snippet below is an
79 ;; example.
80 ;;
81 ;; ┌────
82 ;; │ (defvar-local foo--spinner nil)
83 ;; │ (defconst foo--lighter
84 ;; │ '(" foo" (:eval (spinner-print foo--spinner))))
85 ;; │ (defun foo--start-spinner ()
86 ;; │ "Create and start a spinner on this buffer."
87 ;; │ (unless foo--spinner
88 ;; │ (setq foo--spinner (make-spinner 'moon t)))
89 ;; │ (spinner-start foo--spinner))
90 ;; └────
91 ;;
92 ;; 1. To activate the spinner, just call `(foo--start-spinner)'.
93 ;; 2. To get rid of it, call `(spinner-stop foo--spinner)'.
94 ;;
95 ;; This will use the `moon' spinner, but you can use any of the names
96 ;; defined in the `spinner-types' variable or even define your own.
97
98 \f
99 ;;; Code:
100 (eval-when-compile
101 (require 'cl))
102
103 (defconst spinner-types
104 '((3-line-clock . ["┤" "┘" "┴" "└" "├" "┌" "┬" "┐"])
105 (2-line-clock . ["┘" "└" "┌" "┐"])
106 (flipping-line . ["_" "\\" "|" "/"])
107 (rotating-line . ["-" "\\" "|" "/"])
108 (progress-bar . ["[ ]" "[= ]" "[== ]" "[=== ]" "[====]" "[ ===]" "[ ==]" "[ =]"])
109 (progress-bar-filled . ["| |" "|█ |" "|██ |" "|███ |" "|████|" "| ███|" "| ██|" "| █|"])
110 (vertical-breathing . ["▁" "▂" "▃" "▄" "▅" "▆" "▇" "█" "▇" "▆" "▅" "▄" "▃" "▂" "▁" " "])
111 (vertical-rising . ["▁" "▄" "█" "▀" "▔"])
112 (horizontal-breathing . [" " "▏" "▎" "▍" "▌" "▋" "▊" "▉" "▉" "▊" "▋" "▌" "▍" "▎" "▏"])
113 (horizontal-breathing-long
114 . [" " "▎ " "▌ " "▊ " "█ " "█▎" "█▌" "█▊" "██" "█▊" "█▌" "█▎" "█ " "▊ " "▋ " "▌ " "▍ " "▎ " "▏ "])
115 (horizontal-moving . [" " "▌ " "█ " "▐▌" " █" " ▐"])
116 (minibox . ["▖" "▘" "▝" "▗"])
117 (triangle . ["◢" "◣" "◤" "◥"])
118 (box-in-box . ["◰" "◳" "◲" "◱"])
119 (box-in-circle . ["◴" "◷" "◶" "◵"])
120 (half-circle . ["◐" "◓" "◑" "◒"])
121 (moon . ["🌑" "🌘" "🌖" "🌕" "🌔" "🌒"]))
122 "Predefined alist of spinners.
123 Each car is a symbol identifying the spinner, and each cdr is a
124 vector, the spinner itself.")
125
126 (defvar spinner-current nil
127 "Spinner curently being displayed on the `mode-line-process'.")
128 (make-variable-buffer-local 'spinner-current)
129
130 (defconst spinner--mode-line-construct
131 '(:eval (spinner-print spinner-current))
132 "Construct used to display a spinner in `mode-line-process'.")
133 (put 'spinner--mode-line-construct 'risky-local-variable t)
134
135 (defvar spinner-frames-per-second 10
136 "Default speed at which spinners spin, in frames per second.
137 Each spinner can override this value.")
138
139 \f
140 ;;; The spinner object.
141 (defun spinner--type-to-frames (type)
142 "Return a vector of frames corresponding to TYPE.
143 The list of possible built-in spinner types is given by the
144 `spinner-types' variable, but you can also use your own (see
145 below).
146
147 If TYPE is nil, the frames of this spinner are given by the first
148 element of `spinner-types'.
149 If TYPE is a symbol, it specifies an element of `spinner-types'.
150 If TYPE is 'random, use a random element of `spinner-types'.
151 If TYPE is a list, it should be a list of symbols, and a random
152 one is chosen as the spinner type.
153 If TYPE is a vector, it should be a vector of strings and these
154 are used as the spinner's frames. This allows you to make your
155 own spinner animations."
156 (cond
157 ((vectorp type) type)
158 ((not type) (cdr (car spinner-types)))
159 ((eq type 'random)
160 (cdr (elt spinner-types
161 (random (length spinner-types)))))
162 ((listp type)
163 (cdr (assq (elt type (random (length type)))
164 spinner-types)))
165 ((symbolp type) (cdr (assq type spinner-types)))
166 (t (error "Unknown spinner type: %s" type))))
167
168 ;;;###autoload
169 (defstruct (spinner
170 (:copier nil)
171 (:conc-name spinner--)
172 (:constructor make-spinner (&optional type buffer-local fps)
173 "Create a spinner of the given TYPE.
174 The possible TYPEs are described in `spinner--type-to-frames'.
175
176 FPS, if given, is the number of desired frames per second.
177 Default is `spinner-frames-per-second'.
178
179 If BUFFER-LOCAL is non-nil, the spinner will be automatically
180 deactivated if the buffer is killed. If BUFFER-LOCAL is a
181 buffer, use that instead of current buffer.
182
183 When started, in order to function properly, the spinner runs a
184 timer which periodically calls `force-mode-line-update' in the
185 curent buffer. If BUFFER-LOCAL was set at creation time, then
186 `force-mode-line-update' is called in that buffer instead. When
187 the spinner is stopped, the timer is deactivated."))
188 (frames (spinner--type-to-frames type))
189 (counter 0)
190 (fps spinner-frames-per-second)
191 (timer (timer-create) :read-only)
192 (active-p nil)
193 (buffer (when buffer-local
194 (if (bufferp buffer-local)
195 buffer-local
196 (current-buffer)))))
197
198 (defun spinner-print (spinner)
199 "Return a string of the current frame of SPINNER.
200 If SPINNER is nil, just return nil.
201 Designed to be used in the mode-line with:
202 (:eval (spinner-print some-spinner))"
203 (when (and spinner (spinner--active-p spinner))
204 (elt (spinner--frames spinner)
205 (spinner--counter spinner))))
206
207 (defun spinner--timer-function (spinner)
208 "Function called to update SPINNER.
209 If SPINNER is no longer active, or if its buffer has been killed,
210 stop the SPINNER's timer."
211 (let ((buffer (spinner--buffer spinner)))
212 (if (or (not (spinner--active-p spinner))
213 (and buffer (not (buffer-live-p buffer))))
214 (spinner-stop spinner)
215 ;; Increment
216 (callf (lambda (x) (% (1+ x) (length (spinner--frames spinner))))
217 (spinner--counter spinner))
218 ;; Update mode-line.
219 (if (buffer-live-p buffer)
220 (with-current-buffer buffer
221 (force-mode-line-update))
222 (force-mode-line-update)))))
223
224 (defun spinner--start-timer (spinner)
225 "Start a SPINNER's timer at FPS frames per second."
226 (let ((old-timer (spinner--timer spinner)))
227 (when (timerp old-timer)
228 (cancel-timer old-timer))
229
230 (setf (spinner--active-p spinner) t)
231 ;; Create timer.
232 (let* ((repeat (/ 1.0 (or (spinner--fps spinner)
233 spinner-frames-per-second)))
234 (time (timer-next-integral-multiple-of-time (current-time) repeat))
235 ;; Create the timer as a lex variable so it can cancel itself.
236 (timer (spinner--timer spinner)))
237 (timer-set-time timer time repeat)
238 (timer-set-function timer #'spinner--timer-function (list spinner))
239 (timer-activate timer)
240 ;; Return a stopping function.
241 (lambda () (spinner-stop spinner)))))
242
243 \f
244 ;;; The main functions
245 ;;;###autoload
246 (defun spinner-start (&optional type-or-object fps)
247 "Start a mode-line spinner of given TYPE-OR-OBJECT.
248 If TYPE-OR-OBJECT is an object created with `make-spinner',
249 simply activate it. This method is designed for minor modes, so
250 they can use the spinner as part of their lighter by doing:
251 '(:eval (spinner-print THE-SPINNER))
252 To stop this spinner, call `spinner-stop' on it.
253
254 If TYPE-OR-OBJECT is anything else, a buffer-local spinner is
255 created with this type, and it is displayed in the
256 `mode-line-process' of the buffer it was created it. Both
257 TYPE-OR-OBJECT and FPS are passed to `make-spinner' (which see).
258 To stop this spinner, call `spinner-stop' in the same buffer.
259
260 Either way, the return value is a function which can be called
261 anywhere to stop this spinner. You can also call `spinner-stop'
262 in the same buffer where the spinner was created.
263
264 FPS, if given, is the number of desired frames per second.
265 Default is `spinner-frames-per-second'."
266 (unless (spinner-p type-or-object)
267 ;; Choose type.
268 (if (spinner-p spinner-current)
269 (setf (spinner--frames spinner-current)
270 (spinner--type-to-frames type-or-object))
271 (setq spinner-current (make-spinner type-or-object (current-buffer) fps)))
272 (setq type-or-object spinner-current)
273 ;; Maybe add to mode-line.
274 (unless (memq 'spinner--mode-line-construct mode-line-process)
275 (setq mode-line-process
276 (list (or mode-line-process "")
277 'spinner--mode-line-construct))))
278
279 ;; Create timer.
280 (when fps (setf (spinner--fps type-or-object) fps))
281 (spinner--start-timer type-or-object))
282
283 (defun spinner-start-print (spinner)
284 "Like `spinner-print', but also start SPINNER if it's not active."
285 (unless (spinner--active-p spinner)
286 (spinner-start spinner))
287 (spinner-print spinner))
288
289 (defun spinner-stop (&optional spinner)
290 "Stop the current buffer's spinner."
291 (let* ((spinner (or spinner spinner-current))
292 (timer (spinner--timer spinner)))
293 (when (timerp timer)
294 (cancel-timer timer))
295 (setf (spinner--active-p spinner) nil)))
296
297 (provide 'spinner)
298
299 ;;; spinner.el ends here