The Kanzi animation system consists of animations and timelines: animations define how the values of specific type change in time, and timelines map the animations to properties of objects you want to animate.

The Timeline class defines common properties which specify how the playback of a timeline is performed. These properties include timeline TimelineStartTime "start time", content TimelineClipStartTimeClipDuration "clip start time and clip duration", TimelineRepeatCount "repeat count" and so on. Actual classes inherited from the Timeline class define how animations are applied to the properties of objects. For an example of actual classes see PropertyAnimationTimeline, PropertyFieldAnimationTimeline or ParallelTimeline.

Timeline is a series of iterations played successively starting from specified start time. Each iteration is a continuous portion of timeline content which is played in a specific manner. Timeline content can be a single animation (as in PropertyAnimationTimeline), several animations which are animating fields of a single property (as in PropertyFieldAnimationTimeline) or even other timelines (as in ParallelTimeline).

To specify the time at which the first iteration of a timeline starts to play, set the start time property of the timeline. Start time is defined in the time space of the clock where the playback of this timeline is added or in the time space of its parent playback. Start time can be positive or negative. Negative start time causes the timeline to act like it started at some time in the past. It can cause the timeline to start as if it was half-way finished. The default value for start time is 0 milliseconds.

To retrieve the start time of Timeline call its getStartTime() function.

To specify the portion of timeline content played in an iteration set the clip start time and clip duration properties of the timeline. Clip start time and clip duration are defined in the time space of the timeline content. By default, the whole timeline content is played in a single iteration.

To set the clip start time and clip duration of Timeline call its setClipStartTime() and setClipDuration()

To retrieve the clip start time and clip duration of Timeline call its getClipStartTime() and getClipDuration() functions. Note that getClipDuration() can return empty optional, meaning that clip duration is not specified.

To scale the portion of timeline content played in an iteration up or down, set the duration scale property of the timeline. By default, the value of duration scale is 1 which means that timeline content is not scaled. If duration scale is larger than 1, timeline content is scaled up when it is played in an iteration. For example, if you set duration scale to 2, timeline content is played at half speed and the duration of the iteration is twice as long as normally. If duration scale is less than 1, timeline content is scaled down when it is played. For example, if you set duration scale to 0.5, timeline content is played twice as fast as normally and iteration duration is half of the normal. Timeline duration scale cannot be negative or zero. If you set the duration scale to such a value, the timeline will clamp it to the minimum allowed scale value. Timeline duration scale does not affect the start time of the timeline.

To retrieve the duration scale of Timeline call its getDurationScale() function.

Timeline content in an iteration can be played in either normal or reverse direction. By default (or if you set the direction behavior property of the timeline to Timeline::DirectionBehaviorNormal) the content is played in normal direction. If you set the direction behavior property of the timeline to Timeline::DirectionBehaviorReverse, each iteration plays its portion of timeline content in reverse manner, that is, from the end to the beginning of the content portion. If you set direction behavior to Timeline::DirectionBehaviorPingPong, then each odd iteration plays its content normally and each even iteration plays its content in reverse manner.

To set the direction behavior of Timeline to one of the values from Timeline::DirectionBehavior call Timeline's

To retrieve the direction behavior of Timeline call its getDirectionBehavior() function.

The number of iterations in a timeline is affected by several properties of the timeline. In general, to define how many iterations should be played in a timeline set its repeat count property. But if the direction behavior of the timeline is set to Timeline::DirectionBehaviorPingPong, then each iteration has two sub-iterations (the first sub-iteration plays its portion of the timeline content in normal direction and the second one plays it in reverse direction), so the number of iterations defined by repeat count is doubled. For example, if you set repeat count to 10 and direction behavior to Timeline::DirectionBehaviorPingPong, the number of iterations in the timeline becomes 20. If you set repeat count to 0, the number of iterations in timeline becomes infinite.

To retrieve the repeat count of Timeline call its getRepeatCount() function.

To perform playback of Timeline, create a TimelinePlayback object by calling the createPlayback() function of Timeline. After that you add playback to a TimelineClock by calling its TimelineClock::addTimelinePlayback() function. TimelineClock will advance the global time of the TimelinePlayback object which in turn will advance Timeline.

Do not change the properties of a timeline after you have added its playback to a clock. Changing any timeline property after its playback is added to a clock will result in undefined behavior.

Inherits properties and message types from TimelineMetadata.