WorldForge UI Theme File Format Proposal


This is a proposal for a format for a theme that can be used to create GUI themes that work with many worldForge clients (and possibly other programs). Emphasis is given to allow complex themes to be created, maximizing artist freedom, while keeping the implementation requirements relatively simple. Extendability is also emphasized, making it easy to support different types of widgets, and not placing restrictions on the supported widget set.

Change History

2002-03-16 0.1 Hans Häggström zzorn first version


Generic enough to be used with different clients.

Expressive enough for allowing great looking game oriented UI themes.

Flexible enough to be easy to adapt to new widgets and other circumstances.

Simple enough to not be too complicated to implement in clients.


No size changes are normally caused by the theme. This way layout handling is completely up to the client. TODO: But how does font size affect this for example??

Themable colors, fonts, backgrounds, and UI event sounds.


XML is chosen as the format for describing the theme, as it is a widely supported standard for structured information.

Delivery could happen in a zip / tar.gz file that contains the XML theme description, and necessary bitmaps. Alternatively the XML descriptor can be loaded from a media server, and contain references to media packages containing the required bitmaps.




Name of theme


Version of theme (part of package format?)


Short description about this theme


Various comments by the authors about implementation details for future maintainers, or other things that don't belong in the description.


List of authors
Full name of author
Nickname or handle of author
Email to author
Web site
URL to authors private website or homepage
What this author has contributed to the theme.
Short presentation of the author, e.g. mini biography, ICQ number, alternative web sites, quote, silly comments.


Target Widgets
List of widget-state pairs that use this scheme.
WidgetStatePair has a widget and state. A shorthand notation of "WidgetName:StateName" is used here, although they are encoded as XML attributes or values.

Examples of widget state pairs are "Button:Pressed" or "MenuItem:Disabled".

A star can be used to indicate all states or all widgets. More specific widget-state pairs always override general wildcard based ones however. Example: "*:*" = all states of all widgets, "Label:*" = all states of Label widgets, "*:Disabled" = the disabled state of all widgets.

TODO: How to deal with multiple states? What about combining multiple states somehow? Pressed, Disabled, MouseOver, Focused, Checked, Selected, and so on are all orthogonal.
The font to use for the widget, including size, bold, italics, etc.
Foreground color
Font color & color of any foreground details (color includes alpha value?).
Font Effects
Raised, lowered, etc.
Icon Effects

Change Hue, Saturation, Brightness, Transparency, and/or colorize towards a given target color.

Raised, lowered, and similar edge effects.

Either has a color, gradient, bitmap, or is split in several smaller Background parts.
Can be one of:
  1. Vertical
  2. Horizontal
  3. 2*2 grid
  4. 3*3 grid
The last two alternatives are for convenience only, they could be implemented from the first two.

The theme can specify the location of each split as absolute pixels from an edge, or as a percentage from one edge of the original rectangle.

The subdivided parts are Background elements, and can have color/gradient/bitmap, or can be further split.
Inheriting shemes
An inheriting sheme uses the properties of the parent sheme, unless it overrides one of the properties.


Includes state changes (Enabled->Pressed, Pressed->Enabled, etc..), and any other events that the GUI engine wants to expose to the Theme? (perhaps a list of different possible events would be nice?). A way to make tabbed panel switching sound different from checking a checkbox, for example?.


Events can trigger sound effects. This way UI sounds can be integrated with the theme, which makes sense (a wooden theme can sound like pushing wooden buttons, and a crystal theme can sound like a crystal theme, etc). however, higher level sounds like warning and notice sounds, game and client specific noises, etc are not the responsibility of the theme, and best implemented in another way. Generally most Theme sounds are directly associated with things that happen to widgets of different types.

Cross Fading
It could also be possible to 'cross fade' the attributes of two Schemes over some time at certan state changes. That way a widget could be highlighted when it gets the focus, and fade back to normal colors over a few seconds when it looses focus, for example.

Possibly a cross fade could chain several schemes, to produce a flash or similar effects?

TODO: How to handle Borders that are not rectangular areas, but instead enclose a rectangular area?

TODO: What about stock icons, should the theme be able to specify them?

TODO: What about animated icons, colors, and/or backgrounds?