OpenGUI Documentation

XML Documentation

Warning:
The XML specification has changed since version 0.7.7.
OpenGUI provides a service for loading and unloading via XML configuration files. The exact specification of these XML files is highly dependent on the plugins you have loaded, as any plugin can register to handle any XML tags, even overriding the previous functionality of a tag. For more information on this registration system and how it can affect your application, see the XMLParser documentation. The following documentation will cover the default handling of these tags.

Note:
Tag and attribute names are case sensitive. This is different from older version of XML handling code.
Warning:
The XML parsers perform actions on the data as they read it. Meaning that you cannot create Widgets based on Widget Definitions until the definition tags have been parsed, or perform any other out-of-order operation. The XML logic is very basic by design, and it all nearly directly translates into API calls, which are noted in the tag's documentation.

OpenGUI comes with built in processors for several tags. These tags come in 2 flavors. Universal tags that are handled no matter where they are found, and OpenGUI specific tags that are only handled when found within an enclosing <OpenGUI> tag.

Universal tags:

OpenGUI specific tags (usage hierarchy preserved):

Be sure to check out the Example Config File as well.

<Include>

Performs what is effectively an inline include of the given File. The included file will be parsed for XML based configuration content. Includes can occur absolutely anywhere that the XMLParser is in charge of handling the tag, but since it is often difficult to distinguish where the XMLParser is and is not working it is often best to use these as root level tags only.

Recursive includes are supported, but each file can only be included once per <Include> tag during recursive processing. For example, if file A includes file B, and file B includes file A then the include processing will stop after expansion of file B, as file A has already been included. Self recursive include loops are logged with warnings, but are otherwise ignored. (The multiple include testing is performed using a simple case-insensitive string comparison. Minor path tricks will fool it, but are generally discouraged.)

Example: 

<Include File="metal.xml" />

Attributes

<Plugin>

Loads a plugin by passing the given File to OpenGUI::PluginManager::loadPlugin().

Example: 

<Plugin File="TachometerWidget" />

Attributes
See also:
OpenGUI::PluginManager::loadPlugin() has the potential to perform filename mangling. See its documentation for more information.

<Font>

Registers a new FontSet via OpenGUI::FontManager::RegisterFontSet()

Example: 

<Font Name="pecot" File="pecot.ttf" />

Attributes

<Imageset>

Loads the given File as an imageset via OpenGUI::ImageryManager::createImageset().

Example: 

<Imageset File="tachometer.png">
	<!-- some <Imagery> tags in here -->
</Imageset>

Attributes
Note:
Due to the way the ImageryManager treats duplicate requests to createImageset(), duplicate entries of this tag have no ill effect, and the <Imagery> enclosed within any duplicates will be added to the originally established Imageset.

<Imagery>

Adds an Imagery to the enclosing Imageset via OpenGUI::Imageset::createImagery(). This tag must be enclosed by an <Imageset> tag or it is ignored!

Example: 

<Imageset File="somefile">
	<Imagery Name="TachBG" Left="2" Top="2" Width="321" Height="321" />
</Imageset>

Attributes
Note:
Multiple <Imagery> tags with the same Name will redefine the Imagery as defined in OpenGUI::Imageset::createImagery().

<CursorDef>

Defines a Cursor of the given Name using the given BaseName and BaseLibrary via OpenGUI::CursorManager::DefineCursor(). Any enclosed <Property> tags are used to define property settings that will be applied to the cursor upon creation, as per the DefineCursor() function.

Example: 

<CursorDef Name="Square" BaseName="Generic" BaseLibrary="OpenGUI">
	<Property ValueName="Size" ValueType="FVECTOR2" ValueData="(100x100)" />
	<Property ValueName="Imagery" ValueType="STRING" ValueData="TachBG" />
	<Property ValueName="Offset" ValueType="IVECTOR2" ValueData="(160x160)" />
</CursorDef>

Attributes
Warning:
Multiple cursor definitions with the same name will result in an error.

<WidgetDef>

Defines a Widget of the given Name using the given BaseName and BaseLibrary via OpenGUI::WidgetManager::DefineWidget(). Any enclosed <Property> tags are used to define property settings that will be applied to the widget upon creation, as per the DefineWidget() function.

Example: 

<WidgetDef Name="Tachometer" BaseName="Tachometer" BaseLibrary="OpenGUIEx">
	<!-- some optional <Property> tags -->
</WidgetDef>

Attributes
Warning:
Multiple widget definitions with the same name will result in an error.

<Property>

These tags are not processed by XMLParser directly, but are rather processed in DOM style by their containing tag processor. However, their format is standard throughout OpenGUI for consistency purposes. For the most part, these tags are loaded into OpenGUI::Value objects via OpenGUI::Value::LoadFromXMLNode(), and are stored for later use as property assignments for the object definition that contained them.

Example: 

<Property ValueName="Size" ValueType="FVECTOR2" ValueData="(100x100)" />

Attributes

<Screen>

The <Screen> tag is used to create and destroy Screen objects through XML. During XMLLoad all attributes provided are read and used. During XMLUnload, only the Name attribute is used to identify the Screen to destroy. Only the Name and Size attributes are required, with all others being optional with implied defaults. See OpenGUI::Screen for more information on the default values.

Example: 

<Screen Name="MainScreen" Size="(800x600)" UPI="(96x96)" AutoUpdating="True" AutoTiming="True" DefaultCursor="Square" CursorEnabled="True" CursorVisible="True" >
	<!-- optional <Widget> tags in here -->
</Screen>

Attributes
Note:
If the processing of the <Screen> tag fails at any stage, the entire Screen is invalid, and will not be created. If it has already been created, it will be destroyed before processing returns.

<Widget>

