Permalink
Fetching contributors…
Cannot retrieve contributors at this time
246 lines (223 sloc) 13.4 KB

guide-key.el https://api.travis-ci.org/kai2nenobu/guide-key.png https://coveralls.io/repos/kai2nenobu/guide-key/badge.png?branch=master http://melpa.org/packages/guide-key-badge.svg http://stable.melpa.org/packages/guide-key-badge.svg

概要

guide-keyはキーバインドを自動的かつ動的に表示します。guide-keyはone-key.elの置 き換えを狙っています。

このライブラリの特徴は以下のようなものです。

  • guide-keyはあなたの指定したプレフィクスキーに続くキーバインドを自動的にポッ プアップします。さらにキーバインドを変更しても、guide-keyは動的にその変更に 追随することができます。
  • guide-keyはコマンドをハイライトすることができます。これによりコマンドを探し やすくなり、キーバインドを覚えることが簡単になります。
  • guide-keyは既存のコマンドやキーバインドを上書きしません。 describe-keydescribe-bindings を実行するのに悪影響がありません。

インストール

guide-keyはMELPAに追加されているので、guide-keyはpackage.elを使ってインストー ルすることができます。

img/guide-key-package-install.png

guide-keyはpopwin.elに依存しているので、popwin.elも同時にインストールされます。

package.elがない場合は、m2ym/popwin-elkai2nenobu/guide-keyから直接ダウンロー ドして、 load-path 上においてください。

基本的な使い方

guide-key/guide-key-sequence にお好きなプレイフィクスキーを追加してください。

