____________________ 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