/**
@page xml_layout Layout XML files.
@author Paul D Turner

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

@section xml_layout_contents Layout Element List:
@ref xml_layout_autowindow <br>
@ref xml_layout_event <br>
@ref xml_layout_guilayout <br>
@ref xml_layout_layoutimport <br>
@ref xml_layout_property <br>
@ref xml_layout_window <br>

<br>
@section xml_layout_overview Overview
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.

<br>
@section xml_layout_guilayout \<GUILayout\> Element
- Purpose:
    - \<GUILayout\> is the root element in layout XML files.

- Attributes:
    - @c 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.

- Usage:
    - 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.

- Examples:

<br>
@section xml_layout_window \<Window\> Element
- Purpose:
    - The \<Window\> element is used to specify a new window object to be
      created.

- Attributes:
    - @c 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.
    - @c 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.

- Usage:
    - The \<Window\> 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).

- Examples:

<br>
@section xml_layout_property \<Property\> Element
- Purpose:
    - The \<Property\> element is used to set properties on the Window created
      by the containing \<Window\> element.

- Attributes:
    - @c Name: Specifies the name of the property to set.  Required attribute.
    - @c 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.

- Usage:
    - The \<Property\> 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.

- Examples:

<br>
@section xml_layout_event \<Event\> Element
- Purpose:
    - The Event element is used to create bindings between GUI elements and
      script functions.

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

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

- Examples:

<br>
@section xml_layout_layoutimport \<LayoutImport\> Element
- Purpose:
    - 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:
    - @c Filename: Specifies the path to the xml layout file to be imported.
      Required attribute.
    - @c Prefix: Specifies a prefix that will be prepended to the window name of
      each window created from the imported layout.  Optional attribute.
    - @c ResourceGroup: Specifies the resource group identifier to pass to the
      ResourceProvider when loading the file given in the @c Filename attribute.
      Optional attribute, default is the WindowManager default group.

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

- Examples:

<br>
@section xml_layout_autowindow \<AutoWindow\> Element
- Purpose:
    - 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:
    - @c NameSuffix: Specifies the name suffix of the target auto-window.
      Required attribute.

- Usage:
    - The \<AutoWindow\> 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).

- Examples:

*/
