Falagard System XML elements reference

From CEGUIWiki

The following contains reference material for the XML elements defined for the Falagard skind definition files.

Contents 1 Template 1.1 Purpose: 1.2 Attributes: 1.3 Usage: 1.4 Examples: 2 Elements 2.1 <AbsoluteDim> Element 2.1.1 Purpose: 2.1.2 Attributes: 2.1.3 Usage: 2.1.4 Examples: 2.2 <Area> Element 2.2.1 Purpose: 2.2.2 Attributes: 2.2.3 Usage: 2.2.4 Examples: 2.3 <AreaProperty> Element 2.3.1 Purpose: 2.3.2 Attributes: 2.3.3 Usage: 2.4 <Child> Element 2.4.1 Purpose: 2.4.2 Attributes: 2.4.3 Usage: 2.4.4 Examples: 2.5 <ColourProperty> Element 2.5.1 Purpose: 2.5.2 Attributes: 2.5.3 Usage: 2.5.4 Examples: 2.6 <ColourRectProperty> Element 2.6.1 Purpose: 2.6.2 Attributes: 2.6.3 Usage: 2.6.4 Examples: 2.7 <Colours> Element 2.7.1 Purpose: 2.7.2 Attributes: 2.7.3 Usage: 2.7.4 Examples: 2.8 <Dim> Element 2.8.1 Purpose: 2.8.2 Attributes: 2.8.3 Usage: 2.8.4 Examples: 2.9 <DimOperator> Element 2.9.1 Purpose: 2.9.2 Attributes: 2.9.3 Usage: 2.9.4 Examples: 2.10 <Falagard> Element 2.10.1 Purpose: 2.10.2 Attributes: 2.10.3 Usage: 2.10.4 Examples: 2.11 <FontDim> Element 2.11.1 Purpose: 2.11.2 Attributes: 2.11.3 Usage: 2.11.4 Examples: 2.12 <FrameComponent> Element 2.12.1 Purpose: 2.12.2 Attributes: 2.12.3 Usage: 2.12.4 Examples: 2.13 <HorzAlignment> Element 2.13.1 Purpose: 2.13.2 Attributes: 2.13.3 Usage: 2.13.4 Examples: 2.14 <HorzFormat> Element 2.14.1 Purpose: 2.14.2 Attributes: 2.14.3 Usage: 2.14.4 Examples: 2.15 <HorzFormatProperty> Element 2.15.1 Purpose: 2.15.2 Attributes: 2.15.3 Usage: 2.15.4 Examples: 2.16 <Image> Element 2.16.1 Purpose: 2.16.2 Attributes: 2.16.3 Usage: 2.16.4 Examples: 2.17 <ImageDim> Element 2.17.1 Purpose: 2.17.2 Attributes: 2.17.3 Usage: 2.17.4 Examples: 2.18 <ImageryComponent> Element 2.18.1 Purpose: 2.18.2 Attributes: 2.18.3 Usage: 2.18.4 Examples: 2.19 <ImageProperty> Element 2.19.1 Purpose: 2.19.2 Attributes: 2.19.3 Usage: 2.20 <ImagerySection> Element 2.20.1 Purpose: 2.20.2 Attributes: 2.20.3 Usage: 2.20.4 Examples: 2.21 <Layer> Element 2.21.1 Purpose: 2.21.2 Attributes: 2.21.3 Usage: 2.21.4 Examples: 2.22 <NamedArea> Element 2.22.1 Purpose: 2.22.2 Attributes: 2.22.3 Usage: 2.22.4 Examples: 2.23 <Property> Element 2.23.1 Purpose: 2.23.2 Attributes: 2.23.3 Usage: 2.23.4 Examples: 2.24 <PropertyDefinition> Element 2.24.1 Purpose: 2.24.2 Attributes: 2.24.3 Usage: 2.24.4 Examples: 2.25 <PropertyDim> Element 2.25.1 Purpose: 2.25.2 Attributes: 2.25.3 Usage: 2.25.4 Examples: 2.26 <Section> Element 2.26.1 Purpose: 2.26.2 Attributes: 2.26.3 Usage: 2.26.4 Examples: 2.27 <StateImagery> Element 2.27.1 Purpose: 2.27.2 Attributes: 2.27.3 Usage: 2.27.4 Examples: 2.28 <Text> Element 2.28.1 Purpose: 2.28.2 Attributes: 2.28.3 Usage: 2.28.4 Examples: 2.29 <TextComponent> Element 2.29.1 Purpose: 2.29.2 Attributes: 2.29.3 Usage: 2.29.4 Examples: 2.30 <UnifiedDim> Element 2.30.1 Purpose: 2.30.2 Attributes: 2.30.3 Usage: 2.30.4 Examples: 2.31 <VertAlignment> Element 2.31.1 Purpose: 2.31.2 Attributes: 2.31.3 Usage: 2.31.4 Examples: 2.32 <VertFormat> Element 2.32.1 Purpose: 2.32.2 Attributes: 2.32.3 Usage: 2.32.4 Examples: 2.33 <VertFormatProperty> Element 2.33.1 Purpose: 2.33.2 Attributes: 2.33.3 Usage: 2.33.4 Examples: 2.34 <WidgetDim> Element 2.34.1 Purpose: 2.34.2 Attributes: 2.34.3 Usage: 2.34.4 Examples: 2.35 <WidgetLook> Element 2.35.1 Purpose: 2.35.2 Attributes: 2.35.3 Usage: 2.35.4 Examples:

