diff options
Diffstat (limited to 'DOCS/man/lua.rst')
| -rw-r--r-- | DOCS/man/lua.rst | 149 |
1 files changed, 119 insertions, 30 deletions
diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index 43954044d1..73776964d5 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -62,15 +62,15 @@ that uses the ``.foo`` file extension. mpv also appends the top level directory of the script to the start of Lua's package path so you can import scripts from there too. Be aware that this will shadow Lua libraries that use the same package path. (Single file scripts do not -include mpv specific directory the Lua package path. This was silently changed -in mpv 0.32.0.) +include mpv specific directories in the Lua package path. This was silently +changed in mpv 0.32.0.) Using a script directory is the recommended way to package a script that consists of multiple source files, or requires other files (you can use ``mp.get_script_directory()`` to get the location and e.g. load data files). Making a script a git repository, basically a repository which contains a -``main.lua``` file in the root directory, makes scripts easily updateable +``main.lua`` file in the root directory, makes scripts easily updateable (without the dangers of auto-updates). Another suggestion is to use git submodules to share common files or libraries. @@ -191,12 +191,20 @@ The ``mp`` module is preloaded, although it can be loaded manually with If starting the command failed for some reason, ``nil, error`` is returned, and ``fn`` is called indicating failure, using the same error value. + ``fn`` is always called asynchronously, even if the command failed to start. + ``mp.abort_async_command(t)`` Abort a ``mp.command_native_async`` call. The argument is the return value of that command (which starts asynchronous execution of the command). Whether this works and how long it takes depends on the command and the situation. The abort call itself is asynchronous. Does not return anything. +``mp.del_property(name)`` + Delete the given property. See ``mp.get_property`` and `Properties`_ for more + information about properties. Most properties cannot be deleted. + + Returns true on success, or ``nil, error`` on error. + ``mp.get_property(name [,def])`` Return the value of the given property as string. These are the same properties as used in input.conf. See `Properties`_ for a list of @@ -300,16 +308,17 @@ The ``mp`` module is preloaded, although it can be loaded manually with ``repeatable`` If set to ``true``, enables key repeat for this specific binding. + This option only makes sense when ``complex`` is not set to ``true``. ``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 the following entries (and - may contain undocumented ones): + If set to ``true``, then ``fn`` is called on key down, repeat and up + events, with the first argument being a table. This table has the + following entries (and may contain undocumented ones): ``event`` Set to one of the strings ``down``, ``repeat``, ``up`` or - ``press`` (the latter if key up/down can't be tracked). + ``press`` (the latter if key up/down/repeat can't be + tracked). ``is_mouse`` Boolean Whether the event was caused by a mouse button. @@ -418,9 +427,9 @@ The ``mp`` module is preloaded, although it can be loaded manually with This depends on the property, and it's a valid feature request to ask for better update handling of a specific property. - If the ``type`` is ``none`` or ``nil``, sporadic property change events are - possible. This means the change function ``fn`` can be called even if the - property doesn't actually change. + If the ``type`` is ``none`` or ``nil``, the change function ``fn`` will be + called sporadically even if the property doesn't actually change. You should + therefore avoid using these types. You always get an initial change notification. This is meant to initialize the user's state to the current value of the property. @@ -430,17 +439,21 @@ The ``mp`` module is preloaded, although it can be loaded manually with that are equal to the ``fn`` parameter. This uses normal Lua ``==`` comparison, so be careful when dealing with closures. -``mp.add_timeout(seconds, fn)`` +``mp.add_timeout(seconds, fn [, disabled])`` Call the given function fn when the given number of seconds has elapsed. Note that the number of seconds can be fractional. For now, the timer's resolution may be as low as 50 ms, although this will be improved in the future. + If the ``disabled`` argument is set to ``true`` or a truthy value, the + timer will wait to be manually started with a call to its ``resume()`` + method. + This is a one-shot timer: it will be removed when it's fired. Returns a timer object. See ``mp.add_periodic_timer`` for details. -``mp.add_periodic_timer(seconds, fn)`` +``mp.add_periodic_timer(seconds, fn [, disabled])`` Call the given function periodically. This is like ``mp.add_timeout``, but the timer is re-added after the function fn is run. @@ -480,7 +493,7 @@ The ``mp`` module is preloaded, although it can be loaded manually with the timer callback function fn is run). Note that these are methods, and you have to call them using ``:`` instead - of ``.`` (Refer to http://www.lua.org/manual/5.2/manual.html#3.4.9 .) + of ``.`` (Refer to https://www.lua.org/manual/5.2/manual.html#3.4.9 .) Example: @@ -527,18 +540,6 @@ Advanced mp functions These also live in the ``mp`` module, but are documented separately as they are useful only in special situations. -``mp.suspend()`` - This function has been deprecated in mpv 0.21.0 and does nothing starting - with mpv 0.23.0 (no replacement). - -``mp.resume()`` - This function has been deprecated in mpv 0.21.0 and does nothing starting - with mpv 0.23.0 (no replacement). - -``mp.resume_all()`` - This function has been deprecated in mpv 0.21.0 and does nothing starting - with mpv 0.23.0 (no replacement). - ``mp.get_wakeup_pipe()`` Calls ``mpv_get_wakeup_pipe()`` and returns the read end of the wakeup pipe. This is deprecated, but still works. (See ``client.h`` for details.) @@ -624,7 +625,7 @@ are useful only in special situations. ``mp.get_osd_size()`` Returns a tuple of ``osd_width, osd_height, osd_par``. The first two give - the size of the OSD in pixels (for video ouputs like ``--vo=xv``, this may + the size of the OSD in pixels (for video outputs like ``--vo=xv``, this may be "scaled" pixels). The third is the display pixel aspect ratio. May return invalid/nonsense values if OSD is not initialized yet. @@ -684,13 +685,13 @@ with values found in the config-file and the command-line (in that order). Example implementation:: - require 'mp.options' local options = { optionA = "defaultvalueA", optionB = -0.5, optionC = true, } - read_options(options, "myscript") + + require "mp.options".read_options(options, "myscript") print(options.optionA) @@ -781,7 +782,7 @@ strictly part of the guaranteed API. The booleans ``is_file`` and ``is_dir`` are provided as a convenience; they can be and are derived from ``mode``. - On error (eg. path does not exist), ``nil, error`` is returned. + On error (e.g. path does not exist), ``nil, error`` is returned. ``utils.split_path(path)`` Split a path into directory component and filename component, and return @@ -862,6 +863,94 @@ strictly part of the guaranteed API. Turn the given value into a string. Formats tables and their contents. This doesn't do anything special; it is only needed because Lua is terrible. +mp.input functions +-------------------- + +This module lets scripts get textual input from the user using the console +REPL. + +``input.get(table)`` + Show the console to let the user enter text. + + The following entries of ``table`` are read: + + ``prompt`` + The string to be displayed before the input field. + + ``submit`` + A callback invoked when the user presses Enter. The first argument is + the text in the console. You can close the console from within the + callback by calling ``input.terminate()``. If you don't, the console + stays open and the user can input more text. + + ``opened`` + A callback invoked when the console is shown. This can be used to + present a list of options with ``input.set_log()``. + + ``edited`` + A callback invoked when the text changes. This can be used to filter a + list of options based on what the user typed with ``input.set_log()``, + like dmenu does. The first argument is the text in the console. + + ``complete`` + A callback invoked when the user presses TAB. The first argument is the + text before the cursor. The callback should return a table of the string + candidate completion values and the 1-based cursor position from which + the completion starts. console.lua will filter the suggestions beginning + with the the text between this position and the cursor, sort them + alphabetically, insert their longest common prefix, and show them when + there are multiple ones. + + ``closed`` + A callback invoked when the console is hidden, either because + ``input.terminate()`` was invoked from the other callbacks, or because + the user closed it with a key binding. The first argument is the text in + the console, and the second argument is the cursor position. + + ``default_text`` + A string to pre-fill the input field with. + + ``cursor_position`` + The initial cursor position, starting from 1. + + ``id`` + An identifier that determines which input history and log buffer to use + among the ones stored for ``input.get()`` calls. The input histories + and logs are stored in memory and do not persist across different mpv + invocations. Defaults to the calling script name with ``prompt`` + appended. + +``input.terminate()`` + Close the console. + +``input.log(message, style, terminal_style)`` + Add a line to the log buffer. ``style`` can contain additional ASS tags to + apply to ``message``, and ``terminal_style`` can contain escape sequences + that are used when the console is displayed in the terminal. + +``input.log_error(message)`` + Helper to add a line to the log buffer with the same color as the one the + console uses for errors. Useful when the user submits invalid input. + +``input.set_log(log)`` + Replace the entire log buffer. + + ``log`` is a table of strings, or tables with ``text``, ``style`` and + ``terminal_style`` keys. + + Example: + + :: + + input.set_log({ + "regular text", + { + text = "error text", + style = "{\\c&H7a77f2&}", + terminal_style = "\027[31m", + } + }) + Events ------ |