Basic format
The theme file format is an XML file. It is specified by a DTD:
<!DOCTYPE themes PUBLIC "-//www.matthiasmann.de//TWL-Theme//EN" "http://hg.l33tlabs.org/twl/raw-file/tip/src/de/matthiasmann/twl/theme/theme.dtd">

It consists of the following top level elements:

Many elements in the theme file can specify a name attribute. Some elements are required to construct other elements and should not be used directly. It is common practise to start the name for such elements with '-'.

Some elements refer to additionals files. These file names are URLs relative to the current theme file.

Images
This element specifies an image file and allows to name regions within that file.
<images file="filename.png">
....
</images>

attribute required description
file yes specifies the URL for the image file - the default renderer only supports PNG.
format no how to load that image:
  • COLOR
  • ALPHA (only applicable to gray scale images)
filter no how to filter that image on resizing:
  • NEAREST
  • LINEAR

Elements on the first child level are named (eg they need a name attribute). Elements below the first level can't have names. Images and cursors have an independent name space.

The following predefined elements exist:
name type description
none image A 0x0 pixel image object. Can be used to make holes in a grid.
os-default cursor The OS default cursor.

The following child elements are supported:
The following attributes are support on nearly any child element:
attribute required description
border no Specifies a border which can be used in a theme. It is accessible as property. All values must be positive.
format description
"T,L,B,R" 4 values for Top, Left, Bottom and Right
"H,V" 2 values for Horizontal and Vertical. Identical to "V,H,V,H"
"B" 1 value for Border. Identical to "B,B,B,B" or "B,B"
inset no The inset is added to the size of the image but not considered while rendering. This allows for effects like glow or shadows. The inset can also be negative. It can be specified in the same way as the border.
sizeOverwriteH no Changes the size of image. This can be used to force scaling.
sizeOverwriteV no Changes the size of image. This can be used to force scaling.
tint no Optional tinting of that image. The color is multiplied with the image. See de.matthiasmann.twl.Color.parseColor
center no if "true" then the image is not scaled up if it's drawn onto a arger area but drawn centered instead.
repeatX no if "true" then the image is repeated and stretched as often as needed to cover the requested area but no parts are cut off. The number of copies is determined by max(1, floor(targetSize / imageSize)).
repeatY no similar to repeatX
if no Specifies a condition which must evaluate to true in order to render this image.
unless no Specifies a condition which must evaluate to false in order to render this image.
Fonts
This element defines a global font:
<fontDef name="fontname" filename="fontfile.fnt" color="white">
....
</fontDef>

attribute required description
name yes the name for this global font. Used to reference this font in themes.
default no if set to "true" then this is the default font. If no default font is specified then the first font is used as default.
filename mostly specifies the URL for the font file - the filename is combined with the URL of the containing theme XML file and passed to the Renderer interface.
The default LWJGLRenderer supports BMFont XML (preferred) and TXT format. Use the TWL Theme Editor to create these from TTF files (Tools menu -> Create font).
families no list of comma separated font family names for use with FontMapper
When this attribute is specified then "size" is also required.
size (yes) font size in pixels - only required when "families" is specified
style no list of comma separated font styles - used when "families" is specified
Supported styles are "bold" and "italic"
color yes* the default font color
* * any attribute except "name" and "default" is passed as font parameter to the renderer

The following child element can be added to adjust font parameters based on animation states using boolean algebra:
<fontParam if="state" color="black">

attribute required description
if no This font param only applies when the condition evaluates to true.
unless no This font param does NOT apply when the condition evaluates to true.
color yes* the default font color
* * any attribute except "if" and "unless" is passed as font parameter to the renderer
Either if or unless is required.

Attributes marked with * assume the use of de.matthiasmann.twl.renderer.lwjgl.LWJGLRenderer
Input mappings
A input map is used to map keys or key combinations to actions.
This element defines a global input map:
<inputMapDef name="mapname" ref="base-mapname">
....
</fontDef>

attribute required description
name yes the name for this global input map. Used to reference this input map in themes or other input maps.
ref no Specify another input map which should be used as a base for this one. All mapping of the base map are copied into this map and can be overwritten.

The following child element is used to define mappings:
<action name="actionname">ctrl C</action>
attribute required description
name yes The action which is fired when the specified key combination is pressed.

The following modifiers are supported:
Constants
This element declares a global constant.
<constantDef name="name">....</constantDef>
Exactly one parameter type must be specified as child element.
Themes
This element specifies a top level theme.
<theme name="themename" ref="base-themename" allowWildcard="true">
....
</theme>

attribute required description
name yes The theme name
ref no Specify another theme which should be used as a base for this one. All entries of the base theme are copied into this theme and can be overwritten.
allowWildcard no Default is "false", if set to "true" then this theme is a candidate for wildcard child theme resolution.

The following child elements are allowed:
Parameter types
The following parameter types are supported:
Conditions
Every widget in TWL has an animation state. These states can be used in various places to change the appearance. This is done using conditions and boolean algebra. The following operators are supported:
operator name description
! a NEG negates the result of the sub term. This has highest precedense
( a ) sub term only one kind of the following operators can be used within each sub term.
a + b AND returns true when all sub terms evaluate to true
a | b OR returns true when atleast one sub term evaluates to true
a ^ b XOR returns true when an odd number (1,3,5,...) of sub term evaluates to true

Examples:
hover
hover | armed
(hover | armed) + !selected
hover ^ armed

Conditions are specified as attributes with either if or unless but not both.