Graphical User Interface

Table of Contents

• Configuration XML File
• Font XML Files
• Imageset XML Files
• Layout XML Files
• Scheme XML Files
• LookNFeel XML Files

Reality Factory uses CEGUI (0.6.2) for managing its Graphical User Interface. Resources and configuration data requird by CEGUI are defined in various XML files, which are - by default - located in the gui subfolder. These include

• font files that define the font file (.ttf or image) to use and how to render it. (Editor: FontStudio for bitmapped fonts)
• imageset files describing a set of named regions (sub-images) contained in an image file. (Editor: CEImagesetEditor)
• layout files describing a set of widgets to create, their positions, sizes, and other attributes. Basically this describes the final on-screen layout of your GUI. (Editor: CELayoutEditor)
• scheme files grouping together data files and resources and defining some of their interactions.
• looknfeel files, which define the visual aspect of widgets declared in the scheme file.

Certain game elements, namely the Inventory, Conversations and Messages, and the associated parts of the GUI require very game-specific behaviour. To provide maximum flexibility in this area, Reality Factory offers a scriptable interface to these components and to a substantial part of the CEGUI API. See the corresponding documentation of the respective components for further information.

Configuration XML File

The cegui.config file allows you to specify the logging level for the CEGUI component, the default scheme and the default font to use for your GUI.

The LoggingLevel can be set to one of the following:

• Errors
• Standard
• Informative
• Insane

---

Font XML Files

Font files can define one of two types of font: a static bitmapped font based on an Imageset that contains the predrawn bitmap representations of the character glyphs the font will render, or a dynamically created font based upon standard font files (such as .ttf files). FontStudio can be used to create a bitmapped font.

<Font> Element

<Font> is the root element in XML font definition files, it has some attributes and optional 'Mapping' elements. Mapping elements are only of importance for static / pixmap fonts, any Mapping elements defined for a dynamic font should be ignored.

Attributes
Name	the name that will be used to identify the Font within the system. (required).
Filename	filename for the font. For Static fonts this is an Imageset. For Dynamic fonts this is a .ttf file. (required).
ResourceGroup	The resource group identifier to pass to the resource provider when loading the file.
Type	Specifies the type of font. Valid options are 'FreeType' or 'Pixmap' (required).
Size	Specifies the point size for a dynamic font, ignored for Static fonts. (optional, default=12).
NativeHorzRes	The horizontal screen resolution that the images were are intended to be displayed at (optional, default=640).
NativeVertRes	The vertical screen resolution that the images were are intended to be displayed at (optional, default=480).
AutoScaled	Boolean, states whether to scale imagery so it appears the same size at any resolution (optional, default=false).
AntiAlias	Boolean, states whether the font should be anti-aliased, applies to dynamic fonts only. (optional, default=true).

<Mapping> Element

Used for static fonts only, defines a mapping between a UTF32 codepoint value and an Image defined on the associated Imageset. A Mapping must be supplied for each codepoint that the font is to have available for rendering. A Mapping may only appear as a sub-element of the <Font> element and has no sub-elements.

Attributes
Codepoint	Unicode codepoint which should be mapped. (required).
Image	Name of the image to map. This image shold be defined for the Imageset specified in Filename for the Font.
HorzAdvance	Number of pixels to advance the 'pen' position after rendering. -1 indicates the values should be auto-calculated. (optional, default=-1).

---

Imageset XML Files

An Imageset is a collection of named regions upon an image file (texture). In CEGUI terminology, each of these named regions is an Image and is the basic level of imagery used by CEGUI.

Note:

The technical reason for using imagesets instead of separate image files is to reduce the number of textures switches when rendering the GUI thus improving performance.

<Imageset> Element

The <Imageset> element is the root element in XML imageset definition files. It may contain any number of <Image> elements.

