code.delx.au - gnu-emacs-elpa/blob - 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  Artur Malabarba
   4
   5 ;; Author: Artur Malabarba <bruce.connor.am@gmail.com>
   6 ;; Version: 1.0
   7 ;; Keywords: processes mode-line
   8
   9 ;; This program is free software; you can redistribute it and/or modify
  10 ;; it under the terms of the GNU General Public License as published by
  11 ;; the Free Software Foundation, either version 3 of the License, or
  12 ;; (at your option) any later version.
  13
  14 ;; This program is distributed in the hope that it will be useful,
  15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 ;; GNU General Public License for more details.
  18
  19 ;; You should have received a copy of the GNU General Public License
  20 ;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
  21
  22 ;;; Commentary:
  23 ;; 1 Usage
  24 ;; ═══════
  25 ;;
  26 ;; 1. Add `(spinner "1.0")' to your package’s dependencies.
  27 ;;
  28 ;; 2. Call `(spinner-start)' and a spinner will be added to the
  29 ;; mode-line.
  30 ;;
  31 ;; 3. Call `(spinner-stop)' on the same buffer when you want to remove
  32 ;; it.
  33 ;;
  34 ;;
  35 ;; 2 Behavior
  36 ;; ══════════
  37 ;;
  38 ;; The default spinner is a line drawing that rotates. You can pass an
  39 ;; argument to `spinner-start' to specify which spinner you want. All
  40 ;; possibilities are listed in the `spinner-types' variable, but here are
  41 ;; a few examples for you to try:
  42 ;;
  43 ;; • `(spinner-start 'vertical-breathing 10)'
  44 ;; • `(spinner-start 'minibox)'
  45 ;; • `(spinner-start 'moon)'
  46 ;; • `(spinner-start 'triangle)'
  47
  48 \f
  49 ;;; Code:
  50
  51 (defconst spinner-types
  52   '((3-line-clock . ["┤" "┘" "┴" "└" "├" "┌" "┬" "┐"])
  53     (2-line-clock . ["┘" "└" "┌" "┐"])
  54     (progress-bar . ["[    ]" "[=   ]" "[==  ]" "[=== ]" "[====]" "[ ===]" "[  ==]" "[   =]"])
  55     (progress-bar-filled . ["|    |" "|█   |" "|██  |" "|███ |" "|████|" "| ███|" "|  ██|" "|   █|"])
  56     (vertical-breathing . ["▁" "▂" "▃" "▄" "▅" "▆" "▇" "█" "▇" "▆" "▅" "▄" "▃" "▂" "▁" " "])
  57     (vertical-rising . ["▁" "▄" "█" "▀" "▔"])
  58     (horizontal-breathing . [" " "▏" "▎" "▍" "▌" "▋" "▊" "▉" "▉" "▊" "▋" "▌" "▍" "▎" "▏"])
  59     (horizontal-breathing-long
  60      . ["  " "▎ " "▌ " "▊ " "█ " "█▎" "█▌" "█▊" "██" "█▊" "█▌" "█▎" "█ " "▊ " "▋ " "▌ " "▍ " "▎ " "▏ "])
  61     (horizontal-moving . ["  " "▌ " "█ " "▐▌" " █" " ▐"])
  62     (minibox . ["▖" "▘" "▝" "▗"])
  63     (triangle . ["◢" "◣" "◤" "◥"])
  64     (box-in-box . ["◰" "◳" "◲" "◱"])
  65     (box-in-circle . ["◴" "◷" "◶" "◵"])
  66     (half-circle . ["◐" "◓" "◑" "◒"])
  67     (moon . ["🌑" "🌘" "🌖" "🌕" "🌔" "🌒"]))
  68   "Predefined alist of spinners.
  69 Each car is a symbol identifying the spinner, and each cdr is a
  70 vector, the spinner itself.")
  71
  72 (defvar spinner-current nil
  73   "Spinner curently being displayed on the mode-line.")
  74 (make-variable-buffer-local 'spinner-current)
  75
  76 (defvar spinner--counter 0
  77   "Current frame of the spinner.")
  78 (make-variable-buffer-local 'spinner--counter)
  79
  80 (defconst spinner--mode-line-construct
  81   '((spinner-current
  82      (" "
  83       (:eval (elt spinner-current
  84                   (% spinner--counter
  85                      (length spinner-current)))))
  86      (spinner--timer
  87       (:eval (spinner-stop)))))
  88   "Construct used to display the spinner.")
  89 (put 'spinner--mode-line-construct 'risky-local-variable t)
  90
  91 (defvar spinner--timer nil
  92   "Holds the timer being used on the current buffer.")
  93 (make-variable-buffer-local 'spinner--timer)
  94
  95 (defvar spinner-frames-per-second 5
  96   "Default speed at which spinners spin, in frames per second.
  97 Applications can override this value.")
  98
  99 \f
 100 ;;; The main function
 101 ;;;###autoload
 102 (defun spinner-start (&optional type fps)
 103   "Start a mode-line spinner of given TYPE.
 104 Spinners are buffer local. It is added to the mode-line in the
 105 buffer where `spinner-start' is called.
 106
 107 Return value is a function which can be called anywhere to stop
 108 this spinner.  You can also call `spinner-stop' in the same
 109 buffer where the spinner was created.
 110
 111 FPS, if given, is the number of desired frames per second.
 112 Default is `spinner-frames-per-second'.
 113
 114 If TYPE is nil, use the first element of `spinner-types'.
 115 If TYPE is `random', use a random element of `spinner-types'.
 116 If it is a symbol, it specifies an element of `spinner-types'.
 117 If it is a vector, it used as the spinner.
 118 If it is a list, it should be a list of symbols, and a random one
 119 is chosen as the spinner type."
 120   ;; Choose type.
 121   (setq spinner-current
 122         (cond
 123          ((vectorp type) type)
 124          ((not type) (cdr (car spinner-types)))
 125          ((eq type 'random)
 126           (cdr (elt spinner-types
 127                     (random (length spinner-types)))))
 128          ((listp type)
 129           (cdr (assq (elt type (random (length type)))
 130                      spinner-types)))
 131          ((symbolp type) (cdr (assq type spinner-types)))
 132          (t (error "Unknown spinner type: %s" type))))
 133   (setq spinner--counter 0)
 134
 135   ;; Maybe add to mode-line.
 136   (unless (memq 'spinner--mode-line-construct mode-line-format)
 137     (setq mode-line-format (copy-list mode-line-format))
 138     (let ((cell (memq 'mode-line-buffer-identification mode-line-format)))
 139       (if cell
 140           (setcdr cell (cons 'spinner--mode-line-construct (cdr cell)))
 141         (setcdr (last mode-line-format) '(spinner--mode-line-construct)))))
 142
 143   ;; Create timer.
 144   (when (timerp spinner--timer)
 145     (cancel-timer spinner--timer))
 146   (let ((buffer (current-buffer))
 147         ;; Create the timer as a lex variable so it can cancel itself.
 148         (timer (run-at-time t
 149                             (/ 1.0 (or fps spinner-frames-per-second))
 150                             #'ignore)))
 151     (timer-set-function
 152      timer (lambda ()
 153              (if (buffer-live-p buffer)
 154                  (with-current-buffer buffer
 155                    (setq spinner--counter (1+ spinner--counter))
 156                    (force-mode-line-update))
 157                (ignore-errors (cancel-timer timer)))))
 158     (setq spinner--timer timer)
 159     ;; Return a stopping function.
 160     (lambda () (when (buffer-live-p buffer)
 161             (with-current-buffer buffer
 162               (spinner-stop))))))
 163
 164 (defun spinner-stop ()
 165   "Stop the current buffer's spinner."
 166   (when (timerp spinner--timer)
 167     (cancel-timer spinner--timer))
 168   (setq spinner--timer nil
 169         spinner-current nil)
 170   (setq mode-line-format
 171         (remove 'spinner--mode-line-construct mode-line-format)))
 172
 173 (provide 'spinner)
 174
 175 ;;; spinner.el ends here