Skip to content

CogentRedTester/mpv-scroll-list

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

47 Commits
 
 
 
 
 
 
 
 

Repository files navigation

mpv-scroll-list

This is an API to allow scripts to create interactive scrollable lists in mpv player.

For Users

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.

For Developers

Importing the Module

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.

Conceptual Overview

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.

Variables

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

Methods

These methods must all be run using object:function() syntax so that they act on the correct list object.

Methods meant to control the list overlay:

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

Methods designed to be replaceable for custom behaviour:

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

Methods to support custom functions:

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

Internally used methods (for reference):

Method Description
update_ass() Main function that runs the format functions and calculates the scroll offsets

The List Array

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 Array

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

Utility Functions

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Languages