Attributes
Imagefile	path to the image file containing the graphics (required).
ResourceGroup	The resource group identifier to pass to the resource provider when loading the file.
Name	the name that will be assigned to the Imageset in the GUI system (required).
NativeHorzRes	The horizontal screen resolution that the images were are intended to be displayed at (optional, default=640).
NativeVertRes	The vertical screen resolution that the images were are intended to be displayed at (optional, default=480).
AutoScaled	Boolean, states whether to scale imagery so it appears the same size as any resolution (optional, default=false).

<Image> Element

Defines a single component image of an imageset.

Attributes
Name	The name that will be used to identify the image within the Imageset. (required).
XPos	X pixel co-ordinate of the top-left corner of the image on the texture. (required).
YPos	Y pixel co-ordinate of the top-left corner of the image on the texture. (required).
Width	Width of this image in pixels. (required).
Height	Height of this image in pixels. (required).
XOffset	Horizontal offset to apply when rendering. (optional, default=0)
YOffset	Vertical offset to apply when rendering. (optional, default=0)

---

Layout XML Files

A layout XML file defines a hierachy of window based objects to be created, with property and event binding information for each window.

Layout Element List:

<AutoWindow> Element
<Event> Element
<GUILayout> Element
<LayoutImport> Element
<Property> Element
<Window> Element

<GUILayout> Element

<GUILayout> is the root element in layout XML files.

Attributes
Parent	Specifies the name of an existing window that root window of this gui layout should be attached to after loading the layout. Optional attribute, if this is not specified the root window is not automatically attached to any existing window.

• The <GUILayout> element is the root element for layout files.
• The <GUILayout> element must contain a single <Window> element.
• No element may contain a <GUILayout> element as a sub-element.

<Window> Element

The <Window> element is used to specify a new window object to be created.

Attributes
Type	Specifies the type of window to be created. This may refer to a concrete window type, an alias, or a falagard mapped type. Required attribute.
Name	Specifies the name to give the window. Window names must be unique within the system. Optional attribute, if the attribute is not specified a name will be generated automatically.

• The <Window> element may appear as a sub-element of the following:
  • <GUILayout> elements.
  • <Window> elements.
  • <AutoWindow> elements.
• The <Window> element may contain the following sub-elements:
  • Any number of <LayoutImport> elements. Followed by,
  • Any number of <Property> elements. Followed by,
  • Any number of <Event> elements. Followed by,
  • Any number of <Window> elements.
  • Any number of <AutoWindow> elements.
  • Finally, any number of <Property> elements (again).

<Property> Element

The <Property> element is used to set properties on the Window created by the containing <Window> element.

Attributes
Name	Specifies the name of the property to set. Required attribute.
Value	Specifies the value to set on the property. Optional attribute, if the attribute is not specified the value to be set should be given via the element text content.

• The <Property> element may appear as a sub-element of <Window> elements and <AutoWindow> elements.
• The <Property> element may not contain any sub-elements.
• The <Property> element may contain text content to be used as the value.

<Event> Element

The <Event> element is used to create bindings between GUI elements and script functions.

Attributes
Name	Specifies the name of the event to which the handler function specified by the Function attribute will be subscribed. Required attribute.
Function	Specifies the name of a script function to be subscribed to the event specified by the Name attribute. Required attribute.

• The <Event> may appear as a sub-element of <Window> elements and <AutoWindow> elements.
• The <Event> element may not contain any sub-elements.

<LayoutImport> Element

The <LayoutImport> element is used to reference (import) a layout file into another. The root window of the imported layout is attached to the Window where the import occurrs.

Attributes
Filename	Specifies the path to the xml layout file to be imported. Required attribute.
Prefix	Specifies a prefix that will be prepended to the window name of each window created from the imported layout. Optional attribute.
ResourceGroup	Specifies the resource group identifier to pass to the ResourceProvider when loading the file given in the Filename attribute. Optional attribute, default is the WindowManager default group.

• The <LayoutImport> element may appear as a sub-element of <Window> elements and <AutoWindow> elements.
• The <LayoutImport> element may not contain any sub-elements.

<AutoWindow> Element

