CEGUI各文件格式

Scheme XML files.

Author:

Paul D Turner

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

Overview

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

· Purpose: 

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

· Attributes: 

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

· Usage: 

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

· Examples: 

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

<GUIScheme> Element

· Purpose: 

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

· Attributes: 

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

· Usage: 

o The <GUIScheme> element is the root element for scheme files.

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

o No element may contain a <GUIScheme> element as a sub-element.

· Examples:

<FalagardMapping> Element

· Purpose: 

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

· Attributes: 

o WindowType:Specifies a name for the mapping / window type being created. Required attribute.

o TargetType:Specifies the name of the concrete CEGUI::Window based object that contains the logic for the window type being specified. Required attribute.

o Renderer:Specifies the name of the concrete CEGUI::WindowRenderer based object that contains the rendering specific code for the window type being specified. Required attribute.

o LookNFeel:Specifies the name of the Falagard WidgetLook definition that contains imagery and other definitions for the window type being specified. Required attribute.

o RenderEffect:Specifies the name of a registered RenderEffect of which an instance will be created to be associated with each created window of WindowType. As the use of a RenderEffect requires an underlying RenderingWindow, if this is not automaticaly created by the TargetType, Renderer or LookNFeel the AutoRenderingSurface will be enabled prior to creating and assigning the RenderEffect. If the specified RenderEffect is not registered with the system when instantiation of TargetType is attempted, creation will not fail solely for lack of the effect - rather the window will be created with no effect set (the missing RenderEffect will be logged). Optional attribute.

· Usage: 

o The <FalagardMapping> element may only appear as a sub-element of the <GUIScheme> element.

o The <FalagardMapping> element may not contain any sub-elements.

· Examples:

<Font> Element

· Purpose: 

o 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: 

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

o Filename:Specifies the path to the font XML file. Required attribute.

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

· Usage: 

o The <Font> element may only appear as a sub-element of the <GUIScheme> element.

o The <Font> element may not contain any sub-elements.

· Examples:

<Imageset> Element

· Purpose: 

o 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: 

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

o Filename:Specifies the path to the imageset XML file. Required attribute.

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

· Usage: 

o The <Imageset> element may only appear as a sub-element of the <GUIScheme> element.

o The <Imageset> element may not contain any sub-elements.

· Examples:

<ImagesetFromImage> Element

· Purpose: 

o 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: 

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

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

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

· Usage: 

o The <ImagesetFromImage> element may only appear as a sub-element of the <GUIScheme> element.

o The <ImagesetFromImage> element may not contain any sub-elements.

· Examples:

<LookNFeel> Element

· Purpose: 

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

· Attributes: 

o Filename:Specifies the path to the looknfeel xml file that will be parsed. Required attribute.

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

· Usage: 

o The <LookNFeel> element may only appear as a sub-element of the <GUIScheme> element.

o The <LookNFeel> element may not contain any sub-elements.

· Examples:

<WindowAlias> Element

· Purpose: 

o Specifies an alias for a given window type.

· Attributes: 

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

o Target:Specifies the window type that will be created when a window of the type specified by the attribute Alias is specified.

· Usage: 

o The <WindowAlias> element may only appear as a sub-element of the <GUIScheme> element.

o The <WindowAlias> element may not contain any sub-elements.

· Examples:

<WindowFactory> Element

· Purpose: 

o 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: 

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

· Usage: 

o The <WindowFactory> element may only appear as a sub-element of the <WindowSet> element.

o The <WindowFactory> element may not contain any sub-elements.

· Examples:

<WindowRendererFactory> Element

· Purpose: 

o 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: 

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

· Usage: 

o The <WindowRendererFactory> element may only appear as a sub-element of the <WindowRendererSet> element.

o The <WindowRendererFactory> element may not contain any sub-elements.

· Examples:

<WindowRendererSet> Element

· Purpose: 

o Specifies the name of a loadable module containing concrete CEGUI::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: 

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

· Usage: 

o The <WindowRendererSet> element may only appear as a sub-element of the <GUIScheme> element.

o The <WindowRendererSet> element may not any number of <WindowRendererFactory> sub-elements.

· Examples:

<WindowSet> Element

· Purpose: 

o Specifies the name of a loadable module containing concrete CEGUI::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: 

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

· Usage: 

o The <WindowSet> element may only appear as a sub-element of the <GUIScheme> element.

o The <WindowSet> element may not any number of <WindowFactory> sub-elements.

· Examples:

