summaryrefslogtreecommitdiffstats
path: root/DOCS
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2014-02-17 20:25:11 +0100
committerwm4 <wm4@nowhere>2014-02-17 20:30:44 +0100
commit6d87f6f5501405b91603c3331d101b0d01322105 (patch)
tree7825d21af560cb29edfe87939e6a108e722f6bcc /DOCS
parentc79ea489bfa01df382ec26379ceb94e6230f87b7 (diff)
downloadmpv-6d87f6f5501405b91603c3331d101b0d01322105.tar.bz2
mpv-6d87f6f5501405b91603c3331d101b0d01322105.tar.xz
manpage: lua: attempt to improve add_key_binding() description
Diffstat (limited to 'DOCS')
-rw-r--r--DOCS/man/en/lua.rst41
1 files changed, 23 insertions, 18 deletions
diff --git a/DOCS/man/en/lua.rst b/DOCS/man/en/lua.rst
index 925e473079..8a191f6685 100644
--- a/DOCS/man/en/lua.rst
+++ b/DOCS/man/en/lua.rst
@@ -141,24 +141,29 @@ The ``mp`` module is preloaded, although it can be loaded manually with
nothing if the ``name`` wasn't registered.
``mp.add_key_binding(key, name|fn [,fn])``
- Register a key binding. The binding will be mapped to the given ``key``,
- which is a string describing the physical key. This uses the same key
- names as in input.conf, and also allows combinations (e.g. ``ctrl+a``).
-
- Key bindings are dispatched as script commands. The ``name`` argument is
- the name used to invoke command handlers as registered by
- ``mp.register_script_command``. The name can also be used by users to remap
- the bindings provided by your script (see below).
-
- If a key binding or a command with the given name already exists, it's
- overwritten.
-
- The ``fn`` parameter is optional. If provided, it must be a function, and
- will be called when the key is pressed. Actually, this just for
- convenience, and literally calls ``mp.register_script_command(name, fn)``.
-
- You can also omit the name and only provide a function ``fn`` instead. Then
- a random name is generated internally.
+ Register callback to be run on a key binding. The binding will be mapped to
+ the given ``key``, which is a string describing the physical key. This uses
+ the same key names as in input.conf, and also allows combinations
+ (e.g. ``ctrl+a``).
+
+ After calling this function, key presses will cause the function ``fn`` to
+ be called (unless the user overmapped the key with another binding).
+
+ The ``name`` argument should be a short symbolic string. It allows the user
+ to remap the key binding via input.conf using the ``script_message``
+ command, the script name, and the name of the key binding (see below for
+ an example). The name should be unique across other bindings in the same
+ script - if not, the previous binding with the same name will be
+ overwritten. You can omit the name, in which case a random name is generated
+ internally.
+
+ Internally, key bindings are dispatched via the ``script_message`` input
+ command and ``mp.register_script_command``.
+
+ Trying to map multiple commands to a key will essentially prefer a random
+ binding, while the other bindings are not called. It is guaranteed that
+ user defined bindings in the central input.conf are preferred over bindings
+ added with this function (but see ``mp.add_forced_key_binding``).
Example: