1. Meta

The meta key is used in many key combos, and it is vital to the keyboard UI of Conkeror. However, not all keyboards have a meta key. Therefore Conkeror takes a guess whether your keyboard has a meta key, based on the operating system you are using. The Command key on a Mac is a meta key, so if you are running Conkeror on OS X, your Command key will be what Conkeror considers as meta. If you are running on any other operating system, Conkeror will treat your Alt key as a meta key.

If your keyboard has a meta key, but since you are not in OS X, Conkeror uses your Alt key instead, you can configure Conkeror to use your meta key by putting the following in your rc script:

modifiers.M = new modifier(
    function (event) { return event.metaKey; },
    function (event) { event.metaKey = true; });

Note that due GTK2, if you have used xmodmap to add a meta key, it should be mod4.

Additionally, you can add a modifier A for Alt as follows. The variable modifier_order must be set before any calls to define_key.

modifier_order = ['C', 'M', 'A', 'S'];

2. OS X

2.1. Alt

On OS X, the Alt key combined with any character key sends an "alternate" character. The alternate characters are mostly typographical and mathematical symbols. Thus Alt is similar to Shift: the fact that it was pressed must be ignored, since the character itself is all the information we need about the keypress.

define_key(content_buffer_normal_keymap, "π", "cmd_scrollLineDown"); // Alt-p produces "π" (pi)

But when it was pressed with a non-character key, such as return or tab, it behaves like a simple modifier (like Control, or Meta). When pressed with non-character keys, Alt is represented by the modifier code A.

define_key(content_buffer_normal_keymap, "A-tab", "cmd_scrollLineDown");

2.2. C-space

In OS X, the key combo C-space is consumed by the underlying Mozilla platform, and no keypress event is sent to Conkeror. For this reason, Conkeror provides the alternative binding C-@ for set-mark.

2.3. Option Key as Meta Key

In OS X, option+key gives a dead key (usually greek or some funny character). Because of this, the option key cannot be used as a modifier key since OS X (and hence conkeror) interprets option+key as a character. To get option to be the meta key (M) and apple/command to be the "A"-key, do the following:

1. This page suggests using ukelele to remove the dead keys. So install it. Copy the "US Extended" keyboard map from one of the folder in the dmg file. (Reported for version 3.0.3, this was found inside Unicode.bundle.)

2. Open the file in ukelele. Hit the option key (keyboard picture will change to see the dead keys mapping). Double click each of the keys (a-z, 1-0) and remap to the regular key. For example, option-a to a. Also update option+shift+key to shift+key (For M-<, etc, to work).

3. Save this file; USExtendedNoDeadKey.keylayout is my file. Store in /Library/Keyboard Layouts/ or ~/Library/Keyboard Layouts/. Log out and log back in.

4. In System Preferences > Language & Text > Input Sources, select the layout u created. Select this as your input source.

5. Put the following in your .conkerorrc file:

modifiers.M = new modifier(function (event) { return event.altKey; },
                           function (event) { event.altKey = true; });
modifiers.A = new modifier(function (event) { return event.metaKey; },
                           function (event) { event.metaKey = true; });

3. Caps Lock

The variable key_bindings_ignore_capslock, when true, makes Conkeror override the state of caps lock for command bindings, and force typed characters to upper-case or lower-case based on whether shift was pressed with the character. This does not affect typing in input fields--caps lock will still behave normally for normal typing. Enabling this option will let you use keys like C-x as normal even when caps lock is on.

4. Key Aliases

With a key alias, you can make one key behave like another. Common uses for key aliases are to make C-m behave as return, and C-i behave as tab. Key alias support is provided by the global-overlay-keymap module. To use it, include code like the following in your rc:

require("global-overlay-keymap");
define_key_alias("C-m", "return");

To undo:

undefine_key(global_overlay_keymap, "C-m");

5. Sticky Modifiers

A sticky modifier is a prefix key that acts as a modifier for the next key. People commonly define their escape key to be a sticky meta key, so instead of holding down meta while pressing a key, they can press escape, then the key. Sticky modifier support is provided by the global-overlay-keymap module. To use it, include code like the following in your rc:

require("global-overlay-keymap");
define_sticky_modifier("escape", "M");