Template

The reference for each element is arranged into sections, as described below:

Purpose:

This section describes what the elements general purpose is within the specifications.

Attributes:

This section describes available attributes for the elements, and whether they are required or optional.

Usage:

Describes where the element may appear, whether the element may have sub-elements, and other important usage information.

Examples:

For many elements, this section will contain brief examples showing the element used in context.

Elements

<AbsoluteDim> Element

Purpose:

The <AbsoluteDim> element is used to define a component dimension for an area rectangle. <AbsoluteDim> is used to specify absolute pixel values for a dimension.

Attributes:

• value - specifies the a number of pixels. Required attribute.

Usage:

• The <AbsoluteDim> element may contain a single <DimOperator> element in order to form a dimension calculation.
• The <AbsoluteDim> element can appear as a sub-element in <Dim> to form a dimension specification for an area.
• The <AbsoluteDim> element can appear as a sub-element of <DimOperator> to specify the second operand for a dimension calculation.

Examples:

The following shows <AbsoluteDim> used to define an area rectangle. In the example, all four component dimensions of the area rectangle are specified using <AbsoluteDim>:

<Area>
  <Dim type="LeftEdge" >
    <AbsoluteDim value="10" />
  </Dim>
  <Dim type="TopEdge" >
    <AbsoluteDim value="50" />
  </Dim>
  <Dim type="Width" >
    <AbsoluteDim value="290" />
  </Dim>
  <Dim type="Height" >
    <AbsoluteDim value="250" />
  </Dim>
</Area>

The following shows <AbsoluteDim> in use as part of a dimension calculation sequence. In the example the left edge is being set to the width of the child widget 'myWidget' minus two pixels:

<Area>
  <Dim type="LeftEdge" >
    <WidgetDim widget="myWidget" dimension="Width" >
      <DimOperator op="Subtract" >
        <AbsoluteDim value="2" />
      </DimOperator>
    </WidgetDim>
  </Dim>
  ...
</Area>

Finally, we see <AbsoluteDim> as the starting dimension for a dimension calculation sequence. In the example, we are adding the value of some window property to the starting absolute value of six:

<Area>
  ...
  <Dim type="Height" >
    <AbsoluteDim value="6">
      <DimOperator op="Add" >
        <PropertyDim name="someHeightProperty" />
      </DimOperator>
    </AbsoluteDim>
  </Dim>
</Area>

<Area> Element

Purpose:

The <Area> element is a simple container element for the <Dim> dimension elements in order to form a rectangular area. <Area> is generally used to define target regions which are to be used for rendering imagery, text, to place a component child widget, or to form 'named' areas required by the base widget.

Attributes:

• <Area> has no attributes.

Usage:

• The <Area> element must contain either:
  • A single <AreaProperty> element that describes a URect type property where the final area can be obtained.
  • Four <Dim> elements:
    • One <Dim> element must define the left edge or x position.
    • One <Dim> element must define the top edge or y position.
    • One <Dim> element must define either the right edge or width.
    • One <Dim> element must define either the bottom edge or height.

• The <Area> element may appear in any of the following elements:
  • <Child> to define the target area to be occupied by a child widget.
  • <ImageryComponent> to define the target rendering area of an image.
  • <NamedArea> to define an area which can be retrieved by name.
  • <TextComponent> to define the target rendering area of some text.
  • <FrameComponent> to define the target rendering area for a frame.

Examples:

In this example we can see a named area being defined:

<NamedArea name="exampleArea" >
    <Area>
        <Dim type="LeftEdge"><AbsoluteDim value="0" /></Dim>
        <Dim type="TopEdge"><AbsoluteDim value="0" /></Dim>
        <Dim type="Width"><UnifiedDim scale="1.0" /></Dim>
        <Dim type="Height"><UnifiedDim scale="1.0" /></Dim>
    </Area>
