diff --git a/doc/help/configuring.asciidoc b/doc/help/configuring.asciidoc index 2842db632..dd2612045 100644 --- a/doc/help/configuring.asciidoc +++ b/doc/help/configuring.asciidoc @@ -66,6 +66,9 @@ link:commands.html#unbind[`:unbind`] commands: Key chains starting with a comma are ideal for custom bindings, as the comma key will never be used in a default keybinding. +See the help pages linked above (or `:help :bind`, `:help :unbind`) for more +information. + Configuring qutebrowser via config.py ------------------------------------- @@ -159,28 +162,39 @@ To bind a key: .config.py: [source,python] ---- -config.bind(',v', 'spawn mpv {url}', mode='normal') +config.bind('', 'spawn mpv {url}') ---- -For bindings in normal mode, you can also leave out the `, mode='normal'` part. +To bind a key in a mode other than `'normal'`, add a `mode` argument: + +[source,python] +---- +config.bind('', 'prompt-yes', mode='prompt') +---- If the key is already bound, `force=True` needs to be given to rebind it: [source,python] ---- -config.bind(',v', 'message-info foo', mode='normal', force=True) +config.bind('', 'message-info foo', force=True) ---- To unbind a key (either a key which has been bound before, or a default binding): [source,python] ---- -config.unbind(',v', mode='normal') +config.unbind('', mode='normal') ---- -Key chains starting with a comma are ideal for custom bindings, as the comma key +To bind keys without modifiers, specify a key chain to bind as a string. Key +chains starting with a comma are ideal for custom bindings, as the comma key will never be used in a default keybinding. +[source,python] +---- +config.bind(',v', 'spawn mpv {url}') +---- + To suppress loading of any default keybindings, you can set `c.bindings.default = {}`. diff --git a/doc/help/settings.asciidoc b/doc/help/settings.asciidoc index 907e5d7c1..7c4950871 100644 --- a/doc/help/settings.asciidoc +++ b/doc/help/settings.asciidoc @@ -308,6 +308,7 @@ Default: +pass:[auto]+ Keybindings mapping keys to commands in different modes. This setting is a dictionary containing mode names and dictionaries mapping keys to commands: `{mode: {key: command}}` +While it's possible to bind keys by modifying this setting, it's recommended to use the `config.bind()` function or `:bind` command, which makes modifying it easier and checks for more possible mistakes. If you want to map a key to another key, check the `bindings.key_mappings` setting instead. For special keys (can't be part of a keychain), enclose them in `<`...`>`. For modifiers, you can use either `-` or `+` as delimiters, and these names: @@ -364,7 +365,7 @@ Default: empty === bindings.default Default keybindings. If you want to add bindings, modify `bindings.commands` instead. The main purpose of this setting is that you can set it to an empty dictionary if you want to load no default keybindings at all. -If you want to preserve default bindings (and get new bindings when there is an update), add new bindings to `bindings.commands` (or use `:bind`) and leave this setting alone. +If you want to preserve default bindings (and get new bindings when there is an update), use `config.bind()` in `config.py` or the `:bind` command, and leave this setting alone. Type: <> diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml index 8504c224e..b535c499d 100644 --- a/qutebrowser/config/configdata.yml +++ b/qutebrowser/config/configdata.yml @@ -2167,7 +2167,7 @@ bindings.default: want to load no default keybindings at all. If you want to preserve default bindings (and get new bindings when there is - an update), add new bindings to `bindings.commands` (or use `:bind`) and + an update), use `config.bind()` in `config.py` or the `:bind` command, and leave this setting alone. bindings.commands: @@ -2193,64 +2193,4 @@ bindings.commands: `{mode: {key: command}}` - If you want to map a key to another key, check the `bindings.key_mappings` - setting instead. - - For special keys (can't be part of a keychain), enclose them in `<`...`>`. - For modifiers, you can use either `-` or `+` as delimiters, and these names: - - * Control: `Control`, `Ctrl` - - * Meta: `Meta`, `Windows`, `Mod4` - - * Alt: `Alt`, `Mod1` - - * Shift: `Shift` - - For simple keys (no `<>`-signs), a capital letter means the key is pressed - with Shift. For special keys (with `<>`-signs), you need to explicitly add - `Shift-` to match a key pressed with shift. - - If you want a binding to do nothing, bind it to the `nop` command. - If you want a default binding to be passed through to the website, bind it - to null. - - Note that some commands which are only useful for bindings (but not used - interactively) are hidden from the command completion. See `:help` for a - full list of available commands. - - The following modes are available: - - - * normal: The default mode, where most commands are invoked. - - - * insert: Entered when an input field is focused on a website, or by - pressing `i` in normal mode. Passes through almost all keypresses to the - website, but has some bindings like `` to open an external editor. - Note that single keys can't be bound in this mode. - - * hint: Entered when `f` is pressed to select links with the keyboard. Note - that single keys can't be bound in this mode. - - * passthrough: Similar to insert mode, but passes through all keypresses - except `` to leave the mode. It might be useful to bind `` - to some other key in this mode if you want to be able to send an Escape - key to the website as well. Note that single keys can't be bound in this - mode. - - * command: Entered when pressing the `:` key in order to enter a command. - Note that single keys can't be bound in this mode. - - * prompt: Entered when there's a prompt to display, like for download - locations or when invoked from JavaScript. - + - You can bind normal keys in this mode, but they will be only active when a - yes/no-prompt is asked. For other prompt modes, you can only bind special - keys. - - * caret: Entered when pressing the `v` mode, used to select text using the - keyboard. - - * register: Entered when qutebrowser is waiting for a register name/key for - commands like `:set-mark`. + While it's possible to bind keys by modifying this setting, it's recommended