Custom Options

Custom options lets custom windows and visualizers to add their own options to the View Options and Visualizer Options panels respectively. Each option is mapped to a key in the user defaults database for the custom window or visualizer so that they can use RetroPlayer.getUserDefault() to get the option value.

Custom windows and visualizers must provide an options.json file describing the options and their user interface elements.

Note: The value set by custom options in the user defaults database will always be string values.

File format

The options.json file is JSON file with a an array at the root level. This array contains objects describing each option.

Option object

• "key" is the key the option value will be set for in the user defaults database.
• "title" is the title for the option and will be used for a label in the user interface.
• "defaultValue" is the default value that will be used if there is no value set for the key in the user defaults database.
• "control" is a Control] object that configures the control used in the user interface.

{
    "key"   : "backgroundColor",
    "title" : { "en" : "Background color:",
                "nb" : "Bakgrunnsfarge:" }
    "defaultValue" : "#555555ff",
    "control"      : { "type" : "colorwell" }
}

Control object

The type of control is specified by the "type" key and the supported types are:

• "checkbox"
• "colorwell"
• "popupbutton"
• "slider"

The checkbox control

The checkbox control is a standard checkbox that will set the value to "true" or "false".

"control" : { "type" : "checkbox" }

The colorwell control

The colorwell control is a control for selecting a color. The value will be a string with the color specified using CSS 8-digit hex codes, e.g. "#ff0000ff" for red, so that it can be used to set the color of HTML elements directly.

"control" : { "type" : "colorwell" }

The popupbutton control

The popupbutton control allows the user to select an item from a list of items. The list items is specified with the items key and each item is an object with two keys.

• "title" is the title of the item and will be displayed in the list of items.
• "value" is the value of the item and is the value that will be set in the user defaults database if the item is selected.

"control" : { "type"  : "popUpButton",
              "items" : [ { "title" : { "en" : "System",
                                        "nb" : "System" },
                            "value" : "" },
                          { "title" : { "en" : "Light",
                                        "nb" : "Lyst" },
                            "value" : "NSAppearanceNameAqua" },
                          { "title" : { "en" : "Dark",
                                        "nb" : "Mørkt" },
                            "value" : "NSAppearanceNameDarkAqua" } ] }

The slider control

The slider controls allows the user to select a number in a range. The range is specified with the "maxValue" and "minValue" keys.

"control" : { "type"     : "slider",
              "minValue" : "1",
              "maxValue" : "10" }

Note: Strings are used for all values even when working with numbers.

Titles

Titles can be just a string but to support localization titles can also be objects where language identifiers are keys and the localized strings are values. The language identifier is according to ISO 639–1, e.g. "en" for English and "nb" for Norwegian bokmål.

"title" : { "en" : "Background color:",
            "nb" : "Bakgrunnsfarge:" }

If no localized string are set for a language, RetroPlayer will then look for an English string before falling back to just the first localized string.