</NamedArea>

<AreaProperty> Element

Purpose:

The <AreaProperty> element is intended to allow the system to access a property on the target window to obtain the final target area of a component being defined.

Attributes:

• name - specifies the name of the property to access. The named property must access a URect value. Required attribute.

Usage:

• The <AreaProperty> element may not contain sub-elements.
• The <AreaProperty> element may appear as a sub-element only within the main <Area> element.

<Child> Element

Purpose:

The <Child> element defines a component widget that will be created and added to each instance of any window using the <WidgetLook> being defined. Some base widgets have requirements for <Child> element definition that must be provided.

Attributes:

• type - specifies the widget type to create. Required attribute.
• nameSuffix - specifies a suffix which will be used when naming the widget. The final name of the child widget will be that of the parent with this suffix appended. Required attribute.
• look - specifies the name of a widget look to apply to the child widget. You should only use this if 'type' specifies a Falagard base widget type. Optional attribute.

Usage:

Note: the sub-elements should appear in the order that they are defined here.

• The <Child> element must contain an <Area> element that defines the location of the child widget in relation to the component being defined.
• You may optionally specify a single <VertAlignment> element to set the vertical alignment for the child.
• You may optionally specify a single <HorzAlignment> element to set the horizontal alignment for the child.
• You may specify any number of <Property> elements to set default values for any property supported by the widget type being used for the child.

• The <Child> element may only appear within the <WidgetLook> element.

Examples:

In this example, taken from TaharezLookSkin.looknfeel, we see how the title bar child widget required by the frame window type is defined:

<WidgetLook name="TaharezLook/FrameWindow">
  ...
  <Child type="TaharezLook/Titlebar" nameSuffix="__auto_titlebar__">
    <Area>
      <Dim type="LeftEdge" ><AbsoluteDim value="0" /></Dim>
      <Dim type="TopEdge" ><AbsoluteDim value="0" /></Dim>
      <Dim type="Width" ><UnifiedDim scale="1" type="Width" /></Dim>
      <Dim type="Height" >
        <FontDim type="LineSpacing">
          <DimOperator op="Multiply">
            <AbsoluteDim value="1.5" />
          </DimOperator>
        </FontDim>
      </Dim>
    </Area>
    <Property name="AlwaysOnTop" value="False" />
  </Child>
  ...
</WidgetLook>

<ColourProperty> Element

Purpose:

The <ColourProperty> element is intended to allow the system to access a property on the target window to obtain colour information to be used when drawing some part of the component being defined.

Attributes:

• name - specifies the name of the property to access. The named property must access a single colour value. Required attribute.

Usage:

• The <ColourProperty> element may not contain sub-elements.

• The <ColourProperty> element may appear as a sub-element within any of the following elements:
  • <ImageryComponent> to specify a modulating colour to be applied when rendering the image.
  • <ImagerySection> to specify a modulating colour to be applied to all imagery components within the imagery section as it is rendered.
  • <Section> to specify a modulating colour to be applied to all imagery in the named section as it is rendered.
  • <TextComponent> to specify a colour to use when rendering the text component.
  • <FrameComponent> to specify a colour to use when rendering the text frame.

Examples:

The following example, listing imagery for a button in the "Normal" state, shows the <ColourProperty> element in use to specify a property where colours to be used when rendering the ImagerySection named "label" can be found:

<StateImagery name="Normal">
  <Layer>
    <Section section="normal" />
    <Section section="label">
      <ColourProperty name="NormalTextColour" />
    </Section>
  </Layer>
</StateImagery>

<ColourRectProperty> Element

Purpose:

The <ColourRectProperty > element is intended to allow the system to access a property on the target window to obtain colour information to be used when drawing some part of the component being defined.

Attributes:

• name - specifies the name of the property to access. The named property must access a ColourRect value. Required attribute.

Usage:

• The <ColourRectProperty> element may not contain sub-elements.

• The <ColourRectProperty> element may appear as a sub-element within any of the following elements:
  • <ImageryComponent> to specify a modulating ColourRect to be applied when rendering the image.
  • <ImagerySection> to specify a modulating ColourRect to be applied to all imagery components within the imagery section as it is rendered.
  • <Section> to specify a modulating ColourRect to be applied to all imagery in the named section as it is rendered.
  • <TextComponent> to specify a ColourRect to use when rendering the text component.
  • <FrameComponent> to specify a ColourRect to use when rendering the text frame.

