This is an API to allow scripts to create interactive scrollable lists in mpv player.
Installing the script as a user is very simple, just place the scroll-list.lua file inside the ~~/script-modules folder (you may need to make it).
For more advanced users you can also place the file into one of the lua package directories specified by the LUA_PATH environment variable.
Importing the module in such a way as to respect the above settings can be done with the following code:
package.path = mp.command_native({"expand-path", "~~/script-modules/?.lua;"})..package.path
local list = require "scroll-list"
The list variable then contains a table that represents a single scroll-list object.
Each list object maintains a separate osd ass overlay, and has a suite of variables and methods to modify and control the overlay.
When the open method is run the list creates a header and then iterates through the list of items and creates a formatted ass string using the item objects.
Forced keybindings are then set to allow the user to control the selection, and hence scroll up or down.
When the close method is run the keybinds are removed, and the osd hidden.
Basic scripts can create a full scrollable list by simply constructing an array of valid item objects and running the open, close, and toggle methods, but generally one will want to change the settings and modify the keybindings to actually provide the list with functionality beyond scrolling.
The following variables are provided to modify the behaviour of the list.
| Variable | Description | Default |
|---|---|---|
| global_style | An ass string prepended to the start of the overlay | empty |
| header | The string to print as the header | header \\N ---------------------------------------------- |
| header_style | The ass tag used to format the header | {\q2\fs35\c&00ccff&} |
| list | Array of item objects | empty |
| list_style | Generic ass tag to apply to all list items | {\q2\fs25\c&Hffffff&} |
| wrapper_style | Ass tag for the 'x item(s) remaining' text | {\c&00ccff&\fs16} |
| cursor | String to print before the selected item | ➤\h |
| indent | String to print before non-selected items | \h\h\h\h |
| cursor_style | Ass tag for the cursor | {\c&00ccff&} |
| selected_style | Ass tag to use after the cursor | {\c&Hfce788&} |
| num_entries | Number of items to display on screen before scrolling | 16 |
| selected | Currently selected item | |
| wrap | Whether scrolling should wrap around the list | false |
| empty_text | Text to print when list is empty | no entries |
| keybinds | Array of keybind objects to use when the list is open | See Keybinds entry |
There are also a small number of variables that are intended for internal use by the list, however they may be useful if one want to write custom functions.
| Variable | Description |
|---|---|
| ass | Contains the object returned by mp.create_osd_overlay |
| hidden | Used to track if the list is closed in order to defer redraws |
| flag_update | Used to track if an update was requested while the list was closed |
These methods must all be run using object:function() syntax so that they act on the correct list object.
| Method | Description |
|---|---|
| open() | opens the list |
| close() | closes the list |
| toggle() | toggles the list |
| update() | re-scan the list and update the osd overlay |
| scroll_down() | move cursor down |
| scroll_up() | move cursor up |
| move_pagedown() | move cursor to next page |
| move_pagedup() | move cursor to previous page |
| move_begin() | move cursor to begin |
| move_end() | move cursor to end |
Changing these can break the script if certain function calls are missing. Make sure to check the defaults.
| Method | Description |
|---|---|
| format_header_string() | format and return the header string - allows one to modify or substitute the header string on each redraw |
| format_header() | formats and prints the header to the overlay |
| format_line(index, item) | formats the ass string for the given item at list position index - this handles the cursor, indents, styles and newlines. |
| open() | is called by toggle - runs the functions required when opening the list |
| close() | is called by toggle - runs the functions required when closing the list |
Generally these shouldn't be changed.
| Method | Description |
|---|---|
| append(str) | appends the string str to the ass overlay - if text is nil then it safely exits |
| newline() | alias for append("\\N") |
| add_keybinds() | adds the keybinds defined in the keybinds variable - used by open |
| remove_keybinds() | removes the defined keybinds - used by close |
| open_list() | sends the ass update command and manages the hidden flag - used by open |
| close_list() | sends the ass remove command and manages the hidden flag - used by close |
| Method | Description |
|---|---|
| update_ass() | Main function that runs the format functions and calculates the scroll offsets |
Each item in the list array is a table with the following values:
| key | Description |
|---|---|
| ass | the ass string to print to the screen |
| style | Optional - an ass string to prepend before ass - this is to provide an easier way to add/remove a custom style |
Any other key is ignored, so can be used by a script if it needs to store more information. Note that it is possible that future versions of the script may add functionality for other keys.
The keybinds variable is an array of keybinds that the script applies when the script is open.
Each keybind is itself an array consisting of:
key a string describing the key to bind to - same as input.conf
name a unique name for this binding
fn a function to run when the key is pressed
flags a table of flags (can be an empty table)
These are passed almost directly to the mp.add_forced_key_binding function.
For details on flags see mp.add_key_binding