Custom Themes

This feature addresses the concern that the built-in themes will not always be appealing or appropriate for all users, and that users should be able to adjust the colors and styles that matterhorn uses to get the best experience.

Current Behaviors to Maintain

To minimize surprising upgrade behavior and to keep existing configurations valid:

• Continue to support the special builtin: theme names.
• Continue to default to the built-in dark theme.

Upgrade Path

• Users upgrading to this feature will initially get to just keep their configuration theme setting that is either absent (defaulting to a built-in theme) or present (already referencing a built-in theme).

• Later, users having upgraded to using a custom theme will eventually further upgrade to a version of Matterhorn that introduces new attributes into its UI, and old theme files will lack those attributes. It'd be nice if all themes were fully specified, but that's not realistic because of this case. It'd also be nice if customizing a theme could be done by changing only the parts you don't like and leaving the rest to default. The approach I'm taking here is to let the user customize a theme. To do this the user specifies both the base theme (using the current theme option) and a customization file. The customization file's settings then override the base theme.

Features

Roughly in order of implementation:

• (done) Refactor internal theme representation to require each theme attribute name to also include documentation on which part of the UI it affects. The concern here is that we'll need to communicate this to users who want to make their own themes, and we have to document it somewhere. If we document it in the code, that ensures we'll never forget to do it and it enables us to include the documentation in generated theme files (see below).

• (done) Document the theme attributes.

• (done) Also ensure that themes can specify attributes for Skylighting-driven syntax highlighting.

• (done) Also ensure that themes can specify attributes for indexed username attributes that are used for hash-based username highlighting.

• (done) Update brick with data types, parsers, and serializers for a human-readable string representation of Vty colors and styles to be used in theme files. E.g., someElement.fg = blue, someElement.bg = black, someElement.style = bold, someElement.style = [bold, underline].

• (done) Write a routine to convert the parsed theme representation to a brick attribute map.

• (done) Support loading themes from disk files in INI-file format. To do this, we look at a new themeCustomizationFile configuration option. If it is not an absolute path, treat it as a path relative to the location of the configuration file. This allows users to put themes in their Matterhorn configuration directories without having to specify absolute paths, making the theme files relocatable. When we load these customizations, they are applied to the theme named by the theme option.

• Upgrade to the bidirectional API of config-ini to support reading and then re-writing theme files.

• Support creating theme disk files from the application's current theme configuration via a new command, /save-theme <filename>. Include in saved themes the documentation for each theme attribute as described above (as per-field INI file comments). This allows users to build new themes based on existing ones without needing to 1) find an existing theme disk file (as in the case of a built-in theme) or 2) write it by hand. This command might write theme files so that only the fallback theme is specified, and with all fields commented out, so that it's clear what has been customized.

• Support loading themes at runtime with the existing command, /theme <theme name>, where the parameter is then able to be either a built-in theme name or a filename.

• Stretch goal: add an interactive theme customization UI in which the user can choose a theme attribute, read its description, and change its colors and style.