The <AutoWindow> element is used to target property settings, events and other content on to an automatically created child window of the current Window (or AutoWindow).

Attributes
NameSuffix	Specifies the name suffix of the target auto-window. Required attribute.

• The <AutoWindow> element may appear as a sub-element of the following:
  • <Window> elements.
  • <AutoWindow> elements.
• The <AutoWindow> element may contain the following sub-elements:
  • Any number of <LayoutImport> elements. Followed by,
  • Any number of <Property> elements. Followed by,
  • Any number of <Event> elements. Followed by,
  • Any number of <Window> elements.
  • Any number of <AutoWindow> elements.
  • Finally, any number of <Property> elements (again).

---

Scheme XML Files

A Scheme file is a largely means to group other data files and resources together, and to define some of their interactions, and form a single point to load what might be considered a 'skin' for CEGUI's windows and widgets.

Scheme Element List:

<FalagardMapping> Element
<Font> Element
<GUIScheme> Element
<Imageset> Element
<ImagesetFromImage> Element
<LookNFeel> Element
<WindowAlias> Element
<WindowFactory> Element
<WindowRendererFactory> Element
<WindowRendererSet> Element
<WindowSet> Element

<GUIScheme> Element

The <GUIScheme> element is the root element of the scheme file.

Attributes
Name	Specifies the name that the scheme will be known by within the system. Required attribute.

• The <GUIScheme> element is the root element for scheme files.
• The <GUIScheme> element may contain the following sub-elements (in any sequence):
  • Any number of <Imageset> elements.
  • Any number of <ImagesetFromImage> elements.
  • Any number of <Font> elements.
  • Any number of <LookNFeel> elements.
  • Any number of <WindowSet> elements.
  • Any number of <WindowRendererSet> elements.
  • Any number of <WindowAlias> elements.
  • Any number of <FalagardMapping> elements.
• No element may contain a <GUIScheme> element as a sub-element.

<FalagardMapping> Element

Specifies a mapping that ties together a concrete Window based object, a concrete WindowRenderer based object, and a WidgetLook definition to create a specified window type that can then be instantiated via the WindowManager.

Attributes
WindowType	Specifies a name for the mapping / window type being created. Required attribute.
TargetType	Specifies the name of the concrete Window based object that contains the logic for the window type being specified. Required attribute.
Renderer	Specifies the name of the concrete WindowRenderer based object that contains the rendering specific code for the window type being specified. Required attribute.
LookNFeel	Specifies the name of the Falagard WidgetLook definition that contains imagery and other definitions for the window type being specified. Required attribute.

• The <FalagardMapping> element may only appear as a sub-element of the <GUIScheme> element.
• The <FalagardMapping> element may not contain any sub-elements.

<Font> Element

Specifies a Font to be loaded as part of the scheme. If a font with the requested name already exists, the file specified is not loaded.

Attributes
Name	Specifies the name of the font as specified in the font xml file. This is a validation check; if this name is specified it must match the name given in the font xml file or an exception will be thrown. If this name is not given, the name is extracted from the font xml the first time it is loaded. Optional attibute.
Filename	Specifies the path to the font XML file. Required attribute.
ResourceGroup	Specifies the resource group identifier to pass to the ResourceProvider when loading the file specified in the Filename attribute. Optional attribute, if this is not specified the default resource group for Font files is used.

• The <Font> element may only appear as a sub-element of the <GUIScheme> element.
• The <Font> element may not contain any sub-elements.

<Imageset> Element

Specifies an imageset to be loaded as part of this scheme. If an imageset with the requested name already exists, the file specified is not loaded.

Attributes
Name	Specifies the name of the imageset as specified in the imagseset xml file. This is a validation check; if this name is specified it must match the name given in the imageset xml file or an exception will be thrown. If this name is not given, the name is extracted from the imageset the first time it is loaded. Optional attibute.
Filename	Specifies the path to the imageset XML file. Required attribute.
ResourceGroup	Specifies the resource group identifier to pass to the ResourceProvider when loading the file specified in the Filename attribute. Optional attribute, if this is not specified the default resource group for Imageset files is used.

