Adding upstream version 0.38.0.upstream/0.38.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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
 ------