Writing themes

A Howl theme decides how the whole window looks: the colors and borders of the window and the boxes within it, the styles used for the text in the editors, and the flairs drawn on top of the text, such as the cursor, the selection and search highlights. A theme is a single CSS file, optionally accompanied by images, that is registered with Howl by a bundle. In this page we’ll go through how to write one, how to check it for mistakes, and how to contribute it to Howl.

Checking a theme for mistakes is done with a script from the Howl source, so you’ll want a checkout of the Howl repository at hand (see Howl development).

Getting started

The easiest way to get started is to copy one of the bundled themes and change it from there. The bundled themes live in the bundles/howl-themes directory of the Howl source, one directory per theme; the Monokai theme (bundles/howl-themes/monokai/monokai.css) is the shortest one.

Themes are registered by bundles, so your theme needs a bundle of its own. Your own bundles go in the bundles directory of your Howl user directory (~/.howl/ or ~/.config/howl/, see Init files). Create a directory for the bundle, named so that it doesn’t clash with any other bundle, and put your CSS file in it:

~/.howl/bundles/my-theme/
├── init.moon
└── my-theme.css

The bundle’s init.moon registers the theme, and unregisters it again when the bundle is unloaded:

{:theme} = howl.ui

theme.register 'My Theme', bundle_file('my-theme.css')

{
  info: {
    author: 'Your Name',
    description: 'My own theme',
    license: 'MIT',
  },
  unload: -> theme.unregister 'My Theme'
}

bundle_file resolves a path relative to the bundle’s directory, and all bundles must return the info fields and the unload function shown above. Once you restart Howl, the theme shows up among the others when you set the theme configuration variable (see Configuring Howl).

When you change the CSS file while the theme is in use, run the bundle-reload command and select your bundle (my_theme in this case). This registers the theme anew, which re-applies it with your changes. Setting the theme variable to the theme already in use does not re-read the file.

What’s in a theme file

A theme file is Gtk CSS, which styles the window and the widgets in it, plus a few extensions of Howl’s own. Howl processes these before handing the rest over to Gtk:

• Variables, declared in a :root block and used with var(..). Howl expands them itself, so they work anywhere in the file, including in style and flair rules. A variable’s value may refer to another variable.
• theme-url('file.png'), which refers to a file relative to the theme’s CSS file. Use it for background images and the like.
• Style rules, style.<name> { .. }, which set the text styles used in the editors (see Text styles).
• Flair rules, flair.<name> { .. }, which set how the cursor, selection, highlights, etc. are drawn (see Flairs).

Comments (/* .. */) can go anywhere. A small but complete theme looks like this:

:root {
  --background: #1d1f21;
  --foreground: #c5c8c6;
  --comment: #969896;
  --purple: #b294bb;
  --green: #b5bd68;
}

/* The window, and the boxes holding the editors and the command line */
window {
  background-color: var(--background);
}

.content-box {
  background-color: var(--background);
}

.gutter {
  color: var(--comment);
}

/* Text styles */
style.default {
  color: var(--foreground);
}

style.comment {
  color: var(--comment);
  font-style: italic;
}

style.keyword {
  color: var(--purple);
  font-weight: bold;
}

style.string { color: var(--green); }

/* Flairs */
flair.cursor {
  shape: pipe;
  border-color: var(--foreground);
  width: 2;
  height: text;
}

flair.selection {
  shape: rounded-rectangle;
  background-color: alpha(var(--purple), 0.3);
  minimum-width: letter;
}

Using a variable that isn’t declared is an error that stops the whole theme from being applied, while other mistakes only affect the rule they’re in (see Checking a theme).

Styling the window

Everything outside of the text itself is styled with ordinary Gtk CSS, using the properties Gtk supports. These are the selectors for Howl’s parts of the window:

The background of an editor is that of its .content-box. The font family and size come from the font and font_size configuration variables, so themes shouldn’t set them for the window. Howl draws the line numbers in the gutter itself, using the color of the .gutter rule.

Text styles