• The <Imageset> element may only appear as a sub-element of the <GUIScheme> element.
• The <Imageset> element may not contain any sub-elements.

<ImagesetFromImage> Element

Specifies an imageset to be created directly from an image file as part of this scheme. If an imageset with the requested name already exists, the file specified is not loaded.

Attributes
Name	Specifies the name to be used for the imageset. If this attribute is not given, the imageset is given the name of it's file. Optional attibute.
Filename	Specifies the path to the image file that will be loaded for this imageset (also used as the name of the Imageset if the Name attribute is not given). Required attribute.
ResourceGroup	Specifies the resource group identifier to pass to the ResourceProvider when loading the file specified in the Filename attribute. Optional attribute, if this is not specified the default resource group for Imageset files is used.

• The <ImagesetFromImage> element may only appear as a sub-element of the <GUIScheme> element.
• The <ImagesetFromImage> element may not contain any sub-elements.

<LookNFeel> Element

Specifies a LookNFeel file - containing WidgetLook definitions - to be parsed as part of this scheme.

Attributes
Filename	Specifies the path to the looknfeel xml file that will be parsed. Required attribute.
ResourceGroup	Specifies the resource group identifier to pass to the ResourceProvider when loading the file specified in the Filename attribute. Optional attribute, if this is not specified the default resource group for LookNFeel files is used.

• The <LookNFeel> element may only appear as a sub-element of the <GUIScheme> element.
• The <LookNFeel> element may not contain any sub-elements.

<WindowAlias> Element

Specifies an alias for a given window type.

Attributes
Alias	Specifies the name of the alias; this is an alternative name by which the window type specified by the Target attribute will be known.
Target	Specifies the window type that will be created when a window of the type specified by the attribute Alias is specified.

• The <WindowAlias> element may only appear as a sub-element of the <GUIScheme> element.
• The <WindowAlias> element may not contain any sub-elements.

<WindowFactory> Element

Specifies the name of a WindowFactory object from the loadable module represented by the containing <WindowSet> that is to be registered with the system.

Attributes
Name	Specifies the name of the WindowFactory object to be registered with the system. Required attribute.

• The <WindowFactory> element may only appear as a sub-element of the <WindowSet> element.
• The <WindowFactory> element may not contain any sub-elements.

<WindowRendererFactory> Element

Specifies the name of a WindowRendererFactory object from the loadable module represented by the containing <WindowRendererSet> that is to be registered with the system.

Attributes
Name	Specifies the name of the WindowRendererFactory object to be registered with the system. Required attribute.

• The <WindowRendererFactory> element may only appear as a sub-element of the <WindowRendererSet> element.
• The <WindowRendererFactory> element may not contain any sub-elements.

<WindowRendererSet> Element

Specifies the name of a loadable module containing concrete WindowRenderer based entities and their factories. If one or more <WindowRendererFactory> elements are given, only the specified factories will be registered with the system; if no <WindowRendererFactory> elements are specified, all available factories from the module will be registered.

Attributes
Filename	Specifies the name of the loadable module (dll / .so / etc). Required attribute.

• The <WindowRendererSet> element may only appear as a sub-element of the <GUIScheme> element.
• The <WindowRendererSet> element may contain any number of <WindowRendererFactory> sub-elements.

<WindowSet> Element

Specifies the name of a loadable module containing concrete Window based entities and their factories. If one or more <WindowFactory> elements are given, only the specified factories will be registered with the system; if no <WindowFactory> elements are specified, all available factories from the module will be registered.

Attributes
Filename	Specifies the name of the loadable module (dll / .so / etc). Required attribute.

• The <WindowSet> element may only appear as a sub-element of the <GUIScheme> element.
• The <WindowSet> element may contain any number of <WindowFactory> sub-elements.

---

LookNFeel XML Files

Falagard skin definition files.