Skip to end of metadata
Go to start of metadata

Remarks

ContentTransition is inherited from ISContentControl, which means that it can contain a single object of any type (such as a string, an image, or a panel). For more information about this content model, see Content Model Overview.

Using ContentTransition

You use ContentTransition to provide visual transition when the Content of the control is changed. The transition is enabled by default and the default transition is set to Fading.

You can choose one of the TransitionEffect to apply to a ContentTransition control such as listed in the following:

  • Fading
  • SlideUp
  • SlideDown
  • SlideLeft
  • SlideRight
  • ZoomIn
  • ZoomOut
  • FlipLeft
  • FlipRight
  • FlipUp
  • FlipDown
  • Cube
  • Direct
  • Custom 

The following example shows how to setup a simple ContentTransition control with an Image in its content.

XAML

You can explicitly disable the transition by setting the EnableTransition to false.

ContentTransition also includes several advanced features, such as performing transition on load, customizing transition effects and duration, handling transition events, detecting navigation direction and more. See ContentTransition Overview to learn more about these features.

Working with ConflictAction Property

In rare cases, you may run into situations where one or more transitions are overlapping each other. This scenario may occured when there's new content that is assigned before the current transition is completed.

ContentTransition provides built-in feature to resolve conflicting transition. You can set the ConflictAction property to one of the following values:

  • QueueNextTransition
    The conflicting transition will be queued and hence applied when the current transition completes. This is the default value of the ConflictAction property.
  • CancelCurrentTransition
    The conflicting transition causes the current transition to be stopped. Consequently, the conflicting transition becomes the current transition which is applied to the content immediately.

Working with ContentID Property

In addition to setting the content programatically using code (see SetContent), you can also set the new content based on its ID (Name). This technique is ideal for MVVM design pattern which provides a way to set the new content based on a string value without the need to establish a strong reference to the UI element.

To set the content based on an element's ID, you set the ContentID property to the name of the desired element, such as shown in the following example.

XAML

Working with NavigationDirection Property

ContentTransition provides a more efficient way to manage the transitions. For example, you can configure ContentTransition to automatically select the transition to apply based on navigation direction. This feature is particularly useful in scenarios typically found in modern UI applications, for instances, perform a sliding transition when navigation backward or a flip effect when showing options, and many more.

To customize the transition based on navigation direction, you set the NavigationDirection property of the ContentTransition in code before you specify the new content. The value of the NavigationDirection property maps to the specific transition property such as described in the following table.

NavigationDirectionMapped Property
BackBackTransition
ForwardForwardTransition
ReplaceReplaceTransition
ParentParentTransition
ChildChildTransition
DefaultDefaultTransition
UnknownDefaultTransition

The following example shows how to setup the ContentTransition to automatically apply FlipUp transition which is specified in the BackTransition property when the NavigationDirection is set to Back.

XAML
C#

Since the ContentTransition is a standalone content control, you are required to set the navigation direction manually to apply the effect differently. For navigation scenarios that use this feature automatically, please use the UXFrame control. For more information, see Navigation Overview.

Working with TransitionDuration Property

You can also customize the duration of the transition if you prefer. By default, all transitions have a duration of 0.3 milliseconds.

To customize the transition duration, you set the TransitionDuration property to a number representing the time span in milliseconds measurement.

For the best user experience, particularly in business applications, it is recommended to use a duration of the range between 0.3 and 0.7ms.

Working with IsStaticContent Property and PlayTransition(Action) Method

ContentTransition is generally a content control which performs transition when its Content property changes. This means that you need to assign a new content for the ContentTransition to run its transition. In certain cases, this may not be ideal when the new content is a complex object that takes time to recreate and render. Doing so may affect the smoothness of the animation while transitioning to the particular complex object.

To address the performance issue in such scenario, you may want to reuse the existing content and perform modification to the existing object, while being able to transition the previous and the next state of the content. This approach is called static content transition mechanism where the transition is performed on an existing content rather than a new content.

To enable the static transition mechanism, you set the IsStaticContent and the UseCachedVisualForTransition property of the control to true. Next, you call the PlayTransition method in the code and then pass-in the delegate to be called when the transition is performing.

The following code shows how to transition a GlassLabel control by animating its original state to a new state where the Background is set to Blue color.

XAML
C#

Working with SetContent(object) Method

You use the SetContent method to set the content programmatically using code, such as shown in the following example.

C#

Although you can set a new content through the Content property, using the SetContent method has several advantages over the Content property. For example, using SetContent method automatically removes the target element from its parent element and makes the target element visible if it was previously collapsed.

Definition

public class ContentTransition : ISContentControl

Summary

The following table summarizes the members exposed in this class.

Public Constructors