Examples:

...
<StateImagery name="SpecialState">
  <Layer>
    <Section section="special_main">
      <ColourRectProperty name="SpecialColours" />
    </Section>
  </Layer>
</StateImagery>
...

<Colours> Element

Purpose:

The <Colours> element is used to explicitly specify values for a ColourRect that should be used when rendering some part of the component being defined.

Attributes:

• topLeft - specifies a hex colour value, of the form "AARRGGBB", to be used for the top-left corner of the ColourRect. Required attribute.
• topRight - specifies a hex colour value, of the form "AARRGGBB", to be used for the top-right corner of the ColourRect. Required attribue.
• bottomLeft - specifies a hex colour value, of the form "AARRGGBB", to be used for the bottom-left corner of the ColourRect. Required attribute.
• bottomRight - specifies a hex colour value of the form "AARRGGBB", to be used for the bottom-right corner of the ColourRect. Required attribute.

Usage:

• The <Colours> element may not contain sub-elements.

• The <Colours> element may appear as a sub-element within any of the following elements:
  • <ImageryComponent> to specify a modulating ColourRect to be applied when rendering the image.
  • <ImagerySection> to specify a modulating ColourRect to be applied to all imagery components within the imagery section as it is rendered.
  • <Section> to specify a modulating ColourRect to be applied to all imagery in the named section as it is rendered.
  • <TextComponent> to specify a ColourRect to use when rendering the text component.
  • <FrameComponent> to specify a ColourRect to use when rendering the text frame.

Examples:

In this example, we see the <Colours> element used to specify the value 0xFFFFFF00 as the colour for all four corners of the colour rect to be used when rendering the image being defined:

...
<ImageryComponent>
  <Area>
    <Dim type="LeftEdge" ><AbsoluteDim value="0" /></Dim>
    <Dim type="TopEdge" ><AbsoluteDim value="0" /></Dim>
    <Dim type="Width" ><AbsoluteDim value="12" /></Dim>
    <Dim type="Height" ><AbsoluteDim value="24" /></Dim>
  </Area>
  <Image imageset="newImageset" image="FunkyComponent" />
  <Colours
    topLeft="FFFFFF00"
    topRight="FFFFFF00"
    bottomLeft="FFFFFF00"
    bottomRight="FFFFFF00"
  />
  <VertFormat type="Stretched" />
  <HorzFormat type="Stretched" />
</ImageryComponent>
...

<Dim> Element

Purpose:

The <Dim> element is intended as a container element for a single dimension of an area rectangle.

Attributes:

• type - specifies what the dimension being defined represents. This attribute should be set to one of the values defined for the DimensionType enumeration (see below). Required attribute.

Usage:

• The <Dim> element may only appear within the <Area> element.

• The <Dim> element may contain any of the following specialised dimension elements:
  • <AbsoluteDim>
  • <FontDim>
  • <ImageDim>
  • <PropertyDim>
  • <UnifiedDim>
  • <WidgetDim>

Examples:

<DimOperator> Element

Purpose:

The <DimOperator> element allows you to combine two of the specialised dimension specifier elements via a simple mathematical operator. Since the dimension used as the second operand may also contain a <DimOperator> it is possible to create quite complex operations. Of important note is the fact that in a large chain of operations, the calculations are done in reverse order. Also, there is no operator precedence as such, all operations are applied linearly.

Attributes:

• op - specifies one of the vales from the DimensionOperator enumeration indicating the mathematical operation to be performed. Required attribute.

Usage:

• A single <DimOperator> element may appear as a sub-element within any of the following specialised dimension elements:
  • <AbsoluteDim>
  • <FontDim>
  • <ImageDim>
  • <PropertyDim>
  • <UnifiedDim>
  • <WidgetDim>

• The <DimOperator> element may contain any of the following specialised dimension elements:
  • <AbsoluteDim>
  • <FontDim>
  • <ImageDim>
  • <PropertyDim>
  • <UnifiedDim>
  • <WidgetDim>

Examples:

The following multiplies two simple AbsoluteDim dimensions:

...
<AbsoluteDim value="10">
  <DimOperator op="Multiply">
    <AbsoluteDim value="4" />
  </DimOperator>
</AbsoluteDim>
...

The next example takes the height of the font used for the target window, adds four pixels and multiplies the result by two. Note the effectively reversed order and lack of 'normal' operator precedence, the operation performed will be:

(2 * (4 + LineSpacing))

and not:

((2 * 4) + LineSpacing)

