diff options
Diffstat (limited to 'DOCS/man/lua.rst')
| -rw-r--r-- | DOCS/man/lua.rst | 105 |
1 files changed, 97 insertions, 8 deletions
diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index 5708e19..7377696 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -308,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. @@ -426,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. @@ -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 ------ |