Theme editor

AlephNote can be styled with theme files, all these theme files are located in the folder "themes".
This is a short introduction to creating themes. For more questions you can directly contact me.

Introduction

First there is the "default.xml" file. This is the base theme file and should never be changed. All other themes use this file as the base and just modify some of the values.
The themes are under the hood plain key-value stores, they reference a bunch of identifier that correspond to different properties of the UI and they override the values for these properties (most of the time colors, brushes, margins or simple numerical values).

Folder structure

All themes must be placed in the /themes/ sub folder and must have the extension xml.
The current consensus is to write the filename in lowercase and without spaces.

File structure

The theme files are XML files grouped into 3 parts:

Part 1 <meta> contains a few meta information about the theme (author, name, version ...). You can also specify here with which version of AlephNote this theme works, the syntax is explained later
Part 2 <ref> here you can specify "constants". These valuerefs cannot be changed later and can only be used in this specific file (you reference them with an @)
Part 3 <data> is the meat of the theme. Here you specify the properties you want to change. Because default.xml is the master file it needs to have all available properties and you can simply look at it to see the possible property names. You can group stuff under <data> into groups (and sub-groups), this does not have any effect other than a more organized file, while parsing all tags <group> are ignored and flattened out.

A minimal file might look like this:

<?xml version="1.0" encoding="UTF-8"?>
<theme>
  <meta>
    <name>Example</name>
    <version>1.0</version>
    <compatibility>*</compatibility>
    <author>Nobody</author>
  </meta>

  <ref>
    <valueref key="Transparent" type="color">#00000000</valueref>
    <valueref key="Black"       type="color">#000000</valueref>
    <valueref key="White"       type="color">#FFFFFF</valueref>
  </ref>

  <data>
      <property name="scintilla.background" value="@Black"/>
      <property name="scintilla.default:foreground" value="@White"/>
  </data>
</theme>

Syntax version numbers

The version range syntax is the same that node.js uses. You can, for example specify:

* Any version (not recommended)
1.x.x Any version that starts with 1
1.6.0 The specific version 1.6.0
1.6.0-1.7.0 All versions between 1.6.0 and 1.7.0
~1.6.3 All versions that start with 1.6 and that are greater-or-equal 1.6.3
^1.6.0 All versions that start with 1 and that are greater-or-equal 1.6

Syntax Properties

Under the <data> tag you specify the properties you want to change.
The attribute name is here the property key you want to change, you can find this key either by looking at existing themes, at the default.xml (this one contains all properties) or by looking in the source code.
The attribute value is the new value for this property, depending of the type of the property you can write different values:

Write numerical integer values by writing the number, e.g. value="1"
Write numerical float values by writing the number with a decimal point, e.g. value="1.5"
Write color values by writing the Hex color code together with a pound sign, e.g. value="#FFC355"
You can also write short color codes, e.g. value="#F35" which is equal to value="#FF3355"
You can also write full color codes (with alpha channel), e.g. value="#FFC35580" which has 50% alpha
Write margins/padding/thickness values by specifying the thickness of the four sides (Left, Top, Right, Bottom), e.g. value="1,4,1,4"
You can also write thickness by combining the horizontal and vertical elements, e.g. value="1,4" which is equal to value="1,4,1,4"
You can also write thickness by combining all four elements, e.g. value="1" which is equal to value="1,1,1,1"
Write complex vertical gradients as a list of colors and percentage values (this means at position=0 it has color-A, at position=0.5 color-B and at position=1.0 color-C). E.g.: gradient-v://0.25:#FFF6F6F6|0.25:#FFEAE8E8|0.80:#FFDCD9D9|1.00:#FFFFFFFF. Always specify start-color (position=0.0) and end-color (position=1.0)
There are also horizontal gradients with the same syntax (except gradient-h)

Syntax valuerefs

All the above notations are also valid in the valueref section. In this section are constants defined that can be re-used in different parts of the file. If you want a property to reference a valueref write the valueref key with an @ suffix:

<ref>
  <valueref key="Black" type="color">#000000</valueref>
</ref>
<data>
  <property name="scintilla.background" value="@Black"/>
</data>

Valuerefs are only valid in the same file as they are declared and cannot contain more complex values (eg references to other valuerefs)

Syntax property indirection

The probably most important feature are property references.
You can assign one property the value of another one by writing the other property name with an $ suffix.

<property name="tageditor.foreground" value="$window.foreground"/>
<!-- The tageditor now has the same foreground as the window -->

While <valuerefs> are resolved eager (= as soon as possible), indirect properties are resolved lazy (= as late as possible).
In practice this means if in the "default.xml" the property tageditor.foreground is indirect set to the property of window.foreground you only need to change window.foreground in your theme file (remember you theme file is using default.xml as master and only overriding the already existing theme) to change both properties in effect.

This has multiple useful effects. First you only need to change a few select properties in your theme file and a lot of subsidiary properties will be adjusted automatically. But this system also gives you a tiny bit of safety against future changes. If a new version of AlephNote adds a new control (and so new theme properties) there is a good chance that their values will be indirect references to other properties that are already adjusted in your theme file, and so the new control will look correct (or almost correct) without theme changes.

A few important points:

All theme files use default.xml as base and only override some properties of it
Indirection is late resolved and this way not file-based. The specified indirections in default.xml are still valid in your new theme file
Indirection can hop over multiple (max 4) properties but obviously not in cycles

The theme editor

Attention
The theme editor is currently in beta-status and not fully finished

There is an interactive theme editor in AlephNote where you can simply write the xml and see the changes live.
Its a simple editor for the theme files and (unfortunately) you still need to understand the basic concepts detailed above.

First you need to start AlephNote.exe with the parameter --debug. Then you should get a new menu entry Debug with a sub-entry Show interactive editor

Clicking it opens the interactive theme editor:

In the top left corner you can select a theme [1], or create a new one [2].

After you selected your theme you can see on the right side [3] the XML content of the theme file, here you can edit your theme (syntax-highlighting is inclusive).

On the left side [4] is a list of all available properties, their default value and their value under your theme. If the value in your theme is unchanged they are grayed out a little bit.

The most interesting feature of the theme editor is the preview function [5]. By clicking on Preview you apply your current theme to AlephNote and can directly look at it.
If there are any problems/errors in the theme file they will be displayed in the output box [6].

Changes need to be written to disk with the Save or they will be lost once the editor is closed

Notes

If you find bugs in the themes, the theme editor, if you miss some properties or if you need help with anything other you can create an issue on github.

Also if you make a theme I would (probably) really like to add it to the default themes, just open an issue/pull-request and I will add it.