...
<AbsoluteDim value="2">
  <DimOperator op="Multiply">
    <AbsoluteDim value="4">
      <DimOperator op="Add">
        <FontDim type="LineSpacing" />
      </DimOperator>
    </AbsoluteDim>
  </DimOperator>
</AbsoluteDim>
...

<Falagard> Element

Purpose:

The <Falagard> element is the root element in Falagard XML skin definition files. The element serves mainly as a container for <WidgetLook> elements

Attributes:

• Element <Falagard> has no attributes.

Usage:

• The <Falagard> element is the root element for Falagard skin files.
• The <Falagard> element may contain any number of <WidgetLook> elements.
• No element may contain <Falagard> elements as a sub-element.

Examples:

Here we just see the general structure of a Falagard XML file, notice that the <Falagard> element just serves as a container for multiple <WidgetLook> elements:

<?xml version="1.0" ?>
<Falagard>
  <WidgetLook name="TaharezLook/Button">
    ...
  </WidgetLook>
  <WidgetLook ... >
    ...
  </WidgetLook>
  ...
</Falagard>

<FontDim> Element

Purpose:

The <FontDim> element is used to take some measurement of a Font, and use it as a dimension component of an area rectangle.

Attributes:

• widget - specifies the name suffix of a child window to access when automatically obtaining the font or text string to be used when calculating the dimension's value. The final name used to access the widget will be that of the target window with this suffix appended. If this suffix is not specified, the target window itself is used. Optional attribute.
• type - specifies the type of font metric / measurement to use for this dimension. This should be set to one of the values from the FontMetricType enumeration. Required attribute.
• font - specifies the name of a font. If no font is given, the font will be taken from the target window at the time the dimension's value is taken. Optional attribute.
• string - For horizontal extents measurement, specifies the string to be measured. If no explicit string is given, the window text for the target window at the time the dimension's value is taken will be used instead. Optional attribute.
• padding - an absolute pixel 'padding' value to be added to the font metric value. Optional attribute.

Usage:

• The <FontDim> element may contain a single <DimOperator> element in order to form a dimension calculation.
• The <FontDim> element can appear as a sub-element in <Dim> to form a dimension specification for an area.
• The <FontDim> element can appear as a sub-element of <DimOperator> to specify the second operand for a dimension calculation.

Examples:

This first example just gets the line spacing for the window's current font:

<Dim type="Height">
  <FontDim type="LineSpacing" />
</Dim>

Now we take an extents measurement of the windows current text, using a specified font, and pad the result by ten pixels:

<Dim type="Width">
  <FontDim type="HorzExtent" font="Roman-14" padding="10" />
</Dim>

<FrameComponent> Element

Purpose:

The <FrameComponent> element is used to define an imagery frame using a maximum of eight images for the corners and edges, and a single, formatted, image for the background. Any of the images may be omitted if not required.

Attributes:

• No attributes are currently defined for the <FrameComponent> element.

Usage:

Note: the sub-elements should appear in the order that they are defined here.

• <Area> defining the target area for this frame.
• Up to nine <Image> elements specifying the images to be drawn and in what positions.
• Optionally specifying the colours for the entire frame, one of the colour elements:
  • <Colours>
  • <ColourProperty>
  • <ColourRectProperty>
• Optionally, to specify the vertical formatting to use for the frame background, either of:
  • <VertFormat>
  • <VertFormatProperty>
• Optionally, to specify the horizontal formatting to use for the frame background, either of:
  • <HorzFormat>
  • <HorzFormatProperty>

• The <FrameComponent> element may only appear as a sub-element of the element <ImagerySection>.

Examples:

The following defines a full frame and background. It is taken from the TaharezLook skin specification for the Listbox widget:

<FrameComponent>
  <Area>
    <Dim type="LeftEdge" ><AbsoluteDim value="0" /></Dim>
    <Dim type="TopEdge" ><AbsoluteDim value="0" /></Dim>
    <Dim type="Width" ><UnifiedDim scale="1" type="Width" /></Dim>
    <Dim type="Height" ><UnifiedDim scale="1" type="Height" /></Dim>
  </Area>
  <Image type="TopLeftCorner"
    imageset="TaharezLook" image="ListboxTopLeft"
  />
  <Image type="TopRightCorner"
    imageset="TaharezLook" image="ListboxTopRight"
  />
  <Image type="BottomLeftCorner"
    imageset="TaharezLook" image="ListboxBottomLeft"
  />
  <Image type="BottomRightCorner"
    imageset="TaharezLook" image="ListboxBottomRight"
  />
  <Image type="LeftEdge"
    imageset="TaharezLook" image="ListboxLeft"
  />
  <Image type="RightEdge"
    imageset="TaharezLook" image="ListboxRight"
  />
  <Image type="TopEdge"
    imageset="TaharezLook" image="ListboxTop"
  />
  <Image type="BottomEdge"
    imageset="TaharezLook" image="ListboxBottom"
  />
  <Image type="Background"
    imageset="TaharezLook" image="ListboxBackdrop"
  />
