• Keymaps

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.

There are a few keymaps used for specialty purposes for specific commands, which we will discuss later, but all of the most important keymaps are arranged in a single hierarchy. Keymaps deeper into the hierarchy inherit key bindings from their ancestors. Child keymaps can override bindings in parent keymaps.

2. Hierarchy of Contexts

• default_base_keymap

• Commands bound here will be available in any context of the hierarchy without an override. Very few commands actually belong in this keymap because commands that work in the minibuffer usually involve extra processing compared to their normal-buffer counterparts. An example of a command for which this keymap is appropriate is universal-argument, which works the same in all buffers, as well as the minibuffer.

  • default_global_keymap

  • This keymap is the parent of all keymaps for interacting with content, both in normal web browsing buffers and special buffers like *Download* and *Help*. It is not the ancestor of any minibuffer keymaps.

    • 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.

      • content_buffer_caret_keymap

      • This keymap contains the movement and selection bindings for conkeror's caret-mode. (M-x caret-mode)

      • content_buffer_form_keymap

      • Base keymap for form elements.

        • content_buffer_checkbox_keymap

        • Aforementioned keymap for when a checkbox input element on a webpage has focus.

        • content_buffer_select_keymap

        • content_buffer_text_keymap

          • content_buffer_textarea_keymap

            • content_buffer_richedit_keymap

              • gmail_richedit_keymap (page mode)

            • gmail_textarea_keymap (page mode)

          • gmail_text_keymap (page mode)

      • google_calendar_keymap (page mode)

      • google_maps_keymap (page mode)

      • google_reader_keymap (page mode)

      • google_search_results_keymap (page mode)

      • This is the keymap of the page-mode, google-search-results-mode.

      • reddit_keymap (page mode)

    • special_buffer_keymap

      • download_buffer_keymap

      • help_buffer_keymap

  • hint_keymap

  • isearch_keymap

  • minibuffer_base_keymap

    • minibuffer_keymap

  • single_character_options_minibuffer_keymap

3. Command-Specific Keymaps

• default_help_keymap

• minibuffer_message_keymap

• content_buffer_quote_keymap

• content_buffer_quote_next_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.

4. 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");

5. 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 overlay keymap as the context keymap of the minibuffer.