config

Personal configuration.
git clone git://code.dwrz.net/config
Log | Files | Refs

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.