</FrameComponent>

<HorzAlignment> Element

Purpose:

The <HorzAlignment> element is used to specify the horizontal alignment option required for a child window element.

Attributes:

• type - specifies one of the values from the HorizontalAlignment enumeration indicating the desired horizontal alignment.

Usage:

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

Examples:

This example defines a scrollbar type child widget. We have used the <HorzAlignment> element to specify that the scrollbar appear on the far right edge of the component being defined:

...
<Child  type="MyLook/VertScrollbar" nameSuffix="__auto_vscrollbar__">
  <Area>
    <Dim type="LeftEdge" ><AbsoluteDim value="0" /></Dim>
    <Dim type="TopEdge" ><AbsoluteDim value="0" /></Dim>
    <Dim type="Width" ><AbsoluteDim value="15" /></Dim>
    <Dim type="Height" ><UnifiedDim scale="1" type="Height" /></Dim>
  </Area>
  <HorzAlignment type="RightAligned" />
</Child>
...

<HorzFormat> Element

Purpose:

The <HorzFormat> element is used to specify the required horizontal formatting for an image, frame, or text component.

Attributes:

• type - specifies the required horizontal formatting option. For use in ImageryComponents or FrameComponents, this will be one of the values from the HorizontalFormat enumeration. For use in TextComponents, this will one of the values form the HorizontalTextFormat enumeration.

Usage:

• The <HorzFormat> element may only appear as a sub-element of the <ImageryComponent>, <FrameComponent>, or <TextComponent> elements.
• The <HorzFormat> element may not contain any sub-elements.

Examples:

This first example shows an ImageryComponent definition. We use <HorzFormat> to specify that we want the image stretched to cover the entire width of the designated target area:

...
<ImageryComponent>
  <Area>
    <Dim type="LeftEdge" ><AbsoluteDim value="0" /></Dim>
    <Dim type="TopEdge" ><AbsoluteDim value="0" /></Dim>
    <Dim type="Width" ><AbsoluteDim value="25" /></Dim>
    <Dim type="Height" ><AbsoluteDim value="25" /></Dim>
  </Area>
  <Image imageset="myImageset" image="coolImage" />
  <VertFormat type="Stretched" />
  <HorzFormat type="Stretched" />
</ImageryComponent>
...

This second example is for a TextComponent. You can see <HorzFormat> used here to specify that we want the text centred within the target area, and word-wrapped where required:

<TextComponent>
  <Area>
    <Dim type="LeftEdge" ><AbsoluteDim value="0" /></Dim>
    <Dim type="TopEdge" ><AbsoluteDim value="0" /></Dim>
    <Dim type="RightEdge" ><UnifiedDim scale="1" type="Width" /></Dim>
    <Dim type="Height" ><UnifiedDim scale="1" type="Height" /></Dim>
  </Area>
  <HorzFormat type="WordWrapLeftAligned" />
</TextComponent>

<HorzFormatProperty> Element

Purpose:

The <HorzFormatProperty> element is intended to allow the system to access a property on the target window to obtain the horizontal formatting to be used when drawing the component being defined.

Attributes:

• name - specifies the name of the property to access. The named property must access a string value that will be set to one of the enumeration values appropriate for the component being defined (so HorizontalTextFormat for TextComponent, and HorizontalFormat for FrameComponent and ImageryComponent). Required attribute.

Usage:

• The <HorzFormatProperty> element may not contain sub-elements.

• The <HorzFormatProperty> element may appear as a sub-element within any of the following elements:
  • <ImageryComponent> to specify a horizontal formatting to be used the the image.
  • <FrameComponent> to specify a horizontal formatting to be used for the frame background.
  • <TextComponent> to specify a horizontal formatting to be used for the text.

Examples:

<Image> Element

Purpose:

The <Image> element is used to specify an Imageset and Image pair, and for FrameComponent images, how the image is to be used.

Attributes:

• imageset - specifies the name of an Imageset which contains the image to be used. Required attribute.
• image - specifies the name of the image from the specified Imageset to be used. Required attribute.
• type - Only for FrameComponent. Specifies the part of the frame that this image is to be used for. One of the values from the FrameImageComponent enumeration. Required attribute.

Usage:

