User Guides

Custom Themes

Cantabile supports loading custom themes for the main window. This page describes how to create your own custom theme.

Default Theme File

The default themes provide a good starting point for creating your own theme. These themes were authored using Sketch by Bohemian Coding (requires OS-X). Although you can create themes using any tools you like, Sketch really does work well for this and is highly recommended.

The assets for the default themes are available here.

You'll find two sketch files there: Light.sketch and Dark.sketch. You might also like to examine the theme files that ships with Cantabile. They're in the same folder as Cantabile.exe and have a .theme extension. Rename them to have a .zip file extension to see their contents.

Locating Theme Files

Cantabile locates theme files by looking first in the resource folder and then in the same folder as the Cantabile executable.

Theme File Format

A Cantabile theme consists of:

  1. a set of graphic resources in .png format.
  2. a theme.json file that specifies colors for text and other elements.

Inheriting from a Base Theme

A theme can inherit most of its assets and settings from a base theme. This makes it easy to tweak just a few assets in an existing similar theme.

The base theme is specified in the theme.json file:

{
    "baseTheme": "Dark"
}

The value specified should be the plain theme name and not a file name. Cantabile will search its resource path to find the appropriate theme file. (Be careful to avoid creating a circular inheritance).

By inheriting from one of Cantabile's built-in themes you can save having to update your theme every time a new graphic asset it introduced since the built-in themes will always be able to provide those new assets.

The minimum requirements for a theme are a theme.json file with the name of a base file. Everything else can be inherited from that base theme file including colors and strings in theme.json and graphics resource assets.

Theme inheritance requires build 3500 or later

Graphic Resources

Each graphic resource should be provided in three sizes and conform to the following naming convention:

  • basename.png - the resource at standard 96 DPI resolution
  • basename@2x.png - the resource at double the resolution
  • basename@4x.png - the resource at 4x the resolution

The @2x and @4x resolution images are not strictly necessary but will result in blurred rendering on high resolution monitors or when the main window scaling factor is high. (Sketch can automatically render assets at different resolutions and you'll see the supplied sketch files are configured to do this).

The names of the required resource files can be determined by looking at the slice names in the above sketch files.

If a resource can't be found in the theme, Cantabile will use a red and yellow "flag" image to highlight missing theme assets.

Specifying Text Colors with theme.json

The theme.json file specifies various non-graphic settings related to the theme - mainly text colors. It's format and the contained fields are self explanatory.

Packaging Theme Files

A theme can be either a zip file (renamed to have a .theme file extension) or a folder (also with a .theme extension) containing the above assets.

When packaging theme assets into a zip file compression should not be used.

PNG files are already zip compressed and re-compressing a second time only slows down load times. See the buildzips.bat file in the above mentioned repository for how Cantabile's build process packages themes.