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

<Affector> Element

• Purpose:
  • 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:
  • property: Required attribute that specifies the name of the property that will be changed by this affector.
  • 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.
  • 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:
  • The <Affector> element may only appear as a sub-element of the <AnimationDefinition> element.
  • The <Affector> element may contain one or more <KeyFrame> elements.

• Examples:
  • TODO

<AnimationDefinition> Element

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

• Attributes:
  • name: Required attribute that specifies a system-unique name for the animation.
  • duration: Required attribute that specifies the overall duration of the animation in seconds.
  • 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.
  • 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:
  • The <AnimationDefinition> element may appear as a sub-element of either a root <Animations> element, or within a Falagard system <WidgetLook> element.
  • The <AnimationDefinition> element must contain at least one <Affector> sub-element.
  • The <AnimationDefinition> element may then contain zero or more <Subscription> sub-elements.

• Examples:
  • TODO

<Animations> Element

• Purpose:
  • 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:
  • None.

• Usage:
  • The <Animations> element may not appear as a sub-element of any other elements.
  • The <Animations> element may contain only <AnimationDefinition> elements as sub-elements (any number).

• Examples:
  • TODO

<KeyFrame> Element

• Purpose:
  • 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:
  • 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.
  • 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.
  • 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.
  • 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:
  • The <KeyFrame> element may only appear as sub-elements of the <Affector> element.
  • The <KeyFrame> element may not contain any sub-elements.

• Examples:
  • TODO

<Subscription> Element

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

• Attributes:
  • event: Required attribute that specifies the event that will trigger the given action.
  • 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:
  • The <Subscription> element may only appear as a sub-element of the <AnimationDefinition> element.
  • The <Subscription> element may not contain any sub-elements.

• Examples:
  • TODO