• The <Image> element may only appear as a sub-element of the <ImageryComponent> or <FrameComponent> elements.
• The <Image> element may not contain any sub-elements.

Examples:

Here you can see the <Image> element used to specify the image to render for an ImageryComponent being defined:

...
<ImageryComponent>
  <Area>
    <Dim type="LeftEdge" ><AbsoluteDim value="0" /></Dim>
    <Dim type="TopEdge" ><AbsoluteDim value="0" /></Dim>
    <Dim type="Width" ><AbsoluteDim value="15" /></Dim>
    <Dim type="Height" ><UnifiedDim scale="1.0" type="Height" /></Dim>
  </Area>
  <Image imageset="FunkyLook" image="ButtonIcon" />
  <VertFormat type="CentreAligned" />
  <HorzFormat type="CentreAligned" />
</ImageryComponent>
...

<ImageDim> Element

Purpose:

The <ImageDim> element is used to define a component dimension for an area rectangle. <ImageDim> is used to specify some dimension of an image for use as an area dimension.

Attributes:

• imageset - specifies the name of an Imageset which contains the image to be used. Required attribute.
• image - specifies the name of the image from the specified Imageset to be used. Required attribute.
• dimension - specifies the image dimension to be used. This should be set to one of the values defined in the DimensionType enumeration. Required attribute.

Usage:

• The <ImageDim> element may contain a single <DimOperator> element in order to form a dimension calculation.
• The <ImageDim> element can appear as a sub-element in <Dim> to form a dimension specification for an area.
• The <ImageDim> element can appear as a sub-element of <DimOperator> to specify the second operand for a dimension calculation.

Examples:

This example shows a dimension that uses <ImageDim> to fetch the width of a specified image for use as the dimensions value:

...
<Area>
  <Dim type="LeftEdge">
    <ImageDim imageset="myImages" image="leftImage" dimension="width" />
  </Dim>
  ...
</Area>
...

<ImageryComponent> Element

Purpose:

The <ImageryComponent> element defines a single image to be drawn within a given ImagerySection. The ImageryComponent contains all information about which image is to be drawn, where it should be drawn, which colours are to be used and how the image should be formatted.

Attributes:

• No attributes are defined for the <ImageryComponent> element.

Usage:

Note: the sub-elements should appear in the order that they are defined here.

• <Area> defining the target area for this image.
• Either one of:
  • <Image> element specifying the image to be drawn.
  • <ImageProperty> element specifying a property defining the image to be drawn.
• Optionally specifying the colours for this single image, one of the colour elements:
  • <Colours>
  • <ColourProperty>
  • <ColourRectProperty>
• Optionally, to specify the vertical formatting to use, either of:
  • <VertFormat>
  • <VertFormatProperty>
• Optionally, to specify the horizontal formatting to use, either of:
  • <HorzFormat>
  • <HorzFormatProperty>

• The <ImageryComponent> element may only appear as a sub-element of the element <ImagerySection>.

Examples:

The following was taken from TaharezLookSkin.looknfeel and shows a full ImageryComponent definition:

<ImageryComponent>
   <Area>
    <Dim type="LeftEdge" ><UnifiedDim scale="0" type="LeftEdge" /></Dim>
    <Dim type="TopEdge" ><UnifiedDim scale="0.2" type="TopEdge" /></Dim>
    <Dim type="Width" ><UnifiedDim scale="1" type="Width" /></Dim>
    <Dim type="Height" ><UnifiedDim scale="0.3" type="Height" /></Dim>
  </Area>
  <Image imageset="TaharezLook" image="TextSelectionBrush" />
  <Colours
    topLeft="FFFFFF00"
    topRight="FFFFFF00"
    bottomLeft="FFFFFF00"
    bottomRight="FFFFFF00"
  />
  <VertFormat type="Tiled" />
  <HorzFormat type="Stretched" />
</ImageryComponent>

<ImageProperty> Element

Purpose:

The <ImageProperty> element is intended to allow the system to access a property on the target window to obtain the final image to be used when rendering the ImageryComponent being defined.

Attributes:

• name - specifies the name of the property to access. Required attribute. The named property must access a imageset & image value pair of the form:

“set:<imageset_name> image:<image_name>”

Usage:

• The <AreaProperty> element may not contain sub-elements.
• The <AreaProperty> element may appear as a sub-element only within the <ImageryComponent> element.

<ImagerySection> Element

Purpose:

The <ImagerySection> element is used to group multiple <ImageryComponent> and <TextComponent> definitions into named sections which can then be specified for use as imagery in state definitions.

Attributes:

