libgedit-gtksourceview :: Style scheme file format

Introduction

This page describes how to create or modify style scheme files.

It's an XML file format

A style scheme file is written in XML.

The file needs to have the .xml extension. For example: classic.xml

The first line needs to be:

<?xml version="1.0" encoding="UTF-8"?>

The top-level element: <style-scheme>

A style scheme file has only one top-level element: <style-scheme>

Example:

<style-scheme id="classic" _name="Classic" kind="light">
  <!-- ... -->
</style-scheme>

The <style-scheme> tag supports the following attributes:

id (mandatory): Identifier for the style scheme. Once all style schemes are loaded by the library, each style scheme has a unique id. During the loading, if two or more style schemes have the same id, only one is kept (the one with the highest priority, depending on the order in which the files are loaded).
name (mandatory): Name of the style scheme. This is the name of the scheme to display to the user, e.g. in a preferences dialog.
_name: This is the same as the name attribute, except that it will be translated. name and _name may not be used simultaneously.
kind (mandatory): The kind of style scheme. It accepts only two possible values: "light" or "dark".

Possible elements inside <style-scheme>

The style-scheme element may contain the following elements: description, _description, color and style.

<description> or <_description> (optional)

Description of the style scheme. The <description> value is not translated, while <_description> is. It is an optional tag. If present, only one description must be set. Example:

<_description>Classic color scheme</_description>

Color values

When a color value is needed inside a <color> tag, it needs to be a "final" color value (see below).

When a color value is needed inside a <style> tag, it can either be a "final" color value, or a reference to a <color> tag.

Final color values

All "final" color values must begin with #. Examples:

An hexadecimal color specification like: #000000
A RGBA color (with an alpha field for transparency) like: #rgba(255,0,0,0.5)
A named color understood by GDK like: #beige

See the documentation of the gdk_rgba_parse() function (part of the GDK library) for more information. Note that the # must be prefixed if it's not already the case.

Referring to a <color> tag

We refer to a <color> tag by its name. Example:

<color name="aluminium1" value="#eeeeec"/>
<style name="line-numbers" background="aluminium1"/>

The order is important: a <color> tag must be located before any reference to it (a “define-before-use” rule).

<color> tags

The <color> tags define color names to be used in <style> tags. It has two attributes: name and value. value is a "final" color value as described above. Example:

<color name="aluminium1" value="#eeeeec"/>
<color name="with-transparency" value="#rgba(255,0,0,0.5)"/>

Note that <color> tags are optional because a <style> tag can have final color values too. <color> tags permit to avoid duplication of values, and to give them names (like a color palette).

<style> tags

Each <style> tag describes a single element of style scheme (it corresponds to a GtkSourceStyle object in the library API).

<style> attributes

A <style> tag supports the following attributes:

name (mandatory): Name of the style. It can be anything. Syntax highlighting uses lang-id:style-id, and there are a few special styles which are used to control general appearance of the text. Style scheme may contain other names to be used in an application. For instance, it may define color to highlight compilation errors in a build log or a color for bookmarks.
foreground: Foreground color.
background: Background color.
italic: "true" or "false".
bold: "true" or "false".
underline: Accepts the values supported by PangoUnderline ("none", "single", "double", "low" or "error"). GtkSourceView versions <= 3.16 only supported "true" or "false" and such values are still accepted for backward compatibility.
underline-color: Underline color.
strikethrough: "true" or "false".
scale: Scale the matched text block (font size). Possible values are a float number as factor (e.g. "1.75") or one of the values "xx-small", "x-small", "small", "medium", "large", "x-large", "xx-large". Useful for example to highlight titles or sub-titles (headings).
use-style: If the use-style attribute is used, the other attributes must not be used at the exception of the name. The value of use-style is the name of a previously-defined <style> tag inside the same style scheme file, to re-use the same style. So the order in which the <style> tags appear is important in this case (a “define-before-use” rule).

<style> - Special values for the name attribute

The name attribute of a <style> tag can have special values, which control the general appearance:

text: Default style of text.
selection: Style of selected text.
selection-unfocused: Style of selected text when the widget doesn't have input focus.
cursor: Text cursor style. Only the foreground attribute is used for this style.
secondary-cursor: Secondary cursor style (used in bidirectional text). Only the foreground attribute is used for this style. If this is not set while "cursor" is, then a color between text background and cursor colors is chosen, so it is enough to use "cursor" style only.
current-line: Current line style. Only the background attribute is used.
line-numbers: Text and background colors for the left margin, on which line numbers are drawn.
current-line-number: Current line style for the left margin, on which the current line number is drawn. Only the background attribute is used.
bracket-match: Style to use for matching brackets.
bracket-mismatch: Style to use for mismatching brackets.
right-margin: Style to use for the right margin. The foreground attribute is used for drawing the vertical line. And the background attribute is used for the background on the right side of the margin. An alpha channel is applied to the two colors. For a light style scheme, a good color for both attributes is black. For a dark style scheme, white is a good choice.
draw-spaces: Style to use for drawing spaces (special symbols for a space, a tabulation, etc). Only the foreground attribute is used.
background-pattern: Style to use for drawing a background pattern, for example a grid. Only the background attribute is used.