A style rule sets the look of one kind of text, such as comments, keywords or strings. The selector must be a single style.<name>: grouped selectors, such as style.keyword, style.string, and any other combination are ignored. Dashes and underscores in names mean the same thing, so style.type-def and style.type_def are the same style. Several rules for the same style are combined.

These properties are supported:

style.default is the base for all other styles: whatever a style doesn’t set is taken from style.default. A style that the theme doesn’t define is shown as the style it defaults to, if it has one, and as style.default otherwise. A theme therefore only needs to define the styles it wants to differ.

Below are all the styles used by Howl and its bundled modes, along with the style each one defaults to. The names are given as Howl’s code uses them, with underscores, but in a theme you can just as well write them with dashes, as the bundled themes do (style.type-def). The bundled themes define all of the code, document and diff styles except identifier, symbol, parameter, global and header, so they are a good place to start from.

Code

Embedded code is shown with its own styles on top of embedded, so a background-color set for embedded shows behind all embedded code.

Documents

These are used for Markdown, mail and Cucumber files, and for the documentation Howl shows in popups.

Diffs

The user interface

Language specific styles

Some modes use styles of their own. All of them default to one of the styles above, except ANTLR’s action, which is plain text unless the theme defines it.

Flairs

Flairs are drawn on top of, or below, the text in the editors: the cursor, the selection, the current line, search matches, and so on. Like styles, a flair rule takes a single flair.<name> selector, and dashes and underscores in names are the same. A flair defined by the theme replaces Howl’s own definition entirely, so a flair rule has to set everything the flair needs.

Every flair needs a shape, which is one of:

A flair without a valid shape is ignored. The other properties are:

These are the flairs Howl uses:

Howl has built-in definitions for most of these. brace-highlight, brace-highlight-secondary, replace-strikeout and list-highlight have none, and are only visible if the theme defines them.

Checking a theme

Mistakes in style and flair rules, such as an unknown property or an invalid value, are logged as Theme error: when the theme is applied, as are the CSS errors Gtk reports. The rest of the theme still applies. Within Howl, you can see the messages with the open-journal command.

It’s easier to use the howl-check-themes script in the bin/ directory of the Howl source, which applies themes without opening a window and lists the errors for each theme. Give it a theme file:

[howl-dir] $ ./bin/howl-check-themes ~/.howl/bundles/my-theme/my-theme.css
FAIL  /home/you/.howl/bundles/my-theme/my-theme.css
      unsupported selector 'style.keyword, style.string', ignoring the rule: style and flair rules take a single name
      style.comment: text colors can't be transparent ('alpha(#969896, 0.5)')
      style.comment: invalid font-weight '700'
      flair.cursor: no valid shape, ignoring it

A theme without mistakes is listed as ok, and the script exits with a non-zero status if any theme had errors. Gtk’s errors are shown along with the CSS surrounding them, where <ERROR> marks the spot. You can also give it the name of a theme; with --profile it loads your user directory, so that themes from your own bundles are included. Without arguments it checks all of the bundled themes:

[howl-dir] $ ./bin/howl-check-themes --profile 'My Theme'
[howl-dir] $ ./bin/howl-check-themes

A theme without errors can of course still look wrong, so switch to it and see for yourself.

Contributing a theme to Howl

To add a theme to the themes bundled with Howl, add a directory for it under bundles/howl-themes/ and register it in the list of themes in bundles/howl-themes/init.moon. Credits and copyright notes, e.g. for a theme based on another, go in bundles/howl-themes/README.md. The bundle’s spec applies every bundled theme and fails on any error, so make sure it passes:

[howl-dir] $ ./bin/howl-spec bundles/howl-themes/spec

The website has screenshots of every bundled theme, taken by the screen-shooter script. It’s also a quick way to see a bundled theme in use; this takes a screenshot with a few different views open, and writes it to /tmp/shots/my-theme/:

[howl-dir] $ ./bin/screen-shooter /tmp/shots 'My Theme' multi-views

To add the theme to the site, generate all of its screenshots into site/source/images/screenshots by leaving out the last argument, and add the theme to the list of screenshot pages in site/config.rb.

.. Back to the documentation index.