ContentTransition Constructor()Initializes a new instance of the ContentTransformer class.

Public Properties

BackTransitionSpecifies the transition effect applied to backward navigation mode.
ChildTransitionSpecifies the transition effect applied to child navigation mode.
ConflictActionSpecifies the mode that determines how the control should handle conflict between transitions.
ContentIDGets or sets the ID of the element to be set as the Content of the control. This property can be used in MVVM design pattern to easily assign the content based on the element's ID.
CustomBackTransitionSpecifies the name that represents the custom transition applied to back navigation.
CustomChildTransitionSpecifies the name that represents the custom transition applied to child navigation.
CustomDefaultTransitionSpecifies the name that represents the custom transition applied to default mode.
CustomForwardTransitionSpecifies the name that represents the custom transition applied to forward navigation.
CustomParentTransitionSpecifies the name that represents the custom transition applied to parent navigation.
CustomReplaceTransitionSpecifies the name that represents the custom transition applied to new journal navigation.
DefaultTransitionSpecifies the default transition effect.
EnableTransitionSpecifies whether visual transition is enabled.
ForwardTransitionSpecifies the transition effect applied to forward navigation mode.
IsStaticContentGets or sets a value that indicates whether the Content of the control is a static, non-replacing element.
IsTransitioningGets a value that determine whether the content is transitioning.
NavigationDirectionSpecifies the direction mode that controls how the control should perform its transition.
ParentTransitionSpecifies the transition effect applied to parent navigation mode.
PerformTransitionOnLoadSpecifies whether the control should perform transition during first load.
ReplaceTransitionSpecifies the transition effect applied to new journal navigation mode.
StartupTransitionSpecifies the name that represents the transition applied when the control is loaded for the first time.
TransitionDurationSpecifies the transition duration in seconds.
TransitionLatencyGets or sets the time span (in seconds) to wait before the transition is performed. This property only applies when TransitionStrategy is set to WaitContentReady.
TransitionStrategyGets or sets a value that determines how the control handles the transition process.
UseCachedVisualForTransitionGets or sets a value indicating whether a cached visual should be used instead of the actual element when performing transition.

Protected Properties

ProductProduct Info.

Fields

BackTransitionPropertyIdentifies the BackTransition dependency property.
CacheEffectProperty 
ChildTransitionPropertyIdentifies the ChildTransition dependency property.
ConflictActionPropertyIdentifies the ConflictAction dependency property.
ContentIDPropertyIdentifies the ContentID dependency property.
CustomBackTransitionPropertyIdentifies the CustomBackTransition dependency property.
CustomChildTransitionPropertyIdentifies the CustomBackTransition dependency property.
CustomDefaultTransitionPropertyIdentifies the CustomDefaultTransition dependency property.
CustomForwardTransitionPropertyIdentifies the CustomForwardTransition dependency property.
CustomParentTransitionPropertyIdentifies the CustomParentTransition dependency property.
CustomReplaceTransitionPropertyIdentifies the CustomReplaceTransition dependency property.
DefaultTransitionPropertyIdentifies the DefaultTransition dependency property.
EnableTransitionPropertyIdentifies the EnableTransition dependency property.
ForwardTransitionPropertyIdentifies the ForwardTransition dependency property.
IsStaticContentPropertyIdentifies the IsStaticContent dependency property.
NavigationDirectionPropertyIdentifies the NavigationDirection dependency property.
ParentTransitionPropertyIdentifies the ParentTransition dependency property.
PerformTransitionOnLoadPropertyIdentifies the PerformTransitionOnLoad dependency property.
ReplaceTransitionPropertyIdentifies the ReplaceTransition dependency property.
StartupTransitionPropertyIdentifies the StartupTransition dependency property.
TransformOriginPropertyIdentifies the TransformOrigin dependency property.
TransitionCompletedEventIdentifies the TransitionCompleted routed event.
TransitionDurationPropertyIdentifies the TransitionDuration dependency property.
TransitioningEventIdentifies the Transitioning routed event.
TransitionLatencyPropertyIdentifies the TransitionLatency dependency property.
TransitionStrategyPropertyIdentifies the TransitionStrategy dependency property.
UseCachedVisualForTransitionPropertyIdentifies the PerformTransitionOnLoad dependency property.
ValueExpressionPropertyIdentifies the ValueExpression dependency property.

Static Methods

GetCacheEffect(DependencyObject) 
GetTransformOrigin(DependencyObject)Gets the render transform origin of an object.
GetValueExpression(DependencyObject)Gets the value expression specified on a dependency object, typically a key frame.
SetCacheEffect(DependencyObject, Effect) 
SetTransformOrigin(DependencyObject, Nullable<Point>)Sets the render transform origin to an object.
SetValueExpression(DependencyObject, string)Sets the value expression to a key frame which will be evaluated dynamically at runtime.

