Theme Files

The SyntaxArea editor has many customisable properties that let you adjust its look to suit your needs. In addition to colour properties such as CaretColor and BackColor, tokens (which are produced by the syntax highlighting engine and defined in syntax definition files) can also be styled. This can be done manually using the SyntaxArea.Editor.AddToken() method or these can be specified in theme files.

Theme files are specially formatted TOML files that define the colours to use for the editor as well as defining styles for tokens.

Example

Below is a barebones theme that provides style information for the editor and a minimal number of tokens:

# Theme metadata.
name = "Theme Name"
author = "Garry Pettet"
version = "1.0.0"

# Generic tokens.
backColor = "&h00FFFFFF"
textColor = "&h00000000"
textSelectionColor = "&h00A4CCFE"

# Block folding.
blockFoldedColor = "&h00FF8000"
blockFoldedEllipsisColor = "&h00AAAAAA"
blockFoldMarkerColor = "&h00555555"

# Left gutter colours.
gutterBackColor = "&h00FFFFFF"
gutterBorderColor = "&h00000000"
lineNumbersColor = "&h00000000"

# Autocomplete colours.
suggestionPopupBackColor = "&h00FFFFFF"
suggestionPopupSelectedTextColor = "&h00000000"
suggestionPopupTextColor = "&h00000000"

# Miscellaneous.
bookmarkColor = "&h000000FF"
bracketHighlightColor = "&h000000FF"
caretColor = "&h00000000"
dirtyLinesColor = "&h00FFFF00"
invisibleCharacterColor = "&h00BFC5CC"
verticalRulerColor = "&h00AAAAAA"

# The required default style. Used for text that matches no other style.
[defaultStyle]
textColor = "&h00000000"
backColor = "&h00000000"
hasBackColor = false
bold = false
italic = false
underline = false

# ==============================================
# Required styles. All themes must define these.
# ==============================================
[styles.comment]
textColor = "&h00737373"
backColor = "&h00000000"
hasBackColor = false
bold = false
italic = true
underline = false

[styles.directive]
textColor = "&h007C3EA6"
backColor = "&h00000000"
hasBackColor = false
bold = false
italic = false
underline = false

[styles.escape]
textColor = "&h0000ff00"
backColor = "&h00000000"
hasBackColor = false
bold = false
italic = false
underline = false

[styles.identifier]
textColor = "&h00B42F84"
backColor = "&h00000000"
hasBackColor = false
bold = false
italic = false
underline = false

[styles.keyword]
textColor = "&h000061B8"
backColor = "&h00000000"
hasBackColor = false
bold = false
italic = false
underline = false

[styles.lowercaseIdentifier]
textColor = "&h00B42F84"
backColor = "&h00000000"
hasBackColor = false
bold = false
italic = false
underline = false

[styles.number]
textColor = "&h00000000"
backColor = "&h00000000"
hasBackColor = false
bold = false
italic = false
underline = false

[styles.placeholder]
textColor = "&h00FFFFFF"
backColor = "&h003379F7"
hasBackColor = false
bold = true
italic = false
underline = false

[styles.string]
textColor = "&h00BD391D"
backColor = "&h00000000"
hasBackColor = false
bold = false
italic = false
underline = false

[styles.type]
textColor = "&h00000000"
backColor = "&h00000000"
hasBackColor = false
bold = false
italic = false
underline = false

[styles.uppercaseIdentifier]
textColor = "&h0023575A"
backColor = "&h00000000"
hasBackColor = false
bold = false
italic = false
underline = false

[styles.url]
textColor = "&h00000000"
backColor = "&h00000000"
hasBackColor = false
bold = false
italic = false
underline = true

Keys

All themes should consider the below keys as mandatory.

name: The name of the theme as a string.

author: The name of the theme's author as a string.

version: The theme's version as a semantic version string.

defaultStyle: The TokenStyle object (see below) for default text.

invisibleCharacterColor: The colour to use for invisible characters (e.g. spaces, tabs).

styles: An object containing zero or more TokenStyle objects. Each key is the name of the token to which the style belongs. The following styles should be provided by every theme:

• comment
• directive
• escape
• identifier
• keyword
• lowercaseIdentifier
• number
• placeholder
• string
• type
• uppercaseIdentifier
• url

backColor: The editor's background colour.

blockFoldedColor: The colour of the triangular icon in the gutter used to indicate a folded block.

blockFoldedEllipsisColor: The colour of the ellipsis shown within a folded block.

blockFoldMarkerColor: The colour of the triangular opening and closing block markers in the gutter.

bookmarkColor: The colour of the bookmark icon that appears in the gutter.

bracketHighlightColor: The colour used when highlighting matching brackets.

caretColor: The colour of the caret (insertion point).

dirtyLinesColor: The colour to use for the icon in the gutter that indicates a line is dirty.

gutterBackColor: The background colour of the line number gutter.

gutterBorderColor: The border colour of the line number gutter.

invisibleCharacterColor: The colour of invisible characters (when displayed)

lineNumbersColor: The colour of the line numbers.

suggestionPopupBackColor: The background colour of the autocompletion suggestion window.

suggestionPopupSelectedTextColor: The colour of the text of the currently selection option in the autocompletion suggestion window.

suggestionPopupTextColor: The colour of text in the autocompletion suggestion window.

textColor: The default text colour.

textSelectionColor: The colour to use when selecting text.

verticalRulerColor: The colour to use for the optional vertical ruler.

Colour keys

Where a key expects a colour in the form of a string it should be formatted as:

"&hAARRGGBB"

Where:
AA: Alpha component (hex)
RR: Red component (hex)
GG: Green component (hex)
BB: Blue component (hex)

TokenStyle objects

The defaultStyle key and the subtables within the styles object expect TokenStyle TOML objects. A TokenStyle object defines the visual style of a token in the editor and has the following structure:

{
textColor = "&h00000000"
backColor = "&h00000000"
hasBackColor = false
bold = false
italic = false
underline = false
}

The structure is fairly self explanatory. The only slightly unexpected requirement is that you must specify a backColor even if the token will not have a background colour. The hasBackColor key specifies if the token should use the background colour specified by the backColor key.