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