• name - specifies the name to be given to this ImagerySection. Names are per-WidgetLook, and specifying the same name more than once will replace the previous definition. Required attribute.

Usage:

Note: the sub-elements should appear in the order that they are defined here.

• To optionally specify colours to be modulated with the individual component's colours, the <ImagerySection> may contain one of the colour definition elements:
  • <Colours>
  • <ColourProperty>
  • <ColourRectProperty>
• Any number of <FrameComponent> elements may then follow.
• Followed by any number of <ImageryComponent> elements.
• Finally, any number of <TextComponent> elements may be given

• The <ImagerySection> element may only appear as a sub-element of the <WidgetLook> element.

Examples:

<ImagerySection name="example">
  <ImageryComponent>
    <Area>
      <Dim type="LeftEdge" ><AbsoluteDim value="0" /></Dim>
      <Dim type="TopEdge" ><AbsoluteDim value="0" /></Dim>
      <Dim type="Width" ><AbsoluteDim value="15" /></Dim>
      <Dim type="Height" ><UnifiedDim scale="1.0" type="Height" /></Dim>
    </Area>
    <Image imageset="sillyImages" image="anotherImage" />
    <VertFormat type="Stretched" />
    <HorzFormat type="Stretched" />
  </ImageryComponent>
  <TextComponent>
    <Area>
      <Dim type="LeftEdge" ><AbsoluteDim value="0" /></Dim>
      <Dim type="TopEdge" ><AbsoluteDim value="0" /></Dim>
      <Dim type="Width" ><UnifiedDim scale="1" type="Width" /></Dim>
      <Dim type="Height" ><UnifiedDim scale="1" type="Height" /></Dim>
    </Area>
  </TextComponent>
</ImagerySection>

<Layer> Element

Purpose:

The <Layer> element is used to define layers of imagery within the definition of a StateImagery section.

Attributes:

• priority - specifies the priority for the layer. Higher priorities appear in front of lower priorities. Default priority is 0. Optional attribute.

Usage:

• The <Layer> element may only appear as a sub-element of the <StateImagery> element.
• The <Layer> element may contain any number of <Section> sub-elements.

Examples:

Here we see a single layer with multiple sections included. This example was taken from the TaharezLook skin XML file (ListHeaderSegment widget):

<StateImagery name="Normal">
  <Layer>
    <Section section="segment_normal" />
    <Section section="splitter_normal" />
    <Section section="label" />
  </Layer>
</StateImagery>

<NamedArea> Element

Purpose:

Defines an area that can be accessed via it's name. Generally this this used by base widgets to obtain skin supplied areas for use in rendering or other widget specific operations.

Attributes:

• name - specifies a name for the area being defined. Required attribute.

Usage:

• The <NamedArea> element must contain only an <Area> sub-element defining the area rectangle for the named area.
• The <NamedArea> element may only appear as a sub-element within <WidgetLook> elements.

Examples:

This example defines a named area called "TextArea". It is defined as being an area seven pixels inside the total area of the widget being defined:

<NamedArea name="TextArea">
  <Area>
    <Dim type="LeftEdge" >
      <AbsoluteDim value="7" />
    </Dim>
    <Dim type="TopEdge" >
      <AbsoluteDim value="7" />
    </Dim>
    <Dim type="RightEdge" >
      <UnifiedDim scale="1.0" offset="-7" type="RightEdge" />
    </Dim>
    <Dim type="BottomEdge" >
      <UnifiedDim scale="1.0" offset="-7" type="BottomEdge" />
    </Dim>
  </Area>
</NamedArea>

<Property> Element

Purpose:

The <Property> element is used to initialise a property on a window or widget being defined.

Attributes:

• name - specifies the name of the property to be initialised. Required attribute.
• value - specifies the value string to be used when initialising the property. Required attribute.

Usage:

• The <Property> element may not contain any sub-elements.
• The <Property> element may appear as a sub-element in <WidgetLook> elements to define property initialisers for the type being defined.
• The <Property> element may appear as a sub-element in <Child> elements to define property initialisers for the child widget being defined.

Examples:

In this extract from the definition for TaharezLook/Titlebar, we can see the <Property> element used to set the "CaptionColour" property; this establishes a default for all instances of this widget:

<WidgetLook name="TaharezLook/Titlebar">
  <Property name="CaptionColour" value="FFFFFFFF" />
  <ImagerySection name="main">
    <ImageryComponent>
      <Area>
        <Dim type="LeftEdge" ><AbsoluteDim value="0" /></Dim>
        ...
      </Area>
    ...
    </ImageryComponent>
  </ImagerySection>
  ...
</WidgetLook>