code.delx.au - gnu-emacs-elpa/blob - packages/spinner/README.org

   1 #+TITLE: spinner.el
   2
   3 Add spinners and progress-bars to the mode-line for ongoing operations.
   4
   5 [[file:some-spinners.gif]]
   6
   7 [[file:all-spinners.gif]]
   8
   9 * Usage
  10
  11 First of all, don’t forget to add ~(spinner "VERSION")~ to your package’s dependencies.
  12
  13 ** Major-modes
  14 1. Just call ~(spinner-start)~ and a spinner will be added to the mode-line.
  15 2. Call ~(spinner-stop)~ on the same buffer when you want to remove it.
  16
  17 The default spinner is a line drawing that rotates. You can pass an
  18 argument to ~spinner-start~ to specify which spinner you want. All
  19 possibilities are listed in the ~spinner-types~ variable, but here are
  20 a few examples for you to try:
  21
  22 - ~(spinner-start 'vertical-breathing 10)~
  23 - ~(spinner-start 'minibox)~
  24 - ~(spinner-start 'moon)~
  25 - ~(spinner-start 'triangle)~
  26
  27 You can also define your own as a vector of strings (see the examples
  28 in ~spinner-types~).
  29
  30 ** Minor-modes
  31 Minor-modes can create a spinner with ~spinner-create~ and then add it
  32 to their mode-line lighter. They can then start the spinner by setting
  33 a variable and calling ~spinner-start-timer~. Finally, they can stop
  34 the spinner (and the timer) by just setting the same variable to nil.
  35
  36 Here’s an example for a minor-mode named ~foo~. Assuming that
  37 ~foo--lighter~ is used as the mode-line lighter, the following code
  38 will add an *inactive* global spinner to the mode-line.
  39 #+begin_src emacs-lisp
  40 (defvar foo--spinner (spinner-create 'rotating-line))
  41 (defconst foo--lighter
  42   '(" foo" (:eval (spinner-print foo--spinner))))
  43 #+end_src
  44
  45 1. To activate the spinner, just call ~(spinner-start foo--spinner)~.
  46    It will show up on the mode-line and start animating.
  47 2. To get rid of it, call ~(spinner-stop foo--spinner)~. It will then
  48    disappear again.
  49
  50 Some minor-modes will need spinners to be buffer-local. To achieve
  51 that, just make the ~foo--spinner~ variable buffer-local and use the
  52 third argument of the ~spinner-create~ function. The snippet below is an example.
  53
  54 #+begin_src emacs-lisp
  55 (defvar-local foo--spinner nil)
  56 (defconst foo--lighter
  57   '(" foo" (:eval (spinner-print foo--spinner))))
  58 (defun foo--start-spinner ()
  59   "Create and start a spinner on this buffer."
  60   (unless foo--spinner
  61     (setq foo--spinner (spinner-create 'moon t)))
  62   (spinner-start foo--spinner))
  63 #+end_src
  64
  65 1. To activate the spinner, just call ~(foo--start-spinner)~.
  66 2. To get rid of it, call ~(spinner-stop foo--spinner)~.
  67
  68 This will use the ~moon~ spinner, but you can use any of the names
  69 defined in the ~spinner-types~ variable or even define your own.
  70
  71 * Extra options
  72
  73 Both ~spinner-start~ and ~spinner-create~ take extra options to configure the spinner, these are:
  74
  75 - ~FPS~: The number of frames to display per second. Defaults to ~spinner-frames-per-second~.
  76 - ~DELAY~: After startin a spinner, it still won’t be displayed for this many seconds.