]> code.delx.au - gnu-emacs-elpa/blobdiff - packages/hydra/README.md
Merge commit '68bcaa8d8df5518217a3833fd1bb400c8225fe02' from hydra
[gnu-emacs-elpa] / packages / hydra / README.md
index 06869656ba44217408aa0a3c72fd7c351d724e39..72720989039a3b3698f37a1e532df9f55be5cd0d 100644 (file)
@@ -171,3 +171,69 @@ Since version `0.6.0`, for any Hydra:
 - `digit-argment` can be called with <kbd>0</kbd>-<kbd>9</kbd>.
 - `negative-argument` can be called with <kbd>-</kbd>
 - `universal-argument` can be called with <kbd>C-u</kbd>
+
+## Hydras can have `:pre` and `:post` statements
+
+Since version `0.7.0`, you can specify code that will be called before each head, and
+after the body. For example:
+
+```cl
+(global-set-key
+ (kbd "C-z")
+ (defhydra hydra-vi
+     (:pre
+      (set-cursor-color "#40e0d0")
+      :post
+      (progn
+        (set-cursor-color "#ffffff")
+        (message
+         "Thank you, come again.")))
+   "vi"
+   ("l" forward-char)
+   ("h" backward-char)
+   ("j" next-line)
+   ("k" previous-line)
+   ("q" nil "quit")))
+```
+
+## New Hydra color: amaranth
+
+Since version `0.8.0`, a new color - amaranth, in addition to the previous red and blue, is
+available for the Hydra body.
+
+According to [Wikipedia](http://en.wikipedia.org/wiki/Amaranth):
+
+> The word amaranth comes from the Greek word amaranton, meaning "unwilting" (from the
+> verb marainesthai, meaning "wilt").  The word was applied to amaranth because it did not
+> soon fade and so symbolized immortality.
+
+Hydras with amaranth body are impossible to quit with any binding *except* a blue head.
+A check for at least one blue head exists in `defhydra`, so that you don't get stuck by accident.
+
+Here's an example of an amaranth Hydra:
+
+```cl
+(global-set-key
+ (kbd "C-z")
+ (defhydra hydra-vi
+     (:pre
+      (set-cursor-color "#40e0d0")
+      :post
+      (set-cursor-color "#ffffff")
+      :color amaranth)
+   "vi"
+   ("l" forward-char)
+   ("h" backward-char)
+   ("j" next-line)
+   ("k" previous-line)
+   ("q" nil "quit")))
+```
+
+The only way to exit it, is to press <kbd>q</kbd>. No other methods will work.  You can
+use an amaranth Hydra instead of a red one, if for you the cost of being able to exit only
+though certain bindings is less than the cost of accidentally exiting a red Hydra by
+pressing the wrong prefix.
+
+Note that it does not make sense to define a singe amaranth head, so this color can only
+be assigned to the body. An amaranth body will always have some amaranth heads and some
+blue heads (otherwise, it's impossible to exit), no reds.