From ae5df9be98e4193342321f30285655fcf88e7e63 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sun, 23 Nov 2014 15:08:49 +0100 Subject: 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. --- DOCS/client-api-changes.rst | 2 ++ DOCS/man/input.rst | 22 ++++++++++++++++++++-- DOCS/man/lua.rst | 25 ++++++++++++++++++------- 3 files changed, 40 insertions(+), 9 deletions(-) (limited to 'DOCS') 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 ````. 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 ""`` + 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 -- cgit v1.2.3