Duration structure

Applies to Windows and Windows Phone

Represents the duration of time that a Timeline is active, or more generally represents a duration of time that also supports two special values Automatic and Forever.

Syntax


public struct Duration


<object property="[days.]hours:minutes:seconds[.fractionalSeconds]"/>
-or-
<object property="Automatic" .../>
-or-
<object property="Forever" .../>
 

XAML Values

days

An integer value greater than or equal to 0 that specifies the number of days.

hours

An integer value between 0 and 23 that specifies the number of hours. If you specify a Duration as a XAML attribute, an hours component is required, even if it is 0.

minutes

An integer value between 0 and 59 that specifies the number of minutes. Set hours:minutes components as "0:0" if you are setting only a seconds component.

seconds

An integer value between 0 and 59 that specifies the number of seconds. Set hours:minutes components as "0:0" if you are setting only a seconds component.

fractionalSeconds

Optional. A decimal value consisting of 1 to 7 positions past the decimal point, which specifies fractional seconds.

Automatic

The literal string "Automatic".

Forever

The literal string "Forever".

Attributes

[Version(0x06020000)]
[WebHostHidden()]

Members

The Duration structure has these types of members:

Constructors

The Duration structure has these constructors.

ConstructorDescription
Duration Initializes a new instance of the Duration structure with the supplied TimeSpan value.

 

Fields

The Duration structure has these fields.

FieldData typeDescription
TimeSpan

System.TimeSpan [.NET] | Windows::Foundation::TimeSpan [C++]

The TimeSpan value component.

Type

DurationType

The type as a member of the enumeration.

 

Methods

The Duration structure has these methods. It also inherits methods from the Object class.

MethodDescription
Add [C#, VB]Adds the value of the specified Duration to this Duration.
Compare Compares one Duration value to another.
Equals(Duration) [C#, VB]Compares two Duration structures for equality.
Equals(Duration,Duration) [C#, VB]Compares two Duration structures for equality, as a static helper method.
Equals(Object) [C#, VB]Determines whether the specified object is equal to a Duration.
GetHashCode [C#, VB]Gets a hash code for this object.
Subtract [C#, VB]Subtracts the specified Duration from this Duration.
ToString [C#, VB]Converts a Duration to a String representation.

 

Operators

The Duration structure has these operators.

OperatorDescription
Addition Adds the values of two Duration structures.
Equality Compares two Duration structures for equality.
GreaterThan Determines if one Duration is greater than another.
GreaterThanOrEqual Determines if one Duration is greater than or equal to another.
Implicit Implicitly creates a Duration from a given TimeSpan.
Inequality Compares two Duration structures for inequality.
LessThan Determines if one Duration is less than another.
LessThanOrEqual Determines if one Duration is less than or equal to another.
Subtraction Subtracts the value of one Duration from another.
UnaryPlus Returns the specified Duration.

 

Properties

The Duration structure has these properties.

PropertyAccess typeDescription

Automatic

Read-onlyGets a Duration value that is automatically determined.

Forever

Read-onlyGets a Duration value that represents an infinite interval.

HasTimeSpan

Read-onlyGets a value that indicates if this Duration represents a TimeSpan value.

TimeSpan

Read-onlyGets the TimeSpan value that this Duration represents.

 

Remarks

A Duration value is used for these properties:

For more info on how to use a Duration as part of a Timeline, including code examples, see Storyboarded animations or Timeline.Duration.

The most common way to use a Duration value in the Windows Runtime is to set it using a XAML attribute. When you set a value in XAML, you're supplying a string, and the string is parsed using the hours:minutes:seconds string format and its variants as is described in the XAML Syntax sections near the beginning of this reference topic.

Specifying a Duration using a string that resembles an integer, without any literal characters used in the hours:minutes:seconds string format such as : or . will result in a Duration of that number of days! This is seldom the intended result. Usually you specify animation durations in seconds. As such, the Duration string must include preceding 0 values for hours and minutes, with literal : characters as separators between hours and minutes, and between minutes and seconds. For example, to specify a Duration of five seconds, the correct string for either or a XAML attribute value is "0:0:5" ("0:0:05" is equivalent).

If you're using a Duration in code, a Duration uses a definition of time that is also used by the TimeSpan structure. The TimeSpan structure is represented by System.TimeSpan if you are programming using C# or Microsoft Visual Basic, or Windows.Foundation.TimeSpan if you are programming using C++.

  • The C# or Visual Basic System.TimeSpan has a Parse method that use hours:minutes:seconds string format. If you need to create a Duration value in code you can call the Duration constructor and provide the System.TimeSpan argument by calling TimeSpan.Parse with an hours:minutes:seconds string. Always use the "en-us" culture for parsing this string, because that's how XAML interprets the string format, and you shouldn't be using culture-specific inputs for animating timings anyways.
  • The C++ Windows.Foundation.TimeSpan doesn't support a way to create it in an hours:minutes:seconds string format. You'll have to use DurationHelper.FromTimeSpan, and do the conversion yourself for how hours:minutes:seconds converts to the C++ Windows.Foundation.TimeSpan data value, which is a value in milliseconds.

Notes on XAML syntax

In the grammar shown in the XAML attribute usage, [] indicates optional values, the [] (square brackets) are not literals. The : (colon) and . (period) characters are both literals, and delimit the h:m:s string form of a common time span, or the optional days and fractionalSeconds values.

Use the literal strings "Automatic" and "Forever" as XAML attribute values if you want a Duration that has behavior as documented by Duration.Automatic and Duration.Forever.

Duration does not support an object element syntax, and you cannot declare a Duration as a shareable item in a ResourceDictionary.

Projection and members of Duration

If you are using a Microsoft .NET language (C# or Visual Basic), or in Visual C++ component extensions (C++/CX), then Duration has non-data members available, and its data members are exposed as read-write properties, not fields. Duration exposes several operators, including comparison operators.

For .NET, Duration exposes TimeSpan.Parse for its TimeSpan, Implicit and UnaryPlus operators, and Add and Subtract methods. These aren't available from the structure in C++/CX but you can use equivalent DurationHelper methods for some of these.

If you are programming with C++ using the Windows Runtime Template Library (WRL), then only the data member fields exist as members of Duration, and you cannot use the utility methods or properties listed in the members table. WRL code can access similar utility methods that exist on the DurationHelper class. For example, you can call DurationHelper.Compare to compare two C++ Duration values. For more info, see DurationHelper.

Automatic and Forever

Automatic and Forever are values that hold special meaning for a Duration property value. For .NET, these are represented by the static properties Automatic and Forever.

The Automatic value applied in either XAML or code results in different behavior on a Storyboard as opposed to an animation. For Storyboard, the Automatic value sets the effective time span to be equal to the end time of its longest-running child animation, such that no clipping occurs for any child animation. For animations, the Automatic value results in the behavior whereby the animation runs with a time span of 1 second (0:0:1). This behavior is seldom desirable as a final result, but it enables you to see the running animation during testing, before you have established a final time span.

Using Forever for an animation is a deprecated usage, and is seldom used. This results in an animation that never advances from its starting value, no matter what values were provided for From/To, key frames, and so on. If you want an animation to repeat continuously, use RepeatBehavior="Forever", not Duration="Forever".

Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml
Windows::UI::Xaml [C++]

Metadata

Windows.winmd
Platform.winmd

Assembly

System.Runtime.WindowsRuntime.UI.Xaml.dll

See also

Storyboarded animations
Storyboard
Timeline.Duration

 

 

Show:
© 2014 Microsoft