#pragma section-numbers on <> = 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. = 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. = Buffers = 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*`. 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 select element in content has focus. content_buffer_text_keymap:: :: Keymap for editable input elements in content. Parent keymap is text_keymap. Content_buffer_text_keymap only contains editing commands which are only for content. content_buffer_textarea_keymap:: :: Keymap for textareas 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. = Minibuffer = hint_keymap:: isearch_keymap:: minibuffer_base_keymap:: minibuffer_keymap:: single_character_options_minibuffer_keymap:: = 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 = 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`). = 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. = 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"); }}} = 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''.