The <Widget> tag is used to create widgets underneath of the containing <Widget> or <Screen> or <FormDef> tag. When processing this tag, the parent is cast into a ContainerControl. If this cast fails, the operation will fail. It is the XML writer's responsibility to ensure that they only place children <Widget> tags within proper containing objects.

Example: 

<!-- either <Screen>, <Widget>, or <FormDef> -->
	<Widget Name="MyTach" DefName="Tachometer">
		<!-- some optional <Property> tags -->
		<!-- some optional <Widget> tags in here if this widget is a container -->
	</Widget>
<!-- end enclosing </Screen>, </Widget>, or </FormDef> -->

Attributes
Note:
The BaseName and BaseLibrary attributes require eachother. You cannot have one without the other. Additionally, the DefName is mutually exclusive with the BaseName / BaseLibrary pair. You can use one method or the other, but you cannot use both.
See also:
<Property>, <WidgetDef>, <Screen>, <FormDef>
Remarks:
The <Property> tags within are processed after the attachment to the parent has been made. All applicable <WidgetDef> properties are still processed during widget creation, which is prior to the attachment. All <Property> tags are fully processed before any other child tags are processed. This is a minor deviation from the usual "in-order processing" that XML processing usually exibits. It should also be noted that for the sake of loading speed, the automatic layout code is temporarily disabled during the potential creation of children via the OpenGUI::ContainerControl::suspendLayout() and OpenGUI::ContainerControl::resumeLayout() functions.
Attention:
When adding created Widgets to the container, they are added in the order they are processed using OpenGUI::WidgetCollection::add_back(widget,true). The important things to note here is that they are added to the back (visually below previous widgets), and that the parent container assumes ownership of the pointer (meaning that the widget will be deleted when the parent container is deleted).

<FormDef>

Form definitions provide a mechanism for defining fully built forms for reuse multiple time at any location within an existing GUI hierarchy. The <FormDef> tag itself describes both the name of the form as well as the widget type of the root container. The attribute names and uses are analogous to the <Widget> tag by design both for ease of use as well as to serve as a reminder that the <FormDef> tag itself represents the root widget. Within each level of the form you can embed <Widget> and <Property> tags. These will provide the structure of the form, as well as initial property settings that are applied when the form is instantiated. The given widgets are not tested for existance or their ability to act as containers during form definition creation. Instead, the widgets are resolved at instantiation. Their ability to act as containers is only tested (and required) should they be asked to contain additional widgets according to the form definition at instantiation.

Example: 

<FormDef Name="MyFormName" BaseName="SomeContainer" BaseLibrary="SomeLibrary">
	<!-- some optional <Property> tags -->
	<!-- some optional <Widget> tags in here if this widget is a container, each able to contain further  <Widget> and <Property> tags -->
</FormDef>

Attributes

<Form>

The <Form> tag can be used to create an instance of a Form that was previously defined either progmatically or by use of the <FormDef> tag. The form definition is referenced by the FormDef attribute. The Name attribute (if present) is used as the name to assign the root widget before it is added to the parent container, otherwise the root element will assume the name of the form definition it was created from.

Example: 

<Form Name="ElementName" FormDef="MyFormName" />

Attributes

<Face>

OpenGUI::Face objects can be defined in XML, and will be stored by the OpenGUI::ImageryManager for later retrieval. In order to define a Face via XML, you need to declare both a Name and a Metric, and fill it with <Row>s of <Slice>s.

Example: 

<Face Name="FaceName" Metric="Units">
	<!-- contains <Row>s of <Slice>s, as shown below -->
	<Row>
		<Slice />
	</Row>
</Face>

Attributes

<Row>

Groups contained <Slice>s into logical rows.

Example: 

<Face Name="FaceName" Metric="Units">
	<!-- contains <Row>s of <Slice>s, as shown below -->
	<Row>
		<Slice />
	</Row>
</Face>

Attributes
Has no attributes. It is purely a grouping mechanism.

<Slice>

Defines a single Slice of a Face. Must be contained by a <Row>, which is also contained by a <Face>. All attributes are optional, the defaults of which are specified by OpenGUI::SliceDef.

Example: 

<Face Name="FaceName" Metric="Units">
	<!-- contains <Row>s of <Slice>s, as shown below -->
	<Row>
		<Slice Width="20" Height="20" Imagery="GenericFrameML" />
	</Row>
</Face>

Attributes

Example Config File

The following is an example xml file. It is listed here in its entirety so that you can get an idea of what a common config file looks like. 
<?xml version="1.0" ?>
<OpenGUI>
	<Plugin File="TachometerWidget" />
	
	<Font Name="pecot" File="pecot.ttf" />

	<Imageset File="tachometer.png">
		<Imagery Name="TachBG" Left="2" Top="2" Width="321" Height="321" />
		<Imagery Name="TachNeedle" Left="42" Top="348" Width="131" Height="7" />
	</Imageset>


	<CursorDef Name="Square" BaseName="Generic" BaseLibrary="OpenGUI">
		<Property ValueName="Size" ValueType="FVECTOR2" ValueData="(100x100)" />
		<Property ValueName="Imagery" ValueType="STRING" ValueData="TachBG" />
		<Property ValueName="Offset" ValueType="IVECTOR2" ValueData="(160x160)" />
	</CursorDef>
	
	<WidgetDef Name="Tachometer" BaseName="Tachometer" BaseLibrary="OpenGUIEx">
	</WidgetDef>
</OpenGUI>

Note:
The <?xml version="1.0" ?> line is not required by TinyXML, but you may want to add it anyways.
Copyright © 2006 OpenGUI | OpenGUI.SF.net
Generated: Sun Sep 9 02:00:20 2007