VisualTransition Class

Reference

Definition

Namespace:: Microsoft.UI.Xaml

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

Represents the visual behavior that occurs when the control transitions from one visual state to another.

/// [Microsoft.UI.Xaml.Markup.ContentProperty(Name="Storyboard")]
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class VisualTransition : DependencyObject

[Microsoft.UI.Xaml.Markup.ContentProperty(Name="Storyboard")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class VisualTransition : DependencyObject

Public Class VisualTransition
Inherits DependencyObject

<VisualStateGroup>
  <!--one or more Visual State elements in the implicit States collection property -->
  <VisualStateGroup.Transitions>
    <VisualTransition>
      singleStoryboard
    </VisualTransition>
    <!--more transitions as above-->
  </VisualStateGroup.Transitions>
</VisualStateGroup>

Inheritance: Object IInspectable DependencyObject VisualTransition

Attributes: ContentPropertyAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Examples

This example creates a VisualTransition that specifies that when the user moves the mouse away from the control, the control's border changes to blue, then to yellow, then to black in 1.5 seconds.

<!--Take one and a half seconds to transition from the
    PointerOver state to the Normal state. 
    Have the SolidColorBrush, BorderBrush, fade to blue, 
    then to yellow, and then to black in that time.-->
<VisualTransition From="PointerOver" To="Normal" 
                      GeneratedDuration="0:0:1.5">
  <Storyboard>
    <ColorAnimationUsingKeyFrames
      Storyboard.TargetProperty="Color"
      Storyboard.TargetName="BorderBrush"
      FillBehavior="HoldEnd" >

      <ColorAnimationUsingKeyFrames.KeyFrames>

        <LinearColorKeyFrame Value="Blue" 
                             KeyTime="0:0:0.5" />
        <LinearColorKeyFrame Value="Yellow" 
                             KeyTime="0:0:1" />
        <LinearColorKeyFrame Value="Black" 
                             KeyTime="0:0:1.5" />

      </ColorAnimationUsingKeyFrames.KeyFrames>
    </ColorAnimationUsingKeyFrames>
  </Storyboard>
</VisualTransition>

<VisualStateGroup x:Name="CommonStates">

  <!--Define the VisualTransitions that can be used when the control
      transitions between VisualStates that are defined in the
      VisualStatGroup.-->
  <VisualStateGroup.Transitions>

    <!--Take one hundredth of a second to transition to the
        Pressed state.-->
    <VisualTransition To="Pressed" 
                          GeneratedDuration="0:0:0.01" />
    
    <!--Take one half second to transition to the PointerOver state.-->
    <VisualTransition To="PointerOver" 
                          GeneratedDuration="0:0:0.5" />

    <!--Take one hundredth of a second to transition from the
        Pressed state to the PointerOver state.-->
    <VisualTransition From="Pressed" To="PointerOver" 
                          GeneratedDuration="0:0:0.01" />

    <!--Take one and a half seconds to transition from the
        PointerOver state to the Normal state. 
        Have the SolidColorBrush, BorderBrush, fade to blue, 
        then to yellow, and then to black in that time.-->
    <VisualTransition From="PointerOver" To="Normal" 
                          GeneratedDuration="0:0:1.5">
      <Storyboard>
        <ColorAnimationUsingKeyFrames
          Storyboard.TargetProperty="Color"
          Storyboard.TargetName="BorderBrush"
          FillBehavior="HoldEnd" >

          <ColorAnimationUsingKeyFrames.KeyFrames>

            <LinearColorKeyFrame Value="Blue" 
                               KeyTime="0:0:0.5" />
            <LinearColorKeyFrame Value="Yellow" 
                               KeyTime="0:0:1" />
            <LinearColorKeyFrame Value="Black" 
                               KeyTime="0:0:1.5" />

          </ColorAnimationUsingKeyFrames.KeyFrames>
        </ColorAnimationUsingKeyFrames>
      </Storyboard>
    </VisualTransition>
  </VisualStateGroup.Transitions>

  <!--The remainder of the VisualStateGroup is the
      same as the previous example.-->

  <VisualState x:Name="Normal" />

  <VisualState x:Name="PointerOver">
    <Storyboard>
      <ColorAnimation Storyboard.TargetName="BorderBrush" 
                    Storyboard.TargetProperty="Color" To="Red" />

    </Storyboard>
  </VisualState>

  <VisualState x:Name="Pressed">
    <Storyboard >
      <ColorAnimation Storyboard.TargetName="BorderBrush" 
                    Storyboard.TargetProperty="Color" To="Transparent"/>
    </Storyboard>
  </VisualState>

  <!--The Disabled state is omitted for brevity.-->

</VisualStateGroup>

Remarks

A VisualTransition is a behavior that initiates a Storyboard. This Storyboard is a timeline that declares the duration that animations that transition between two visual states will run. The transition can be defined differently for each combination of starting state (the From state) and ending state (the To state) as defined by your control's set of visual states. Transitions are defined by the Transitions property of VisualStateGroup and are usually defined in XAML. Most default control templates don't define transitions, and in this case the transitions between states happen instantaneously. The old state's modifications to the template are removed, and the new state's modifications are applied.

A VisualTransition references either one or two named visual states. The From value references the name of a state that is the current state. The To value references the name of a state that is the new state requested by a GoToState call. These names come from an x:Name attribute string value that is applied to a VisualState as part of its definition in the same VisualStateGroup. Either From or To are a required value for an effective VisualTransition, a VisualTransition that lacks either of these values or uses values that don't match existing states does nothing.

A VisualTransition can reference just a From state, just a To state, or both a From and To state. Omitting either From or To equates to any state. The VisualStateManager uses a precedence logic for which transition to apply whenever visual states change:

If a VisualTransition exists that specifically references the old state as From and the new state as To, use that transition.
Otherwise, if a VisualTransition exists that specifically references the new state as To but does not specify From, use that transition.
Finally, if a VisualTransition exists that specifically references the old state as From but does not specify To, use that transition.

If none of the above apply, no transition runs.

When you call GoToState to change the visual state of a control, the VisualStateManager performs these actions:

If the VisualState that the control was using prior to the newly requested visual state has a Storyboard, that storyboard stops.
Between these actions, the Storyboard for a VisualTransition runs, if a transition that involves the two visual states exists, and the named visual state requested by GoToState is valid and is a new state.
If the VisualState as named by stateName has a Storyboard, the storyboard begins.

A VisualTransition can have a Storyboard value, a GeneratedDuration value or both. But if a VisualTransition has neither a Storyboard value nor a GeneratedDuration value, that VisualTransition does nothing in terms of animations, even if states named by the From and To values are involved in a state change.

Implicit transitions

You can define a VisualTransition such that it has a GeneratedDuration, but does not have any specific dependency properties being targeted and animated. This creates an implicit transition. Any dependency property that is specifically targeted for animation in either the From or To visual states and thus has different values across the state change then uses a generated transition animation. This generated animation transitions between the From state value and the To state value of such a property using interpolation. The implicit transition animation lasts for the time stated by GeneratedDuration.

Implicit transitions only apply to properties that are a Double, Color or Point value. In other words the property must be possible to implicitly animate using a DoubleAnimation, PointAnimation or ColorAnimation. If you want to create a transition animation on some other value, for example a value that requires ObjectAnimationUsingKeyFrames, put that animation in the Storyboard and give the animation a Duration that you want it to run.

By default, an implicit transition animation uses linear interpolation to animate a value through the GeneratedDuration. You can change the linear interpolation to an interpolation behavior of your choice by setting GeneratedEasingFunction as well as GeneratedDuration on a VisualTransition.

Transition animations

There is another design pattern and API for displaying visual transitions for apps using C++ or C#. This concept is called transition animations and the class that implements the behavior is a theme transition or a theme animation. Rather than declaring transitions between visual states of the same control and applying changes to properties of control parts like you do with visual states, a transition animation represents changes in the relationship between a complete UI element and the overall app and UI. For example, there's a RepositionThemeTransition that can be applied whenever a UI element is moved in the UI coordinate space of its layout container. Many of the transition animations are initiated by a user action. A transition animation applies to various Transition properties of UIElement and specific derived classes, not to a VisualStateGroup. Transition animations and theme animations are often built-in to the default behavior of a control.

Constructors

VisualTransition()

Initializes a new instance of the VisualTransition class.

Properties

Dispatcher	Always returns `null` in a Windows App SDK app. Use DispatcherQueue instead. (Inherited from DependencyObject)
DispatcherQueue	Gets the `DispatcherQueue` that this object is associated with. The `DispatcherQueue` represents a facility that can access the `DependencyObject` on the UI thread even if the code is initiated by a non-UI thread. (Inherited from DependencyObject)
From	Gets or sets the name of the VisualState to transition from.
GeneratedDuration	Gets or sets the amount of time it takes to move from one state to another, and the time that any implicit transition animations should run as part of the transition behavior.
GeneratedEasingFunction	Gets or sets the easing function applied to the generated animations.
Storyboard	Gets or sets the Storyboard that runs when the transition occurs.
To	Gets or sets the name of the VisualState to transition to.

Methods

ClearValue(DependencyProperty)	Clears the local value of a dependency property. (Inherited from DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Returns any base value established for a dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject)
GetValue(DependencyProperty)	Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject)
ReadLocalValue(DependencyProperty)	Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registers a notification function for listening to changes to a specific DependencyProperty on this DependencyObject instance. (Inherited from DependencyObject)
SetValue(DependencyProperty, Object)	Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Cancels a change notification that was previously registered by calling RegisterPropertyChangedCallback. (Inherited from DependencyObject)

Applies to

Share via