input: add text produced by key to script key events

Particularly for "any_unicode" mappings, so they don't have to
special-case keys like '#' and ' ', which are normally mapped to
symbolic names for input.conf reasons. (Though admittedly, this is a
pretty minor thing, since API users could map these manually.)

2 files changed, 14 insertions, 1 deletions

diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 81126efd43..02264f0eda 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -971,8 +971,13 @@ Input Commands that are Possibly Subject to Change
     2. The name of the binding (as established above).
     3. The key state as string (see below).
     4. The key name (since mpv 0.15.0).
+    5. The text the key would produce, or empty string if not applicable.
 
-    The key state consists of 2 letters:
+    The 5th argument is only set if no modifiers are present (using the shift
+    key with a letter is normally not emitted as having a modifier, and results
+    in upper case text instead, but some backends may mess up).
+
+    The key state consists of 2 characters:
 
     1. 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
@@ -980,6 +985,9 @@ Input Commands that are Possibly Subject to Change
     2. Whether the event originates from the mouse, either ``m`` (mouse button)
        or ``-`` (something else).
 
+    Future versions can add more arguments and more key state characters to
+    support more input peculiarities.
+
 ``ab-loop``
     Cycle through A-B loop states. The first command will set the ``A`` point
     (the ``ab-loop-a`` property); the second the ``B`` point, and the third
diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
index 8861552562..2900a5393c 100644
--- a/DOCS/man/lua.rst
+++ b/DOCS/man/lua.rst
@@ -265,6 +265,11 @@ The ``mp`` module is preloaded, although it can be loaded manually with
                 The name of they key that triggered this, or ``nil`` if invoked
                 artificially. If the key name is unknown, it's an empty string.
 
+            ``key_text``
+                Text if triggered by a text key, otherwise ``nil``. See
+                description of ``script-binding`` command for details (this
+                field is equivalent to the 5th argument).
+
     Internally, key bindings are dispatched via the ``script-message-to`` or
     ``script-binding`` input commands and ``mp.register_script_message``.