(require 'guide-key)
(setq guide-key/guide-key-sequence '("C-x r" "C-x 4"))
(guide-key-mode 1)  ; Enable guide-key-mode

ここで設定したプレフィクスキーを押すと、それに続くキーバインドが少し遅れて(デ フォルトでは1秒後)自動的にポップアップされます。このスクリーンショットは C-x r を押した時のものです。

img/guide-key-example.png

あるいは guide-key/guide-key-sequencet に設定すれば、すべてのプレフィ クスキーに対してポップアップされます。

guide-keyは指定された正規表現に一致するコマンドをハイライトします。 C-x r に続くキーバインドは rectangle 系、 register 系、 bookmark 系に分かれま す。もし、 rectangle 系のみをハイライトしたい場合は、init.elに以下のように 設定します。

(setq guide-key/highlight-command-regexp "rectangle")

img/guide-key-example2.png

この機能によりコマンドが見つけやすくなり、キーバインドを覚えやすくなります。も しすべての系統のコマンドをハイライトしたい場合は、複数の正規表現とフェイスを 指定することができます。

(setq guide-key/highlight-command-regexp
      '("rectangle"
        ("register" . font-lock-type-face)
        ("bookmark" . "hot pink")))

img/guide-key-multiple-highlight.png

guide-key/highlight-command-regexp の要素がコンスセルの場合、carはハイライ トすべきコマンドの正規表現であり、cdrはハイライトに利用されるフェイスか色名に なります。

さらにプレフィクスコマンドは自動的にハイライトされます。

プレフィクスキーを押してからどのくらいの時間でキーバインドをポップアップさせる かは、Emacsの経験によって変わってくるでしょう。これは guide-key/idle-delay で変更することができます。

(setq guide-key/idle-delay 0.1)

プレフィクスキーを押してから、ここで設定した時間何も入力しなかった時だけキー バインドが表示されます。このためすばやく入力できるキーバインドの場合は、いま までと変わらず、ポップアップが表示されることなく入力することができます。

guide-keyは以下の環境で動くことを確認しています。

  • Emacs 24.4, Ubuntu 14.04 or Windows 8.1 64bit
  • Emacs 24.2, Ubuntu 12.04 or Windows 7 64bit
  • Emacs 23.3, Ubuntu 12.04 or Windows 7 64bit
  • Emacs 22.3, Windows 7 64bit
  • Emacs 24.3.1, OS X 10.9

popwinが動けばguide-keyも動作すると思います。また端末内で動いているEmacsでも guide-keyは問題なく動作します。

発展的な使い方

再帰的なチェック

たくさんのプレフィクスを guide-key/guide-key-sequence に追加するのは大変です。 guide-key/recursive-key-sequence-flag を使えばこの問題が解決します。 guide-key/recursive-key-sequence-flag がnon-nilの時、guide-keyは入力されたキー を再帰的にチェックします。つまり C-x 8 ^ が入力されている時、guide-keyは guide-key/guide-key-sequenceC-x 8C-x が含まれているかをチェック します。

例えば以下のように設定した場合

(setq guide-key/guide-key-sequence '("C-x"))
(setq guide-key/recursive-key-sequence-flag t)

C-x rC-x 8 など C-x に続くプレフィクスキーを押した際に、キーバイン ドがポップされます。

特定のモードに関する設定

特定のモードのみに追加の設定をすることができます。 guide-key/add-local-guide-key-sequenceguide-key/add-local-highlight-command-regexp とモードのフックを使ってくださ い。

以下のコードは org-mode の設定例です。

(defun guide-key/my-hook-function-for-org-mode ()
  (guide-key/add-local-guide-key-sequence "C-c")
  (guide-key/add-local-guide-key-sequence "C-c C-x")
  (guide-key/add-local-highlight-command-regexp "org-"))
(add-hook 'org-mode-hook 'guide-key/my-hook-function-for-org-mode)

org-mode バッファで C-c C-x p を押して org-set-property を実行すると、 以下のようになります。

img/guide-key-example-org-anime.gif

guide-key/guide-key-sequence については guide-key/add-local-guide-key-sequence を使わずに設定することもできます。例 えば以下のように設定してください。

(setq guide-key/guide-key-sequence
      '("C-x r" "C-x 4"
        (org-mode "C-c C-x")
        (outline-minor-mode "C-c @")))

メジャーモードが org-mode の場合 C-c C-x に続くキーバインドがポップアップ されます。 outline-minor-mode が有効な場合、 C-c @ に続くキーバインドがポッ プアップされます。

key-chord との連携

guide-keyはkey-chord.elと連携することができます。key chordに続くキーバインドを ポップアップしたい場合、 guide-key/key-chord-hack-on を実行する必要がありま す。その上で以下のように guide-key/guide-key-sequence にkey chordを追加して ください。

(key-chord-define global-map "@4" 'ctl-x-4-prefix)

(guide-key/key-chord-hack-on)
(setq guide-key/guide-key-sequence '("<key-chord> @ 4" "<key-chord> 4 @"))

guide-key/recursive-key-sequence-flag がnon-nilの場合、さらにシンプルになり ます。

(guide-key/key-chord-hack-on)
(setq guide-key/recursive-key-sequence-flag t)
(setq guide-key/guide-key-sequence '("<key-chord>"))

この設定の場合は、すべてのkey chordに続くキーバインドがポップアップされます。

guide-key/key-chord-hack-onthis-command-keysthis-command-keys-vector という原始的な関数をアドバイスしているため、 危 険 な可能性があります。

その他の関数や変数

guide-keyを操作するその他の関数や変数を以下に示します。

  • (guide-key-mode ARG): guide-key-mode はマイナーモードとして実装されてい ます。”M-x guide-key-mode“を実行するとguide-keyの有効無効を切り替えます。 guide-key-mode はグローバルマイナーモードであるため、バッファ個別に有効無 効を切り替えることはできません。
  • guide-key/popup-window-position: この変数はキーバインドがポップアップされ る位置を設定します。この変数の値は right, bottom, left, top のいず れかです。デフォルト値は right です。
  • guide-key/polling-time: この変数はポーリング時間を設定します。デフォルト 値は0.1秒です。
  • guide-key/idle-delay: この変数はプレフィクスキーを押してからキーバインドが ポップアップされるまでの時間を設定します。デフォルト値は1.0秒です。キー入力 の途中で止まらない限りは、いつもどおり入力することができます。0.0に設定すれ ば旧来の動作と同様になります。
  • guide-key/text-scale-amount: この変数はポップアップするキーバインドの文字 の大きさを設定します。デフォルト値は0です(文字の大きさはEmacsでのデフォル トの大きさになります)。テキストを大きくしたい場合は正の数、小さくしたい場 合は負の数に設定してください。

Known issues

いくつかの問題や欠点があります。

  • guide-keyはすべてのキーバインドを表示しようとするため、ポップアップするウィ ンドウは大きくなりがちです。ポップアップするウィンドウの大きさがフレームよ り大きくなると、正常にポップアップできなくなります。 C-x のようにキーバイ ンドが多いプレフィクスキーはポップアップさせないことをお勧めします。
  • ポップアップされたウィンドウがすぐに閉じてしまうことがあります(キーバイン ドがポップアップされないように見える)。popwinがコントロールしているウィン ドウを閉じた直後にその現象が起きがちです。そのような時は、 C-g を連打して からもう一度試してみてください。
  • one-key はコマンド名の代わりに短い説明文字列を表示することができます。こ れは手動でテンプレートを作っている利点です。対照的にguide-keyは動的にキーバ インドを抽出しているため、コマンド名以外を表示することはできません。

TODOs

  • [ ] confine a length of command name
  • [ ] confine the number of items to guide
  • [ ] a feature to exclude or include guide by command name
  • [X] enrichment of guide buffer
    • [ ] select more user-friendly colors
  • [X] automatically guide all following keys
  • [X] pop up guide buffer at top or bottom
  • [X] prefix argument processing
  • [X] define global minor mode

ChangeLog

Version 1.2.5

  • Enable setting guide-key/guide-key-sequence to t so that any key sequence will pop up bindings (#22)
  • Enable to guide key sequences with universal argument (#6)
  • Add a feature to specify a direct color name (#25)

Version 1.2.4

  • Change the format of tag name to suit MELPA Stable rule (ver1.x.y -> v1.x.y)
  • Add some tests and work with Travis CI and Coveralls
  • Fix a regression bug about a local highlight face (#16)
  • Add a feature to specify multiple highlight faces according to each regular expression (#14)

Version 1.2.3

  • Modify a link of one-key to more explanatory page
  • Allow key sequences with regexp special characters. (Thanks to @mrc)
  • Allow popup function to be called directly. (Thanks to @mlf176f2)

Version 1.2.2

  • Add a Japanese README.
  • Add a documentation about key-chord hack.

Version 1.2.1

  • Support for mode specific key sequences in guide-key/guide-key-sequence. (Thanks to @Fuco1)

Version 1.2.0

  • Add a feature to scale the text size in the guide buffer.
  • Add a feature to popup the guide buffer with delay. (Thanks to @deprecated)
  • Fix up README. (Thanks to @haxney)

Version 1.1.1

  • Suppress an annoying message, “No following key”.

Version 1.1.0

  • Add a functionality to check an input key sequence recursively. This enables to avoid adding many prefixes to guide-key/guide-key-sequence. (Thanks @kui)

Version 1.0.1

  • Change to save and restore a last configuration of popwin

Version 1.0.0

  • First release version
  • Adjust names of functions and variables
  • Add some documentations

Version 0.1.2

  • Enable to guide key-chord bindings.

Version 0.1.1

  • Make guide-key-mode global minor mode.

Version 0.1.0

  • Initial version.