WorldForge UI Theme File Format Proposal

Abstract

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

Goals

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.

Requirements

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.

Implementation

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.

Structure

Theme

Name

Name of theme

Version

Version of theme (part of package format?)

Description

Short description about this theme

Comments

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

Authors

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

Scheme

Target Widgets
List of widget-state pairs that use this scheme.
WidgetStatePair
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.
Font
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.

Background
Either has a color, gradient, bitmap, or is split in several smaller Background parts.
Color
Gradient
Bitmap
Division
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.

Events

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?.

Sounds

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?