Public Methods

CancelTransition()Stops any running transitions.
ClearContent()Clears the content of the control and detach it from the parent accordingly.
OnApplyTemplate()Builds the visual tree for the ContentTransition when a new template is applied.
PlayTransition(Action)Play the transition using the existing content.
RefreshClip()Perform clipping to the dimension of the control. Call this method if necessary
SetContent(object)Sets the given object as the content for the control.
SetContentDirect(object)Sets the given content directly to the control.
SetContentDirect(object, bool)Sets the given content directly to the control and bypass any visual transitions.
SetRealtimeTransitionOnce()Forces the control to use Realtime strategy only for the next transition.

Protected Methods

OnContentChanged(object, object)Called when the value of the Content property changes.

Events

TransitionCompletedOccurs when the current transition has completed.
TransitioningOccurs when the content is transitioning.

Public Constructors

public ContentTransition()

Initializes a new instance of the ContentTransformer class.

Public Properties

public TransitionEffect BackTransition { get; set; }

Specifies the transition effect applied to backward navigation mode.

public TransitionEffect ChildTransition { get; set; }

Specifies the transition effect applied to child navigation mode.

public TransitionConflictMode ConflictAction { get; set; }

Specifies the mode that determines how the control should handle conflict between transitions.

public string ContentID { get; set; }

Gets or sets the ID of the element to be set as the Content of the control. This property can be used in MVVM design pattern to easily assign the content based on the element's ID.

public string CustomBackTransition { get; set; }

Specifies the name that represents the custom transition applied to back navigation.

public string CustomChildTransition { get; set; }

Specifies the name that represents the custom transition applied to child navigation.

public string CustomDefaultTransition { get; set; }

Specifies the name that represents the custom transition applied to default mode.

public string CustomForwardTransition { get; set; }

Specifies the name that represents the custom transition applied to forward navigation.

public string CustomParentTransition { get; set; }

Specifies the name that represents the custom transition applied to parent navigation.

public string CustomReplaceTransition { get; set; }

Specifies the name that represents the custom transition applied to new journal navigation.

public TransitionEffect DefaultTransition { get; set; }

Specifies the default transition effect.

public bool EnableTransition { get; set; }

Specifies whether visual transition is enabled.

public TransitionEffect ForwardTransition { get; set; }

Specifies the transition effect applied to forward navigation mode.

public bool IsStaticContent { get; set; }

Gets or sets a value that indicates whether the Content of the control is a static, non-replacing element.

public bool IsTransitioning { get; }

Gets a value that determine whether the content is transitioning.

public TransitionContentDirection NavigationDirection { get; set; }

Specifies the direction mode that controls how the control should perform its transition.

public TransitionEffect ParentTransition { get; set; }

Specifies the transition effect applied to parent navigation mode.

public bool PerformTransitionOnLoad { get; set; }

Specifies whether the control should perform transition during first load.

Remarks

By default, the ContentTransition performs transition only when its content is changed in the runtime which does not apply to the initial content. In certain cases, you may want to apply the transition to the initial content when the ContentTransition is loaded. To achieve this, you set the PerformTransitionOnLoad property to true.

 

public TransitionEffect ReplaceTransition { get; set; }

Specifies the transition effect applied to new journal navigation mode.

public string StartupTransition { get; set; }

Specifies the name that represents the transition applied when the control is loaded for the first time.

public double TransitionDuration { get; set; }

Specifies the transition duration in seconds.

public double TransitionLatency { get; set; }

Gets or sets the time span (in seconds) to wait before the transition is performed. This property only applies when TransitionStrategy is set to WaitContentReady.

public TransitionStrategy TransitionStrategy { get; set; }

Gets or sets a value that determines how the control handles the transition process.

public bool UseCachedVisualForTransition { get; set; }

Gets or sets a value indicating whether a cached visual should be used instead of the actual element when performing transition.

Protected Properties

protected ProductInfo Product { get; }

Product Info.

Fields

public static readonly DependencyProperty BackTransitionProperty

Identifies the BackTransition dependency property.

public static readonly DependencyProperty CacheEffectProperty

 

public static readonly DependencyProperty ChildTransitionProperty

Identifies the ChildTransition dependency property.

public static readonly DependencyProperty ConflictActionProperty

Identifies the ConflictAction dependency property.

public static readonly DependencyProperty ContentIDProperty

Identifies the ContentID dependency property.

public static readonly DependencyProperty CustomBackTransitionProperty

Identifies the CustomBackTransition dependency property.

public static readonly DependencyProperty CustomChildTransitionProperty

