emacs-which-key, 在弹出窗口中,显示可用键绑定的Emacs软件包

分享于 

23分钟阅读

GitHub

  繁體 雙語
Rewrite of guide-key for emacs
  • 源代码名称:emacs-which-key
  • 源代码网址:http://www.github.com/justbur/emacs-which-key
  • emacs-which-key源代码文档
  • emacs-which-key源代码下载
  • Git URL:
    git://www.github.com/justbur/emacs-which-key.git
    Git Clone代码到本地:
    git clone http://www.github.com/justbur/emacs-which-key
    Subversion代码到本地:
    $ svn co --depth empty http://www.github.com/justbur/emacs-which-key
    Checked out revision 1.
    $ cd repo
    $ svn up trunk
    
    哪个键

    http://melpa.org/packages/which-key-badge.svghttp://stable.melpa.org/packages/which-key-badge.svghttps://travis-ci.org/justbur/emacs-which-key.svg?branch=master

    最近的更改

    ::: 已经添加 which-key-enable-extended-define-key

    允许使用简洁的语法来指定替换文本,使用 define-key 或者使用 define-key的替代。 请参见字符串字符串和自定义字符串替换字符串。

    2017-11-13: Added

    显示当前主要模式映射中的活动绑定。

    简介

    which-key 是Emacs的次要模式,它在当前输入的不完整命令( 前缀) 中显示键绑定。 例如,如果输入 C-x 并等待默认 1,minibuffer将随着 C-x ( 或者尽可能多的空间允许你的设置)的所有可以用键绑定而扩展。 这包括像 C-x 8 这样的前缀,这些前缀在不同的面中显示。 屏幕截图的屏幕截图如下所示。 which-key 开始重写 guide-key-mode,但是特性集在一定程度上是发散的。

    目录

    安装

    MELPA

    在将 MELPA 设置为存储库之后,使用 M-x package-install which-key 或者你喜欢的方法。 你需要调用 which-key-mode 以启用次要模式。

    手动

    将 which-key.el 添加到 load-path 中并要求。 类似

    (add-to-list'load-path"path/to/which-key.el")
    (require'which-key)
    (which-key-mode)

    初始设置

    如果你对默认设置满意,则不需要进一步设置。 尝试其他选项,有 3种默认配置的选择是预先配置的。 主要的选择是你希望哪个键缓冲区显示。 默认选项的截图将在下一节中显示。

    在每种情况下,我们都显示了尽可以能多的关键绑定,因为我们可以。 约束由多个因素决定,包括Emacs设置,当前Emacs帧的大小以及下面的主要设置。

    有很多替代能力,它们是相当灵活的(。使用正则表达式的能力例如)。 这使得哪个键非常可以定制。

    侧边窗口底部选项

    底部弹出窗口窗口。 这是当前默认值。 要还原这里设置,请使用

    (which-key-setup-side-window-bottom)

    ./img/which-key-bottom.png

    右侧窗口右侧选项

    右侧弹出窗口窗口。 默认使用

    (which-key-setup-side-window-right)

    注意默认设置相当保守,并且不会在较窄的帧上显示。 如果有消息说明哪个键无法显示密钥,请尝试使框架更宽或者调整与最大宽度( 查看 M-x customize-group which-key ) 相关的默认值。

    ./img/which-key-right.png

    左侧窗口右侧的窗口

    这是前两个选择的组合。 如果没有房间,它会尽量使用底部,这通常是比较容易的,这通常更容易把钥匙放进屏幕上。 如果Emacs框架的大小频繁变化,这个设置会很有帮助,如果使用动态/平铺窗口管理器。

    (which-key-setup-side-window-right-bottom)

    Minibuffer选项

    接管 minibuffer。为推荐的配置使用

    (which-key-setup-minibuffer)

    ./img/which-key-minibuffer.png

    注意minibuffer的最大高度是通过内置变量 max-mini-window-height 控制的。 另外,分页命令与minibuffer选项不能可靠地工作。 如果需要分页,请使用底部窗口中的侧窗口。

    附加命令

    • which-key-show-top-level 将显示没有前缀的大多数键绑定。 最重要的不是全部,因为很多用户对大多数用户可能并不感兴趣。
    • which-key-show-major-mode 将显示当前活动的主要模式绑定。 它类似于 C-h m,但它的关键格式是。 它还知道使用 evil-define-key 定义的Evil 命令。
    • which-key-show-next-page 是用于分页的命令。
    • which-key-undo 可以用于在键序列中间撤消最后一次按键。

    特殊功能和配置选项

    有比这里描述的更多的选项。 所有可以配置的变量都可以通过 M-x customize-group which-key

    弹出类型选项

    默认情况下,键可以使用三种不同的弹出类型来显示可用键。 变量 which-key-popup-type 决定使用哪一个。

    minibuffer
    (setq which-key-popup-type 'minibuffer)

    在minibuffer中显示键。

    窗口
    (setq which-key-popup-type 'side-window)

    在侧边窗口中显示关键点。 这里弹出式类型还有更多选项:

    ;; location of which-key window. valid values: top, bottom, left, right, ;; or a list of any of the two. If it's a list, which-key will always try;; the first location first. It will go to the second location if there is;; not enough room to display any keys in the first location(setq which-key-side-window-location 'bottom);; max width of which-key window, when displayed at left or right.;; valid values: number of columns (integer), or percentage out of current;; frame's width (float larger than 0 and smaller than 1)(setq which-key-side-window-max-width 0.33);; max height of which-key window, when displayed at top or bottom.;; valid values: number of lines (integer), or percentage out of current;; frame's height (float larger than 0 and smaller than 1)(setq which-key-side-window-max-height 0.25)
    (setq which-key-popup-type 'frame)

    在弹出框中显示键。 这个弹出器在一个终端中不能很好地工作,在任何给定时刻只能显示一帧。 这里弹出式类型还有更多选项:

    ;; max width of which-key frame: number of columns (an integer)(setq which-key-frame-max-width 60);; max height of which-key frame: number of lines (an integer)(setq which-key-frame-max-height 20)
    自定义

    编写自己的显示功能 ! 这需要你写三个函数 which-key-custom-popup-max-dimensions-function , which-key-custom-show-popup-function 以及 which-key-custom-hide-popup-function 有关详细信息,请参阅这些变量的文档,但下面是一个示例( 这是侧窗底部的当前实现)。

    (setq which-key-popup-type 'custom)
    (defunwhich-key-custom-popup-max-dimensions-function (ignore)
     (cons (which-key-height-or-percentage-to-height
     which-key-side-window-max-height)
     (frame-width)))
    (defunfit-horizonatally ()
     (let ((fit-window-to-buffer-horizontallyt))
     (fit-window-to-buffer)))
    (defunwhich-key-custom-show-popup-function (act-popup-dim)
     (let* ((alist '((window-width. fit-horizontally)
     (window-height. fit-window-to-buffer))))
     (if (get-buffer-window which-key--buffer)
     (display-buffer-reuse-window which-key--buffer alist)
     (display-buffer-in-major-side-window which-key--buffer
     'bottom0 alist))))
    (defunwhich-key-custom-hide-popup-function ()
     (when (buffer-live-p which-key--buffer)
     (quit-windows-on which-key--buffer)))

    自定义字符串替换选项

    你可以使用三种不同的替换方法自定义键在缓冲区中显示的方式,每个方法对应于替换列表。 每个列表背后的基本思想是,在每个con单元格的carcdr 中的替换字符串中指定选择字符串。

    自动

    一个较新的选项是 which-key-enable-extended-define-key 它建议 define-key 允许预处理它的参数的哪个键。 语句

    (define-key some-map "f" '("foo". long-name-for-command-foo))

    在Emacs中有效。设置这里变量使哪个键自动将对应的命令 NAME 替换为字符串中的文本。 一个很好的例子是命名前缀。 以下将"b"绑定到 nil,并将绑定命名为前缀。

    (define-key some-map "b" '("bar-prefix"))
    "基于密钥"替换

    使用这里方法,可以使用提供的字符串替换键的说明。 下面是一个例子

    (which-key-add-key-based-replacements
     "C-x C-f""find files")

    其中第一个字符串是要替换它的描述的键组合,以适合于 kbd的形式。 键组合使用第二个字符串覆盖描述,"查找文件"。 在第二种类型中,你可以将替换限制为主要模式。 比如,

    (which-key-add-major-mode-key-based-replacements 'org-mode"C-c C-c""Org C-c C-c""C-c C-a""Org Attach")

    第一个条目是主要模式,后面是第一个条目类型的列表。 如果在主要模式下列出相同的键组合,则主要模式版本优先。

    关键字和描述替换

    第二和第三种方法针对用于键的文本和直接描述。 相关变量为 which-key-replacement-alist。 下面是默认密钥替换的一个示例

    (push '(("<([[:alnum:]-]+)>".nil) . ("1".nil))
     which-key-replacement-alist)

    outer单元的每个元素都是 (KEY. BINDING)的con单元格。 外部缺陷的car 决定了如何对密钥绑定进行 MATCH,而 cdr 确定如何替换这些 MATCHES。 有关更多信息,请参见 which-key-replacement-alist的字符串字符串。

    下一个示例演示如何替换描述。

    (push '((nil."left") . (nil."lft")) which-key-replacement-alist)

    下面是使用键替换在结果中包含Unicode字符的示例。 不幸的是,使用Unicode字符可能会改变哪个键缓冲区的对齐方式,因为Unicode字符的宽度不同。

    (add-to-list'which-key-replacement-alist '(("TAB".nil) . ("".nil))
    (add-to-list'which-key-replacement-alist '(("RET".nil) . ("".nil))
    (add-to-list'which-key-replacement-alist '(("DEL".nil) . ("".nil))
    (add-to-list'which-key-replacement-alist '(("SPC".nil) . ("".nil))

    cdr 也可能是接收表单 (KEY. BINDING)cons 并生成相同形式的cons的函数。 这让我们有了一些有趣的想法,比如 @pdcawleyPR #147 建议的想法。

    (push (cons '(nil."paredit-mode") 
     (lambda (kb)
     (cons (car kb)
     (if paredit-mode
     "[x] paredit-mode""[ ] paredit-mode"))))
     which-key-replacement-alist)

    如果 paredit-mode 当前处于活动状态,则将检查此框。

    排序选项

    默认情况下,输出按自定义顺序中的键排序。 缺省顺序是按字母顺序排序每个键的"类",其中类和它们的顺序是

    Special (SPC, TAB,.. .) <Single Character (ASCII) (a,.. .) <Modifier (C-, M-,.. .) <Other

    你可以控制这里变量的ORDER BY 设置。 这也显示了其他可用的选项。

    ;; default(setq which-key-sort-order 'which-key-key-order);; same as default, except single characters are sorted alphabetically;; (setq which-key-sort-order 'which-key-key-order-alpha);; same as default, except all prefix keys are grouped together at the end;; (setq which-key-sort-order 'which-key-prefix-then-key-order);; same as default, except all keys from local maps shown first;; (setq which-key-sort-order 'which-key-local-then-key-order);; sort based on the key description ignoring case;; (setq which-key-sort-order 'which-key-description-order)

    分页选项

    至少有几个前缀有许多键绑定到它们,如 C-x。 哪个键显示的键可以给定你的设置,但是对于这些前缀,这可以能不够。 分页功能使你能够将键绑定到函数 which-key-C-h-dispatch,这将允许你在不更改键序列中的键序列的情况下循环。 有两种稍微不同的方法。

    方法 1 ( 默认值): 使用 help-char ( 或者)

    这是最简单的方式,默认情况下是打开的。 用户

    (setq which-key-use-C-h-commands nil)

    禁用行为( 这将只在切换which-key-mode后才生效,如果已经启用)。 可以在有多个键页的情况下将 C-h 与 switch 页的任何前缀一起使用。 这将更改Emacs的默认行为,这将显示应用于前缀的键绑定列表。 例如如果要键入 C-x C-h,你将得到 C-x 后面的命令列表。 这使用了哪个键来显示这些键,不同于Emacs默认值保存了刚刚输入的不完整前缀。

    命令如下:

    • 使用 n ( 或者 C-n ) 循环浏览页面
    • p ( 或者 C-p ) 循环循环
    • u ( 或者 C-u ) 撤消最后输入的键( ) !
    • 使用 h ( 或者 C-h ) 调用绑定到 C-h的默认命令,通常为 describe-prefix-bindings

    对于那些喜欢 helm-descbinds 但也想使用 C-h 作为关键分页键的人来说,这一点尤其有用。

    注意 C-h 在这里上下文中默认等效于 ?

    方法 2: 绑定你自己的密钥

    实际上,像 C-x 这样的前缀所需要做的就是将 <f5> 绑定到相关命令。

    (define-key which-key-mode-map (kbd"C-x <f5>") 'which-key-C-h-dispatch)

    这完全等同于

    (setq which-key-paging-prefixes '("C-x"))
    (setq which-key-paging-key "<f5>")

    如果你有许多前缀,则提供后者以方便使用。

    自定义选项

    键使用的面为

    FaceApplied ToDefault定义
    which-key-key-face每个按键序列:inherit font-lock-constant-face
    which-key-separator-face分隔符( → ):inherit font-lock-comment-face
    which-key-note-face提示和注释:inherit which-key-separator-face
    which-key-special-key-face用户定义的特殊键:inherit which-key-key-face :inverse-video t :weight bold
    which-key-group-description-face命令组( 例如,keymap ):inherit font-lock-keyword-face
    which-key-command-description-face不在本地地图中的命令:inherit font-lock-function-name-face
    which-key-local-map-description-face本地地图中的命令:inherit which-key-command-description-face

    最后两个应该解释。 命令存在于许多可能的映射中之一。 你可以区分本地映射,这取决于你所在的缓冲区,哪些模式是活动的。等等 和全局地图。 这可能对你区分两者有帮助。 这样做的一种方法是像这样从 which-key-command-description-face 中删除默认

    (set-face-attribute'which-key-command-description-facenil:inheritnil)

    另一种方法是使本地地图键显示为粗体

    (set-face-attribute'which-key-local-map-description-facenil:weight'bold)

    你也可以使用 M-x customize-face 自定义上面的任何一个以满足你的喜好。

    其他选项

    下面的选项也可以通过定制。 显示它们的默认值。

    ;; Set the time delay (in seconds) for the which-key popup to appear. A value of;; zero might cause issues so a non-zero value is recommended.(setq which-key-idle-delay 1.0);; Set the maximum length (in characters) for key descriptions (commands or;; prefixes). Descriptions that are longer are truncated and have".." added.(setq which-key-max-description-length 27);; Use additonal padding between columns of keys. This variable specifies the;; number of spaces to add to the left of each column.(setq which-key-add-column-padding 0);; The maximum number of columns to display in the which-key buffer. nil means;; don't impose a maximum.(setq which-key-max-display-columns nil);; Set the separator used between keys and descriptions. Change this setting to;; an ASCII character if your font does not show the default arrow. The second;; setting here allows for extra padding for Unicode characters. which-key uses;; characters as a means of width measurement, so wide Unicode characters can;; throw off the calculation.(setq which-key-separator "" )
    (setq which-key-unicode-correction 3);; Set the prefix string that will be inserted in front of prefix commands;; (i.e., commands that represent a sub-map).(setq which-key-prefix-prefix "+" );; Set the special keys. These are automatically truncated to one character and;; have which-key-special-key-face applied. Disabled by default. An example;; setting is;; (setq which-key-special-keys '("SPC""TAB""RET""ESC""DEL"))(setq which-key-special-keys nil);; Show the key prefix on the left, top, or bottom (nil means hide the prefix).;; The prefix consists of the keys you have typed so far. which-key also shows;; the page information along with the prefix.(setq which-key-show-prefix 'left);; Set to t to show the count of keys shown vs. total keys in the mode line.(setq which-key-show-remaining-keys nil)

    第三方库支持

    为第三方库提供了一些支持,这些库不使用查找命令的标准方法。 其中一些需要显式启用。 这里代码包含一些黑客攻击,因此请报告任何问题。

    键和弦

    默认情况下启用。

    Evil 运算符

    Evil 运动和文本对象( 如 d ) 并不是全部按标准方式查找。 如果 Evil 是loaded的,那么通过使用 which-key-allow-evil-operators 来控制它是不应该的,因为它是loaded的,因为它需要显式地启用。 前者允许内部和外部文本对象映射显示,而后者显示的是运动。

    上帝模式

    通话 (which-key-enable-god-mode-support) 加载god模式以启用对上帝模式键序列的支持。 这是新的实验,所以请报告任何问题。

    更多示例

    :带拆分框架的漂亮显示器

    ,键,即使框架被分割成多个 Windows,键看起来也很好。

    ./img/which-key-right-split.png

    ./img/which-key-bottom-split.png

    谢谢

    特别感谢

    • 用于帮助初始开发和查找多个的 @bmag 插件。
    • 在其他方面修改代码使之成为可能的用户。

    PAC  PACK  KEY  disp  POP  Emacs  
    相关文章