Font XML files.

Author:

Paul D Turner

Font files can define one of two types of font:

· A FreeType font, which is based upon standard font files - such as .ttf files - where glyphs get dynamically rendered to an internal cache as needed.

· A Pixmap font, which is based on an Imageset that contains the predrawn bitmap representations of the character glyphs the font will render.

Overview

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

· Purpose: 

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

· Attributes: 

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

· Usage: 

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

· Examples: 

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

<Font> Element

· Purpose: 

o The <Font> element is the root element in XML font definition files.

· Attributes: 

o Type:Specifies the type of font being defined. This should be one of the following values: 

§ FreeType:Indicates a font based upon a standard font file (such as a true-type '.ttf' font).

§ Pixmap:Indicates a font based upon an Imageset which defines Images for the font glyphs.

o Name:Specifies the name that will be used to identify the Font within the CEGUI system. Required attribute.

o Filename:Specifies the path to the associated resource for the font. Required attribute. 

§ For FreeType type fonts this should reference a standard font file loadable by the freetype2 library (such as a .ttf file, or similar).

§ For Pixmap type fonts this should reference an an Imageset.

o ResourceGroup:Specifies the resource group identifier to pass to the ResourceProvider when loading the file given in the Filename attribute. For Pixmap type fonts, this may be the special value "*" to indicate the Imagseset specified in Filename is actually the name of an already loaded Imagesest rather than the name of an Imageset XMl file to be loaded. Optional attribute.

o Size:Specifies the point size for a FreeType type font. This is ignored for Pixmap type fonts. Optional attribute, default is 12.

o AntiAlias:Boolean attribute that states whether the font should be rendered anti-aliased. This setting only affects FreeType type fonts. Optional attribute, default is true.

o AutoScaled:Boolean attribute that states whether to scale imagery so it appears the same physical size at any resolution. The specified native resolution values indicate the resolution that will result in a one-to-one (i.e. unscaled) mapping from source to destination. At resolutions higher than the native, the imagery will be scaled up to take up more space, and at resolutions lower than the native, the imagery will be scaled down to take up less space. Optional attribute, default is false.

o NativeHorzRes:When AutoScaled is enabled, specifies the horizontal screen resolution that will result in an unscaled, one-to-one mapping of pixels from the source image to the destination surface. Optional attribute, default is 640.

o NativeVertRes:When AutoScaled is enabled, specifies the vertical screen resolution that will result in an unscaled, one-to-one mapping of pixels from the source image to the destination surface. Optional attribute, default is 480.

o LineSpacing:Specifies a line spacing value to be used in preference to what is extracted from the underlying font file (useful if the font file is made with a bad line spacing value). If set to zero, the value from the underlying font file is used instead. This setting only affects FreeType type fonts. Optional attribute, default is 0.

· Usage: 

o The <Font> element is the root element for font files.

o The <Font> element may contain any number of <Mapping> elements.

o No element may contain a <Font> element as a sub-element.

· Examples:

<Mapping> Element

· Purpose: 

o The <Mapping> element is used only with Pixmap type fonts and 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.

· Attributes: 

o Codepoint:Specifies the Unicode codepoint to produce a mapping for. Required attribute.

o Image:Specifies the name of the image to map to the codepoint specified in Codepoint. This named image must be defined for the Imageset identified in the Filename attribute of the containing <Font> element.

o HorzAdvance:Specifies a number of pixels to advance the 'pen' position after rendering the image specified in this mapping. A value of -1 will cause an appropriate value to be auto-calculated. Optional attribute, default is -1.

· Usage: 

o The <Mapping> element may only appear as a sub-element of the <Font> element.

o The <Mapping> element may not contain any sub-elements.

· Examples:

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.

Layout Element List:

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

Overview

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

· Purpose: 

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

· Attributes: 

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

· Usage: 

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

· Examples: 

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

<GUILayout> Element

· Purpose: 

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

· Attributes: 

o 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: 

o The <GUILayout> element is the root element for layout files.

o The <GUILayout> element must contain a single <Window> element.

o No element may contain a <GUILayout> element as a sub-element.

· Examples:

<Window> Element

· Purpose: 

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

· Attributes: 

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

o 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: 

o The <Window> may appear as a sub-element of the following: 

§ <GUILayout> elements.

§ <Window> elements.

§ <AutoWindow> elements.

o 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:

<Property> Element

· Purpose: 

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

· Attributes: 

o Name:Specifies the name of the property to set. Required attribute.