Identifies the CustomBackTransition dependency property.

public static readonly DependencyProperty CustomDefaultTransitionProperty

Identifies the CustomDefaultTransition dependency property.

public static readonly DependencyProperty CustomForwardTransitionProperty

Identifies the CustomForwardTransition dependency property.

public static readonly DependencyProperty CustomParentTransitionProperty

Identifies the CustomParentTransition dependency property.

public static readonly DependencyProperty CustomReplaceTransitionProperty

Identifies the CustomReplaceTransition dependency property.

public static readonly DependencyProperty DefaultTransitionProperty

Identifies the DefaultTransition dependency property.

public static readonly DependencyProperty EnableTransitionProperty

Identifies the EnableTransition dependency property.

public static readonly DependencyProperty ForwardTransitionProperty

Identifies the ForwardTransition dependency property.

public static readonly DependencyProperty IsStaticContentProperty

Identifies the IsStaticContent dependency property.

public static readonly DependencyProperty NavigationDirectionProperty

Identifies the NavigationDirection dependency property.

public static readonly DependencyProperty ParentTransitionProperty

Identifies the ParentTransition dependency property.

public static readonly DependencyProperty PerformTransitionOnLoadProperty

Identifies the PerformTransitionOnLoad dependency property.

public static readonly DependencyProperty ReplaceTransitionProperty

Identifies the ReplaceTransition dependency property.

public static readonly DependencyProperty StartupTransitionProperty

Identifies the StartupTransition dependency property.

public static readonly DependencyProperty TransformOriginProperty

Identifies the TransformOrigin dependency property.

public static readonly RoutedEvent TransitionCompletedEvent

Identifies the TransitionCompleted routed event.

public static readonly DependencyProperty TransitionDurationProperty

Identifies the TransitionDuration dependency property.

public static readonly RoutedEvent TransitioningEvent

Identifies the Transitioning routed event.

public static readonly DependencyProperty TransitionLatencyProperty

Identifies the TransitionLatency dependency property.

public static readonly DependencyProperty TransitionStrategyProperty

Identifies the TransitionStrategy dependency property.

public static readonly DependencyProperty UseCachedVisualForTransitionProperty

Identifies the PerformTransitionOnLoad dependency property.

public static readonly DependencyProperty ValueExpressionProperty

Identifies the ValueExpression dependency property.

Static Methods

public static Effect GetCacheEffect(DependencyObject obj)

 

Parameters

obj 

 

public static Nullable<Point> GetTransformOrigin(DependencyObject obj)

Gets the render transform origin of an object.

Parameters

objThe target object.

Return Types

The transform origin of the object.

 

public static string GetValueExpression(DependencyObject obj)

Gets the value expression specified on a dependency object, typically a key frame.

Parameters

objThe target object.

Return Types

The value expression string.

 

public static void SetCacheEffect(DependencyObject obj, Effect value)

 

Parameters

obj 
value 

 

public static void SetTransformOrigin(DependencyObject obj, Nullable<Point> value)

Sets the render transform origin to an object.

Parameters

objThe target object.
valueThe new transform origin.

 

public static void SetValueExpression(DependencyObject obj, string value)

Sets the value expression to a key frame which will be evaluated dynamically at runtime.

Parameters

objThe target object.
valueThe value expression to set. I.e., ActualWidth;100;Half

 

Public Methods

public void CancelTransition()

Stops any running transitions.

public void ClearContent()

Clears the content of the control and detach it from the parent accordingly.

public void OnApplyTemplate()

Builds the visual tree for the ContentTransition when a new template is applied.

public void PlayTransition(Action postTransitionAction)

Play the transition using the existing content.

Parameters

postTransitionAction 

 

public void RefreshClip()

Perform clipping to the dimension of the control. Call this method if necessary

public void SetContent(object content)

Sets the given object as the content for the control.

Parameters

contentThe content to be set.

 

public void SetContentDirect(object content)

Sets the given content directly to the control.

Parameters

contentThe content to be set.

 

public void SetContentDirect(object content, bool animateIfIdle)

Sets the given content directly to the control and bypass any visual transitions.

Parameters

contentThe content to be set.
animateIfIdlePerform animation if the control is not currently performing any transitions.

 

public void SetRealtimeTransitionOnce()

Forces the control to use Realtime strategy only for the next transition.

Protected Methods

protected void OnContentChanged(object oldContent, object newContent)

Called when the value of the Content property changes.

Parameters

oldContentThe old value of the Content property.
newContentThe new value of the Content property.

 

Events

public event ISRoutedEventHandler TransitionCompleted

Occurs when the current transition has completed.

public event ISRoutedEventHandler Transitioning

Occurs when the content is transitioning.

  • No labels