Contents
1. Overview
Conkeror has a sophisticated keyboard interface for interacting with web content. Unfortunately, in this area, power comes at the price of some complexity. Conkeror's keymap system may seem more complex than that of its mentor software, Emacs, but this complexity is unavoidable given the complexity of the GUI-web environment that Conkeror must deal with. For example, there must be a set of key bindings for use in text boxes, and another for checkboxes; a set for viewing web pages, and another for non-webpage buffers. In fact, many keymaps for the many different contexts of focus that the user can be in.
When you want to bind a command so it is available in suitable contexts, you need to pick the proper keymap to bind it in. In this article, we will try to describe all of the available keymaps to help you select the right one.
At any moment a Conkeror window has a stack of current keymaps, with the keymaps most specific to the context at the top, and the most general at the bottom. Which keymaps are present in this stack is partly static and partly dynamic.
For example, content_buffer_normal_keymap has a parent link to default_global_keymap. Binding lookups in the one will always fall through to the other. This is a static link. On the other hand, the relationship between content_buffer_checkbox_keymap and content_buffer_form_keymap is dynamic. If a checkbox is focused, content_buffer_checkbox_keymap will be active, but content_buffer_form_keymap will only be active if that checkbox is inside of an HTML <form> (from here on, we'll just call that 'a form').
2. Global
- default_base_keymap
This keymap is almost always at the bottom of the keymap stack, whether the context is in a buffer or the minibuffer. Commands bound here will be available in any context, with few exceptions. An example of a command for which this keymap is appropriate is universal-argument.
- text_keymap
- This keymap contains all of the basic editing commands and is an ancestor keymap in every editing context, including content text boxes and minibuffer states which support editing.
3. Buffers
- default_global_keymap
This keymap is the parent of all keymaps for interacting with content, both in normal web browsing buffers and in special buffers like *Download* and *Help*.
- content_buffer_normal_keymap
- The context of this keymap is content-buffers, a.k.a. web browser buffers. This keymap contains a wide variety of commands--everything related to navigation, scrolling, and much more.
- special_buffer_keymap
- download_buffer_keymap
- help_buffer_keymap
- content_buffer_form_keymap
- This keymap is in effect whenever the context is on a form element which is inside of a form.
- content_buffer_checkbox_keymap
Keymap for when a checkbox <input> element in content has focus.
- content_buffer_select_keymap
Keymap for when a drop-down menu or scrolling-list <select> element in content has focus.
- content_buffer_text_keymap
Keymap for editable-text-field <input> elements in content. Parent keymap is text_keymap. Only contains editing commands which are only for content.
- content_buffer_textarea_keymap
Keymap for editable-text-box <textarea> elements in content. Parent keymap is content_buffer_text_keymap. This keymap provides bindings for moving the cursor up and down and other commands which are only valid in multiline editing.
- content_buffer_richedit_keymap
Keymap for richedit elements. Parent keymap is content_buffer_textarea_keymap.
4. Minibuffer
- hint_keymap
- isearch_keymap
- minibuffer_base_keymap
- minibuffer_keymap
- single_character_options_minibuffer_keymap
5. Buffer Mode Keymaps
- caret_keymap
This keymap contains the movement and selection bindings for conkeror's caret-mode. (M-x caret-mode)
- quote_keymap
- quote_next_keymap
6. Page Mode Keymaps
Many page modes provide keymaps that define special keys for the websites they target. Often these are simply fallthrough bindings, which let specific keys bypass Conkeror's keyboard system so the webpage can handle them. Page mode keymaps always have names that begin with the name of the page mode. You can find out what page mode keymaps are active when a page mode is in effect by reading the describe-bindings buffer (C-h b).
7. Command-Specific Keymaps
- default_help_keymap
- minibuffer_message_keymap
- key_binding_reader_keymap
- universal_argument_keymap
This keymap is invoked by the command universal-argument (C-u) as an overlay that provides bindings on the number keys and the subtract key for typing a numeric prefix argument.
8. Creating Binding Sets
The bulk of this page has been about Conkeror's default binding set. At the time of this writing, it is in fact the only one known to exist. However, it is possible to create other binding sets.
To suppress loading of all of Conkeror's default key bindings, put the following in your rc. Note the use of user_pref. The default binding set is loaded before the rc, so disabling it must be controlled with a user preference.
user_pref("conkeror.load.bindings/default/bindings", 0);
Then make your own set of bindings. The easiest way to get started will be to copy the default bindings directory from the Conkeror source, and modify them. Add the location of your bindings to Conkeror's load_paths, and load them as you would load any module:
require("my-bindings/bindings");
9. Terminology
If you want to be able to talk about how Conkeror's keyboard handling works, it is important to understand some high level terminology.
- context keymap
The context keymap is the keymap corresponding to the focused element, such as an input box, a button, and anchor, or just the base "normal mode" keymap. It can also be a special keymap corresponding to an input mode like quote-mode or caret-mode. Examples of context keymaps are content_buffer_normal_keymap, content_buffer_textarea_keymap, &c.
- active keymap
This is either the same as the context keymap, or when you are in the middle of a key sequence, like just after typing C-x the keymap associated with C-x.
- overlay keymap
More specifically, I.overlay_keymap. This is a keymap that can be set in the interactive context by a prefix command in a key sequence. It has precedence over the context keymap or active keymap in the following keystrokes within the key sequence. This is how universal_argument_keymap is implemented.
- global-overlay-keymap
not to be confused with overlay keymap described above. This is the keymap by which key aliases and sticky modifiers are implemented. It gets called via keypress_hook. It is completely modular, so if global-overlay-keymap.js is not loaded, this keymap does not exist.
- override keymap
This is a keymap for any modal interaction such as a minibuffer prompt. In fact the minibuffer is the only thing that uses it currently. It would not be too inaccurate to think of the override keymap as the context keymap of the minibuffer.