o 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: 

o The <Property> may appear as a sub-element of <Window> elements and <AutoWindow> elements.

o The <Property> element may not contain any sub-elements.

o The <Property> element may contain text content to be used as the value.

· Examples:

<Event> Element

· Purpose: 

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

· Attributes: 

o Name:Specifies the name of the event to which the handler function specified by the Function attribute will be subscribed. Required attribute.

o Function:Specifis the name of a script function to be subscribed to the event specified by the Name attribute. Required attribute.

· Usage: 

o The <Event> may appear as a sub-element of <Window> elements and <AutoWindow> elements.

o The <Event> element may not contain any sub-elements.

· Examples:

<LayoutImport> Element

· Purpose: 

o 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: 

o Filename:Specifies the path to the xml layout file to be imported. Required attribute.

o Prefix:Specifies a prefix that will be prepended to the window name of each window created from the imported layout. Optional attribute.

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

· Usage: 

o The <LayoutImport> may appear as a sub-element of <Window> elements and <AutoWindow> elements.

o The <LayoutImport> element may not contain any sub-elements.

· Examples:

<AutoWindow> Element

· Purpose: 

o 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: 

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

· Usage: 

o The <AutoWindow> may appear as a sub-element of the following: 

§ <Window> elements.

§ <AutoWindow> elements.

o 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:

Animation XML files.

Author:

Paul D Turner

Animation XML files allow the specification of animations for CEGUI, which can later be instantiated and targetted to specific GUI elements. The same system and XML formats are also valid as part of Falagard WidgetLook definitions.

Animation XML Element List:

<Affector> Element
<AnimationDefinition> Element
<Animations> Element
<KeyFrame> Element
<Subscription> Element

Overview

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

· Purpose: 

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

· Attributes: 

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

· Usage: 

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

· Examples: 

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

<Affector> Element

· Purpose: 

