summaryrefslogtreecommitdiffstats
path: root/DOCS
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2014-02-17 02:38:07 +0100
committerwm4 <wm4@nowhere>2014-02-17 02:52:58 +0100
commit24fa69dbfa6c5c7a80456218f2c31179864c4d77 (patch)
tree0312cccc355f78cfa1627155eca77cbc0ae6180a /DOCS
parent12b7850f11f524ec158b392d7fceabd4ba193ba3 (diff)
downloadmpv-24fa69dbfa6c5c7a80456218f2c31179864c4d77.tar.bz2
mpv-24fa69dbfa6c5c7a80456218f2c31179864c4d77.tar.xz
lua: add mechanism for script provided key bindings
There was already an undocumented mechanism provided by mp.set_key_bindings and other functions, but this was relatively verbose, and also weird. It was mainly to make the OSC happy (including being efficient and supporting weird corner cases), while the new functions try to be a bit simpler. This also provides a way to let users rebind script-provided commands. (This mechanism is less efficient, because it's O(n^2) for n added key bindings, but it shouldn't matter.)
Diffstat (limited to 'DOCS')
-rw-r--r--DOCS/man/en/lua.rst100
1 files changed, 99 insertions, 1 deletions
diff --git a/DOCS/man/en/lua.rst b/DOCS/man/en/lua.rst
index 0a03ebde5c..89abcb00b5 100644
--- a/DOCS/man/en/lua.rst
+++ b/DOCS/man/en/lua.rst
@@ -92,6 +92,97 @@ The ``mp`` module is preloaded, although it can be loaded manually with
Return the current mpv internal time in seconds as a number. This is
basically the system time, with an arbitrary offset.
+``mp.register_script_command(name, fn)``
+ Register a command named ``name``. If the script receives a message
+ with the given name as first argument, ``fn(...)`` is called with the
+ rest of the script commands.
+
+ If a command with the given name already exists, it's overwritten.
+
+ This is intended for allowing users to interact the script in some ways
+ using the ``script_message`` input command.
+
+ Example:
+
+ In a script, say ``fooscript.lua``:
+
+ ::
+
+ function something_handler(arg1, arg2)
+ print("arg1=" .. arg1)
+ print("arg2=" .. arg2)
+ end
+ mp.register_script_command("something", something_handler)
+
+ input.conf:
+
+ ::
+
+ x script_message lua/fooscript something "hello" "you"
+
+ This will print the lines ``arg1=hello`` and ``arg2=something`` when the
+ key ``x`` is pressed.
+
+ Also see ``mp.add_key_binding`` how to add key bindings by default.
+
+``mp.unregister_script_command(name)``
+ Undo a previous registration with ``mp.register_script_command``. Does
+ 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.
+
+ Example:
+
+ ::
+
+ function something_handler()
+ print("the key was pressed")
+ end
+ mp.add_key_binding("x", "something", something_handler)
+
+ This will print the message ``the key was pressed`` when ``x`` was pressed.
+
+ The user can remap these key bindings. Assume the above script was using
+ the filename ``fooscript.lua``, then the user has to put the following
+ into his input.conf to remap the command to the ``y`` key:
+
+ ::
+
+ y script_message lua/fooscript something
+
+ This will print the message when the key ``y`` is pressed. (``x`` will
+ still work, unless the user overmaps it.)
+
+``mp.add_forced_key_binding(...)``
+ This works almost the same as ``mp.add_key_binding``, but registers the
+ key binding in a way that will overwrite the user's custom bindings in his
+ input.conf. (``mp.add_key_binding`` overwrites default key bindings only,
+ but not those by the user's input.conf.)
+
+``mp.remove_key_binding(name)``
+ Remove a key binding added with ``mp.add_key_binding`` or
+ ``mp.add_forced_key_binding``. Use the same name as you used when adding
+ the bindings. It's not possible to remove bindings for which you omitted
+ the name.
+
``mp.register_event(name, fn)``
Call a specific function when an event happens. The event name is a string,
and the function fn is a Lua function value.
@@ -136,7 +227,14 @@ The ``mp`` module is preloaded, although it can be loaded manually with
this equally, so you should be careful about collisions.
``mp.get_script_name()``
- Return the name of the current script.
+ Return the name of the current script. The name is usually made of the
+ filename of the script, with directory and file extension removed, and
+ prefixed with ``lua/``. If there are several script which would have the
+ same name, it's made unique by appending a number.
+
+ .. admonition:: Example
+
+ The script ``/path/to/fooscript.lua`` becomes ``lua/fooscript``.
``mp.suspend()``
Suspend the mpv main loop. There is a long-winded explanation of this in