Custom Windows

On macOS Yosemite and later, RetroPlayer allows the user to create custom windows using HTML, CSS and JavaScript. These windows can then be accessed through the Window menu. It is also possible to configure RetroPlayer to use a custom window as the mini player. In fact both the default mini player and the Intuitracker window are implemented using this technology, so anything these windows do, a custom window can do. Their implementation can be inspected by performing Show Package Contents on RetroPlayer in Finder and then navigate to Contents/Resources/Windows.

Creating a custom window

A custom window is created by creating a folder in Music/RetroPlayer/Windows with a file called window.html. The name of the folder will be used as the name of the window and will be visible in the Window menu. The folder may also contain additional resources like CSS and JavaScript files that are loaded by window.html.

RetroPlayer provides the RetroPlayer API that can be used from JavaScript to both control RetroPlayer and access information.

An example implementation based on the default mini player is available.

Download Example

Options

There are no common options for all custom windows but it is possible to provide an options.json file for adding custom options to the View Options panel.

The View Options panel will show the options for the window that currently is the main window.

Window styling

RetroPlayer uses the computed style for the HTML element to set the style of the window. Most of the style properties works just as in a web browser but there are some subtle differences for properties that affect the window itself.

The affected CSS properties are:

width and height. These properties specifies the width and height of the window.
max-width and max-height. These properties specifies the maximum width and height of the window. If these are not set, width and height will be used as the maximum values.
min-width and min-height. These properties specifies the minimum width and height of the window. If these are not set, width and height will be used as the minimum values.
border-top-left-radius. This property normally only specifies radius of the rounded top left corner of an element box but for a window, it will be used for all four window corners.

The initial value of these style properties are automatically applied but to apply any changes after the window has been loaded, the custom window implementation must call RetroPlayer.setWindowStyle().

To change the window size a custom window implementation usually uses either RetroPlayer.setWindowContentSize() or RetroPlayer.adjustWindowSizeToContent().