Homepage: https://github.com/cute-jumper/ace-jump-helm-line
Author: Junpeng Qiu
Updated:
Ace-jump to a candidate in helm window
____________________
ACE-JUMP-HELM-LINE
Junpeng Qiu
____________________
Table of Contents
_________________
1 Setup
2 Usage
.. 2.1 Keys & UI
.. 2.2 Different Actions: move-only, persistent or select
.. 2.3 Automatic Idle Execution
.. 2.4 Line Hints Preview
3 Example settings
4 Demos(only showing the basic feature)
5 Similar Package
6 Acknowledgment
[[file:http://melpa.org/packages/ace-jump-helm-line-badge.svg]]
[[file:http://stable.melpa.org/packages/ace-jump-helm-line-badge.svg]]
*Ace-jump to a candidate in helm window.*
This package makes use of the `avy.el'.
[[file:http://melpa.org/packages/ace-jump-helm-line-badge.svg]]
http://melpa.org/#/ace-jump-helm-line
[[file:http://stable.melpa.org/packages/ace-jump-helm-line-badge.svg]]
http://stable.melpa.org/#/ace-jump-helm-line
1 Setup
=======
,----
| (add-to-list 'load-path "/path/to/ace-jump-helm-line.el")
| (require 'ace-jump-helm-line)
`----
You can use the following code to bind `ace-jump-helm-line' to a
key(say, C-'):
,----
| (eval-after-load "helm"
| '(define-key helm-map (kbd "C-'") 'ace-jump-helm-line))
`----
2 Usage
=======
When in a helm session, for example, after you call `helm-M-x', you
can use your key binding(for example, C-') to invoke
`ace-jump-helm-line'. See the following demos.
*Note*: Since *2016-02-19*, you can configure `ace-jump-helm-line' in
a similar way as `avy'. The old-fashioned variable
`ace-jump-helm-line-use-avy-style' is discarded now. There is no
effect by setting this variable(I dropped this variable because `avy'
has become much more configurable since I first developed this
package).
2.1 Keys & UI
~~~~~~~~~~~~~
You can customize following variables:
1. `ace-jump-helm-line-keys': the keys to be used for
`ace-jump-helm-line'. If you don't set this variable, `avy-keys'
will be used.
2. `ace-jump-helm-line-style': You can set the styles to be used for
`ace-jump-helm-line'. The values can be `pre', `at', `at-full',
`post', and `de-bruijn', the same as `avy-style'. If you don't set
this variable, `avy-style' will be used.
3. `ace-jump-helm-line-background': Whether you want to use a
background or not. The default value is `nil'.
For old version users: if you want to achieve the same effect of
`(setq ace-jump-helm-line-use-avy-style nil)', use the following
code:
,----
| (setq ace-jump-helm-line-keys (number-sequence ?a ?z))
| (setq ace-jump-helm-line-style 'at)
| (setq ace-jump-helm-line-background t)
`----
2.2 Different Actions: move-only, persistent or select
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can now specify the action that will be executed after the cursor
has been moved to the candidate. This is controlled by the value of
`ace-jump-helm-line-default-action'. Three different kinds of values
are available:
1. `nil' or `move-only': This is the default one. Just move the cursor
to the candidate and do nothing.
2. `persistent': After the cursor has been moved to the candidate,
execute the persistent action on that candidate.
3. `select': After the cursor has been moved to the candidate, select
the candidate and exit the helm session.
Thanks to `avy' 0.4.0, we can now switch the action after we see the
avy prompt. Three different keys can be used to switch the action:
1. `ace-jump-helm-line-move-only-key'
2. `ace-jump-helm-line-persistent-key'
3. `ace-jump-helm-line-select-key'
For example, if we have following settings:
,----
| (setq ace-jump-helm-line-default-action 'select)
| (setq ace-jump-helm-line-select-key ?e) ;; this line is not neeeded
| ;; Set the move-only and persistent keys
| (setq ace-jump-helm-line-move-only-key ?o)
| (setq ace-jump-helm-line-persistent-key ?p)
`----
Say after we invoke `ace-jump-helm-line', we can use f to jump to a
candidate. Since the default action is `select', the candidate will be
automatically selected and the helm session will be ended after the
cursor has been moved to it. But suddenly I change my mind and only
want to move to it. Instead of pressing f, I can press of where o is
defined by the `ace-jump-helm-line-move-only-key' and is used to
switch the action to `move-only'. Similarly, if I press pf, then the
persistent action on the candidate will be executed.
Note in this example, setting `ace-jump-helm-line-select-key' has no
effect because the default action is `select'. It makes no senses that
we need to have an extra key to switch to the `select' action. So if
your default action is `nil' or `move-only',
`ace-jump-helm-line-move-only-key' is not needed and
`ace-jump-helm-line-persistent-key' is not needed if your default
action is `persistent'. However, you're *safe* to set these variables
regardless of your default action since the variable corresponding to
your default action will just be ignored.
If you wonder why this feature is useful, here is an example: if you use
`helm-find-files' and set the default action to be `select', you can now
use `ace-jump-helm-line-persistent-key' to complete the directory name
instead of opening the directory in dired. This means you can use
`ace-jump-helm-line' until you finally find the target file.
For compatibility issues, there are also two identical pre-defined
commands: `ace-jump-helm-line-and-select' and
`ace-jump-helm-line-execute-action'. Their default action is to select
the candidate and exit the helm session. Now you can achieve the same
effect using `ace-jump-helm-line' by the following setting:
,----
| (setq ace-jump-helm-line-default-action 'select)
`----
2.3 Automatic Idle Execution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`ace-jump-helm-line' can be automatically executed if there is no
input after the user launches a helm command. The delay can be
specified by setting the variable `ace-jump-helm-line-idle-delay' in
seconds. The default value is 1.
Use the following code to enable this feature for a helm command, say,
`helm-mini':
,----
| (ace-jump-helm-line-idle-exec-add 'helm-mini)
`----
After adding this setting, `ace-jump-helm-line' will be automatically
triggerred if there is no input for `ace-jump-helm-line-idle-delay'
seconds after `helm-mini' is called.
To remove it, use:
,----
| (ace-jump-helm-line-idle-exec-remove 'helm-mini)
`----
Note this feature is *experimental*. Please file an issue if you find
any problems. As I couldn't find good documentation about adding hooks
to a helm command, the implementation is a simple yet dirty hack. And
don't try to set the value of `ace-jump-helm-line-idle-delay' to be
`nil'. It doesn't work.
2.4 Line Hints Preview
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can preview the line hints without invoking `ace-jump-helm-line' by
enabling `ace-jump-helm-line-autoshow-mode'. This is similar to `linum-mode'.
With `avy-style' set to `at-full', the result is shown below:
https://github.com/cute-jumper/ace-jump-helm-line/screencasts/autoshow.png
Or if you may prefer to show the hints using `linum-mode', you can set
`ace-jump-helm-line-autoshow-use-linum' to `t':
,----
| (setq ace-jump-helm-line-autoshow-use-linum t)
`----
The result:
https://github.com/cute-jumper/ace-jump-helm-line/screencasts/autoshow-linum.png
3 Example settings
==================
,----
| (eval-after-load "helm"
| '(define-key helm-map (kbd "C-'") 'ace-jump-helm-line))
| ;; or if using key-chord-mode
| ;; (eval-after-load "helm"
| ;; '(key-chord-define helm-map "jj" 'ace-jump-helm-line))
| (setq ace-jump-helm-line-style 'pre)
| (setq ace-jump-helm-line-background t)
| (setq ace-jump-helm-line-default-action 'select)
| (setq ace-jump-helm-line-select-key ?e) ;; this line is not neeeded
| ;; Set the move-only and persistent keys
| (setq ace-jump-helm-line-move-only-key ?o)
| (setq ace-jump-helm-line-persistent-key ?p)
| ;; enable idle execution for `helm-mini'
| (ace-jump-helm-line-idle-exec-add 'helm-mini)
| ;; enable hints preview
| (ace-jump-helm-line-autoshow-mode +1)
| ;; use `linum-mode' to show
| (setq ace-jump-helm-line-autoshow-mode-use-linum t)
`----
4 Demos(only showing the basic feature)
=======================================
The following demo are recorded in pre-0.4 version. It's a little
out-dated.
Use `avy' style to jump to a helm candidate:
[./screencasts/avy-jump-style.gif]
Or use a different style similar to `ace-jump-mode' (by setting the
values of `ace-jump-helm-line-keys', `ace-jump-helm-line-style' and
`ace-jump-helm-line-background'):
[./screencasts/ace-jump-mode-style.gif]
The new features after v0.4 are not recorded yet.:-(
5 Similar Package
=================
[This issue of Helm] has been solved by adding a new minor mode
`helm-linum-relative-mode' to `linum-relative'. You can take a look if
you don't like `avy' and want to find an alternative. As a heavy user
of `avy', I don't find the way that `helm-linum-relative-mode'
provides very appealing. Thanks to `avy', this package provides more
customizations and more consistent user experience for `avy' users.
[This issue of Helm] https://github.com/emacs-helm/helm/issues/1257
6 Acknowledgment
================
- Thank [Oleh Krehel] for the awesome [avy] package.
- Thank @hick for the original idea.
[Oleh Krehel] https://github.com/abo-abo/
[avy] https://github.com/abo-abo/avy