{"id":13835500,"url":"https://github.com/CogentRedTester/mpv-scroll-list","last_synced_at":"2025-07-10T07:32:22.543Z","repository":{"id":40754515,"uuid":"305092446","full_name":"CogentRedTester/mpv-scroll-list","owner":"CogentRedTester","description":null,"archived":false,"fork":false,"pushed_at":"2025-01-10T06:39:46.000Z","size":38,"stargazers_count":41,"open_issues_count":2,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T20:11:15.357Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CogentRedTester.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-18T12:05:35.000Z","updated_at":"2025-01-10T06:39:49.000Z","dependencies_parsed_at":"2023-02-10T03:00:31.018Z","dependency_job_id":null,"html_url":"https://github.com/CogentRedTester/mpv-scroll-list","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CogentRedTester/mpv-scroll-list","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogentRedTester%2Fmpv-scroll-list","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogentRedTester%2Fmpv-scroll-list/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogentRedTester%2Fmpv-scroll-list/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogentRedTester%2Fmpv-scroll-list/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CogentRedTester","download_url":"https://codeload.github.com/CogentRedTester/mpv-scroll-list/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogentRedTester%2Fmpv-scroll-list/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264545168,"owners_count":23625404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T14:01:03.586Z","updated_at":"2025-07-10T07:32:22.245Z","avatar_url":"https://github.com/CogentRedTester.png","language":"Lua","funding_links":[],"categories":["Library"],"sub_categories":[],"readme":"# mpv-scroll-list\n\nThis is an API to allow scripts to create interactive scrollable lists in mpv player.\n\n## For Users\nInstalling 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).\n\nFor more advanced users you can also place the file into one of the lua package directories specified by the `LUA_PATH` environment variable.\n\n## For Developers\n\n### Importing the Module\nImporting the module in such a way as to respect the above settings can be done with the following code:\n\n```\npackage.path = mp.command_native({\"expand-path\", \"~~/script-modules/?.lua;\"})..package.path\nlocal list = require \"scroll-list\"\n```\n\nThe list variable then contains a table that represents a single scroll-list object.\n\n### Conceptual Overview\nEach list object maintains a separate osd ass overlay, and has a suite of variables and methods to modify and control the overlay.\nWhen 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.\nForced keybindings are then set to allow the user to control the selection, and hence scroll up or down.\nWhen the `close` method is run the keybinds are removed, and the osd hidden.\nBasic 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.\n\n### Variables\n\nThe following variables are provided to modify the behaviour of the list.\n\n| Variable       | Description                                           | Default                                                     |\n|----------------|-------------------------------------------------------|-------------------------------------------------------------|\n| global_style   | An ass string prepended to the start of the overlay   | empty\n| header         | The string to print as the header                     | `header \\\\N ----------------------------------------------` |\n| header_style   | The ass tag used to format the header                 | `{\\q2\\fs35\\c\u002600ccff\u0026}`                                      |\n| list           | Array of item objects                                 | empty                                                       |\n| list_style     | Generic ass tag to apply to all list items            | `{\\q2\\fs25\\c\u0026Hffffff\u0026}`                                     |\n| wrapper_style  | Ass tag for the 'x item(s) remaining' text            | `{\\c\u002600ccff\u0026\\fs16}`                                         |\n| cursor         | String to print before the selected item              | `➤\\h`                                                       |\n| indent         | String to print before non-selected items             | `\\h\\h\\h\\h`                                                  |\n| cursor_style   | Ass tag for the cursor                                | `{\\c\u002600ccff\u0026}`                                              |\n| selected_style | Ass tag to use after the cursor                       | `{\\c\u0026Hfce788\u0026}`                                             |\n| num_entries    | Number of items to display on screen before scrolling | 16                                                          |\n| selected       | Currently selected item                               |                                                             |\n| wrap           | Whether scrolling should wrap around the list         | false                                                       |\n| empty_text     | Text to print when list is empty                      | `no entries`                                                |\n| keybinds       | Array of keybind objects to use when the list is open | See [Keybinds entry](#The-Keybinds-Array)                   |\n\nThere 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.\n\n| Variable    | Description                                                        |\n|-------------|--------------------------------------------------------------------|\n| ass         | Contains the object returned by `mp.create_osd_overlay`            |\n| hidden      | Used to track if the list is closed in order to defer redraws      |\n| flag_update | Used to track if an update was requested while the list was closed |\n\n\n### Methods\nThese methods must all be run using `object:function()` syntax so that they act on the correct list object.\n\n#### Methods meant to control the list overlay:\n\n| Method          | Description                                 |\n|---------------  |---------------------------------------------|\n| open()          | opens the list                              |\n| close()         | closes the list                             |\n| toggle()        | toggles the list                            |\n| update()        | re-scan the list and update the osd overlay |\n| scroll_down()   | move cursor down                            |\n| scroll_up()     | move cursor up                              |\n| move_pagedown() | move cursor to next page                    |\n| move_pagedup()  | move cursor to previous page                |\n| move_begin()    | move cursor to begin                        |\n| move_end()      | move cursor to end                          |\n\n#### Methods designed to be replaceable for custom behaviour:\nChanging these can break the script if certain function calls are missing. Make sure to check the defaults.\n\n| Method                   | Description                                                  |\n| ------------------------ | ------------------------------------------------------------ |\n| format_header_string()   | format and return the header string - allows one to modify or substitute the header string on each redraw |\n| format_header()          | formats and prints the header to the overlay                 |\n| format_line(index, item) | formats the ass string for the given `item` at list position `index` - this handles the cursor, indents, styles and newlines. |\n| open()                   | is called by `toggle` - runs the functions required when opening the list |\n| close()                  | is called by `toggle` - runs the functions required when closing the list |\n\n#### Methods to support custom functions:\n\nGenerally these shouldn't be changed.\n\n| Method            | Description                                                                        |\n|-------------------|------------------------------------------------------------------------------------|\n| append(str)       | appends the string `str` to the ass overlay - if text is nil then it safely exits  |\n| newline()         | alias for `append(\"\\\\N\")`                                                          |\n| add_keybinds()    | adds the keybinds defined in the `keybinds` variable - used by `open`              |\n| remove_keybinds() | removes the defined keybinds - used by `close`                                     |\n| open_list()       | sends the ass update command and manages the hidden flag - used by `open`          |\n| close_list()      | sends the ass remove command and manages the hidden flag - used by `close`         |\n\n#### Internally used methods (for reference):\n\n| Method       | Description                                                                    |\n|--------------|--------------------------------------------------------------------------------|\n| update_ass() | Main function that runs the format functions and calculates the scroll offsets |\n\n### The List Array\n\nEach item in the list array is a table with the following values:\n| key   | Description                                                                                                      |\n|-------|------------------------------------------------------------------------------------------------------------------|\n| ass   | the ass string to print to the screen                                                                            |\n| style | Optional - an ass string to prepend before `ass` - this is to provide an easier way to add/remove a custom style |\n\nAny other key is ignored, so can be used by a script if it needs to store more information.\nNote that it is possible that future versions of the script may add functionality for other keys.\n\n### The Keybinds Array\n\nThe `keybinds` variable is an array of keybinds that the script applies when the script is open.\nEach keybind is itself an array consisting of:\n\n    key     a string describing the key to bind to - same as input.conf\n    name    a unique name for this binding\n    fn      a function to run when the key is pressed\n    flags   a table of flags (can be an empty table)\n\nThese are passed almost directly to the `mp.add_forced_key_binding` function.\nFor details on flags see [mp.add_key_binding](https://mpv.io/manual/master/#lua-scripting-[,flags]])\n\n\n### Utility Functions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCogentRedTester%2Fmpv-scroll-list","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCogentRedTester%2Fmpv-scroll-list","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCogentRedTester%2Fmpv-scroll-list/lists"}