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.

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