summaryrefslogtreecommitdiffstats
path: root/DOCS
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2014-11-23 15:08:49 +0100
committerwm4 <wm4@nowhere>2014-11-23 15:13:35 +0100
commitae5df9be98e4193342321f30285655fcf88e7e63 (patch)
tree3f327acc1c25f3e48bebfc13c0d0061823c282e0 /DOCS
parent7b47f12f8f1cae385060741e4e7f758297515225 (diff)
downloadmpv-ae5df9be98e4193342321f30285655fcf88e7e63.tar.bz2
mpv-ae5df9be98e4193342321f30285655fcf88e7e63.tar.xz
input, lua: redo input handling
Much of it is the same, but now there's the possibility to distinguish key down/up events in the Lua API.
Diffstat (limited to 'DOCS')
-rw-r--r--DOCS/client-api-changes.rst2
-rw-r--r--DOCS/man/input.rst22
-rw-r--r--DOCS/man/lua.rst25
3 files changed, 40 insertions, 9 deletions
diff --git a/DOCS/client-api-changes.rst b/DOCS/client-api-changes.rst
index 9490fa4b7a..177c70cb16 100644
--- a/DOCS/client-api-changes.rst
+++ b/DOCS/client-api-changes.rst
@@ -25,6 +25,8 @@ API changes
::
+ 1.10 - deprecate/disable everything directly related to script_dispatch
+ (most likely affects nobody)
1.9 - add enum mpv_end_file_reason for mpv_event_end_file.reason
- add MPV_END_FILE_REASON_ERROR and the mpv_event_end_file.error field
for slightly better error reporting on playback failure
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 3e4fb300f8..a1cca52191 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -541,8 +541,26 @@ Input Commands that are Possibly Subject to Change
``<target>``. Each client (scripts etc.) has a unique name. For example,
Lua scripts can get their name via ``mp.get_script_name()``.
- (Scripts use this internally to dispatch key bindings, and this can also
- be used in input.conf to reassign such bindings.)
+``script_binding "<name>"``
+ Invoke a script-provided key binding. This can be used to remap key
+ bindings provided by external Lua scripts.
+
+ The argument is the name of the binding.
+
+ It can optionally be prefixed with the name of the script, using ``/`` as
+ separator, e.g. ``script_binding scriptname/bindingname``.
+
+ For completeness, here is how this command works internally. The details
+ could change any time. On any matching key event, ``script_message_to``
+ or ``script_message`` is called (depending on whether the script name is
+ included), where the first argument is the string ``key-binding``, the
+ second argument is the name of the binding, and the third argument is the
+ key state as string. The key state consists of a number of letters. The
+ first letter is one of ``d`` (key was pressed down), ``u`` (was released),
+ ``r`` (key is still down, and was repeated; only if key repeat is enabled
+ for this binding), ``p`` (key was pressed; happens if up/down can't be
+ tracked). The second letter whether the event originates from the mouse,
+ either ``m`` (mouse button) or ``-`` (something else).
``ab_loop``
Cycle through A-B loop states. The first command will set the ``A`` point
diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
index e09792a277..3f9e90e0b0 100644
--- a/DOCS/man/lua.rst
+++ b/DOCS/man/lua.rst
@@ -198,12 +198,23 @@ The ``mp`` module is preloaded, although it can be loaded manually with
overwritten. You can omit the name, in which case a random name is generated
internally.
- The last argument is used for additional flags. Currently, this includes
- the string ``repeatable``, which enables key repeat for this specific
- binding.
+ The last argument is used for optional flags. This is a table, which can
+ have the following entries:
- Internally, key bindings are dispatched via the ``script_message_to`` input
- command and ``mp.register_script_message``.
+ ``repeatable``
+ If set to ``true``, enables key repeat for this specific binding.
+
+ ``complex``
+ If set to ``true``, then ``fn`` is called on both key up and down
+ events (as well as key repeat, if enabled), with the first
+ argument being a table. This table has an ``event`` entry, which
+ is set to one of the strings ``down``, ``repeat``, ``up`` or
+ ``press`` (the latter if key up/down can't be tracked). It further
+ has an ``is_mouse`` entry, which tells whether the event was caused
+ by a mouse button.
+
+ Internally, key bindings are dispatched via the ``script_message_to`` or
+ ``script_binding`` input commands and ``mp.register_script_message``.
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
@@ -226,7 +237,7 @@ The ``mp`` module is preloaded, although it can be loaded manually with
::
- y script_message something
+ y script_binding something
This will print the message when the key ``y`` is pressed. (``x`` will
@@ -237,7 +248,7 @@ The ``mp`` module is preloaded, although it can be loaded manually with
::
- y script_message_to fooscript something
+ y script_binding fooscript.something
``mp.add_forced_key_binding(...)``
This works almost the same as ``mp.add_key_binding``, but registers the