ace-jump-helm-line

Ace-jump to a candidate in helm window.

This package makes use of the avy.el.

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))

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).

Keys & UI

You can customize following variables:

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.
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.
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)

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:

nil or move-only: This is the default one. Just move the cursor to the candidate and do nothing.
persistent: After the cursor has been moved to the candidate, execute the persistent action on that candidate.
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:

ace-jump-helm-line-move-only-key
ace-jump-helm-line-persistent-key
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 needed
;; 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)

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.

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:

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:

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 needed
;; 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)

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:

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):

The new features after v0.4 are not recorded yet.:-(

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.

Acknowledgment

Thank Oleh Krehel for the awesome avy package.
Thank @hick for the original idea.

jepotter1-archive / ace-jump-helm-line