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.