rnhmjoj/qutebrowser
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Improve bind documentation

Browse Source 
[ci skip]
This commit is contained in:
Florian Bruhin 2017-09-19 13:56:29 +02:00
parent bb073e1709
commit 1a1a6ebf79
3 changed files with 23 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
doc/help/configuring.asciidoc
View File

@ -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('<Ctrl-v>', '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('<Ctrl-y>', '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('<Ctrl-v>', '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('<Ctrl-v>', 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 = {}`.

3
doc/help/settings.asciidoc
View File

@ -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: <<types,Dict>>

64
qutebrowser/config/configdata.yml
View File

@ -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 `<Ctrl-e>` 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 `<Escape>` to leave the mode. It might be useful to bind `<Escape>`
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