o The <Affector> element specifies the name of a property that will be affected (have it's value changed) as part of the animation and how the changes are to be applied to that property over time.

· Attributes: 

o property:Required attribute that specifies the name of the property that will be changed by this affector.

o applicationMethod:Optional attribute that specifies how interpolated property values are to be applied. Valid options are: 

§ "absolute": The interpolated value is set as the new property value (default setting).

§ "relative": The interpolated value is added to the starting value of the property.

§ "relative multiply": The interpolated value is multiplied with the starting value of the property.

o interpolator:Required attribute that specifies the name of the interpolator that will interpret the property value to smoothly transition from one key frame value to another. The interpolator name specified must be registered with the system. Stock interpolators are provided for the following: 

§ "bool"

§ "colour"

§ "ColourRect"

§ "float"

§ "int"

§ "Point"

§ "Rect"

§ "Size"

§ "String"

§ "UBox"

§ "UDim"

§ "uint"

§ "URect"

§ "UVector2"

§ "Vector3"

· Usage: 

o The <Affector> element may only appear as a sub-element of the <AnimationDefinition> element.

o The <Affector> element may contain one or more <KeyFrame> elements.

· Examples: 

o TODO

<AnimationDefinition> Element

· Purpose: 

o The <AnimationDefinition> element is used to define a single named animation that can be instantiated and applied to GUI elements.

· Attributes: 

o name:Required attribute that specifies a system-unique name for the animation.

o duration:Required attribute that specifies the overall duration of the animation in seconds.

o replayMode:Optional attribute that specifies if and how the animation will be replayed / repeated. Acceptable values are: 

§ "loop": Animation plays through, then restarts from the beginning (default setting).

§ "once": Animation plays one time and then stops.

§ "bounce": Animation plays forwards and then backwards in a continual cycle.

o autoStart:Optional boolean attribute that specifies whether the animation will start playing immediately. Default value is 'false' which means some external event must trigger the animation if it is to be seen.

· Usage: 

o The <AnimationDefinition> element may appear as a sub-element of either a root <Animations> element, or within a Falagard system <WidgetLook> element.

o The <AnimationDefinition> element must contain at least one <Affector> sub-element.

o The <AnimationDefinition> element may then contain zero or more <Subscription> sub-elements.

· Examples: 

o TODO

<Animations> Element

· Purpose: 

o The <Animations> element is the root element in an animations XML file and it's purpose is to contain any number of <AnimationDefinition> elements.

· Attributes: 

o None.

· Usage: 

o The <Animations> element may not appear as a sub-element of any other elements.

o The <Animations> element may contain only <AnimationDefinition> elements as sub-elements (any number).

· Examples: 

o TODO

<KeyFrame> Element

· Purpose: 

o The <KeyFrame> element is used to specify the value of the affected property at a given time position. Key frames can use values of properties of the affected window. If the source property is not empty, the properties value is saved when animation starts and used as the value for this key frame.

· Attributes: 

o position:Required attribute that specifies the time interval within the animation at which point the value for this key frame should be reached. This value should be between zero and the total duration of the animation being defined.

o value:Optional attribute that specifies a value for the affected property that should be in effect at the specified position within the animation. If this attribute is not given, you should specify the sourceProperty attribute.

o sourceProperty:Optional attribute specifying the name of a property from which the target value of this key frame will be fetched. If this attribute is not specified, you should specify the value attribute.

o progression:Optional attribute indicating the method of progression towards this key frame value over time. The available options are: 

§ "linear"(default value(.

§ "discrete"

§ "quadratic accelerating"

§ "quadratic decelerating"

· Usage: 

o The <KeyFrame> element may only appear as sub-elements of the <Affector> element.

o The <KeyFrame> element may not contain any sub-elements.

· Examples: 

o TODO

<Subscription> Element

· Purpose: 

o The <Subscription> element defines a subscription to an event on the target EventSet that will trigger a specified action for the animation.

· Attributes: 

o event:Required attribute that specifies the event that will trigger the given action.

o action:Required attribute that specifies the action that will be taken when the specified event is fired. Possible values are: 

§ "Start"

§ "Stop"

§ "Pause"

§ "Unpause"

§ "TogglePause"

· Usage: 

o The <Subscription> element may only appear as a sub-element of the <AnimationDefinition> element.

o The <Subscription> element may not contain any sub-elements.

· Examples: 

o TODO

Imageset XML files.

Author:

Paul D Turner

An Imageset is a collection of named regions upon some source surface, such as an image file or texture. In CEGUI terminology, each of these named regions is an Image and is the basic level of imagery used by CEGUI.

Overview

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

· Purpose: 

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

· Attributes: 

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

· Usage: 

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

· Examples: 

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

<Imageset> Element

· Purpose: 

o The <Imageset> element is the root element in XML imageset definition files.

· Attributes: 

o Name:Specifies the name that will be assigned to the Imageset in the CEGUI system. Required Attribute.

o Imagefile:Specifies the path to the image file containing the imagery for the imageset. Required attribute.

o ResourceGroup:Specifies the resource group identifier to pass to the ResourceProvider when loading the file given in the Imagefile attribute. Optional attribute, default is the Imageset default group.

o AutoScaled:Boolean property that states whether to scale imagery so it appears the same physical size at any resolution. The specified native resolution values indicate the resolution that will result in a one-to-one (i.e. unscaled) mapping from source to destination. At resolutions higher than the native, the imagery will be scaled up to take up more space, and at resolutions lower than the native, the imagery will be scaled down to take up less space. Optional attribute, default is false.

o NativeHorzRes:When AutoScaled is enabled, specifies the horizontal screen resolution that will result in an unscaled, one-to-one mapping of pixels from the source image to the destination surface. Optional attribute, default is 640.

o NativeVertRes:When AutoScaled is enabled, specifies the vertical screen resolution that will result in an unscaled, one-to-one mapping of pixels from the source image to the destination surface. Optional attribute, default is 480.

· Usage: 

o The <Imageset> element is the root element for imageset files.

o The <Imageset> element may contain any number of <Image> elements.

o No element may contain <Imageset> elements as a sub-element.

· Examples:

<Image> Element

· Purpose: 

o Defines a single component image of an imageset.

· Attributes: 

o Name:Specifies the name that will be used to identify the image within the Imageset. Required attribute.

o XPos:Specifies the X pixel co-ordinate of the top-left corner of the image on the source surface. Required attribute.

o YPos:Specifies the Y pixel co-ordinate of the top-left corner of the image on the source surface. Required attribute.

o Width:Specifies the width of the image in pixels. Required attribute.

o Height:Specifies the height of the image in pixels. Required attibute.

o XOffset:Specifies a horizontal offset to apply when rendering the image. Optional attribute, default is 0.

o YOffset:Specifies a vertical offset to apply when rendering the image. Optional attribute, default is 0.

· Usage: 

o The <Image> element may only appear as a sub-element of the <Imageset> element.

o The <Image> element may not contain any sub-elements.

· Examples: