README.org (2831B)
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 starting a spinner, it still won’t be displayed for this many seconds.