AnimatedIcon Class

Reference

Definition

Namespace:: Microsoft.UI.Xaml.Controls

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 an icon that displays and controls a visual that can animate in response to user interaction and visual state changes.

This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.XamlContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.UI.Xaml.Markup.ContentProperty(Name="Source")]
class AnimatedIcon : IconElement

[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.XamlContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.UI.Xaml.Markup.ContentProperty(Name="Source")]
public class AnimatedIcon : IconElement

Public Class AnimatedIcon
Inherits IconElement

Inheritance: IconElement
AnimatedIcon

Attributes: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute ContentPropertyAttribute

Examples

Tip

For more info, design guidance, and code examples, see Animated icon.

Open the WinUI 2 Gallery app and see the AnimatedIcon in action.

The WinUI 2 Gallery app includes interactive examples of most WinUI 2 controls, features, and functionality. Get the app from the Microsoft Store or get the source code on GitHub.

Add an AnimatedIcon to a button

This example demonstrates a back button that displays a back arrow icon that animates when pointer events occur.

The AnimatedBackVisualSource is a back-arrow animation provided by WinUI.
The FallbackIconSource is used when animations can't be played.
The AddHandler method with handledEventsToo set to true is used for events that the button marks as Handled.

<!-- 
xmlns:muxc="using:Microsoft.UI.Xaml.Controls"
xmlns:animatedvisuals="using:Microsoft.UI.Xaml.Controls.AnimatedVisuals"
-->

<AppBarButton x:Name="BackButton" Label="Back"
              muxc:AnimatedIcon.State="Normal"
              PointerEntered="AppBarButton_PointerEntered"
              PointerExited="AppBarButton_PointerExited">
    <muxc:AnimatedIcon>
        <animatedvisuals:AnimatedBackVisualSource/>
        <muxc:AnimatedIcon.FallbackIconSource>
            <muxc:SymbolIconSource Symbol="Back"/>
        </muxc:AnimatedIcon.FallbackIconSource>
    </muxc:AnimatedIcon>
</AppBarButton>

// using muxc = Microsoft.UI.Xaml.Controls;

// Add handlers.
protected override void OnNavigatedTo(NavigationEventArgs e)
{
    SettingsButton.AddHandler(UIElement.PointerPressedEvent, 
        new PointerEventHandler(AppBarButton_PointerPressed), true);
    SettingsButton.AddHandler(UIElement.PointerReleasedEvent, 
        new PointerEventHandler(AppBarButton_PointerReleased), true);
    base.OnNavigatedTo(e);
}

// Remove handlers.
protected override void OnNavigatedFrom(NavigationEventArgs e)
{
    SettingsButton.RemoveHandler(UIElement.PointerPressedEvent, 
        (PointerEventHandler)AppBarButton_PointerPressed);
    SettingsButton.RemoveHandler(UIElement.PointerReleasedEvent, 
        (PointerEventHandler)AppBarButton_PointerReleased);
    base.OnNavigatedFrom(e);
}

private void AppBarButton_PointerEntered(object sender, PointerRoutedEventArgs e)
{
    muxc.AnimatedIcon.SetState((UIElement)sender, "PointerOver");
}

private void AppBarButton_PointerPressed(object sender, PointerRoutedEventArgs e)
{
    muxc.AnimatedIcon.SetState((UIElement)sender, "Pressed");
}

private void AppBarButton_PointerReleased(object sender, PointerRoutedEventArgs e)
{
    muxc.AnimatedIcon.SetState((UIElement)sender, "Normal");
}

private void AppBarButton_PointerExited(object sender, PointerRoutedEventArgs e)
{
    muxc.AnimatedIcon.SetState((UIElement)sender, "Normal");
}

Remarks

Set the AnimatedIcon.Source property to specify the animated visual for the icon. WinUI provides animated visuals for some common icons in the Microsoft.UI.Xaml.Controls.AnimatedVisuals namespace.

In some cases, system settings or limitations can prevent the icon from being animated.

If the user turns off animations in their system settings, AnimatedIcon displays the final frame of the state transition the control was in.
Specify a FallbackIconSource to be used when animations aren't supported, such as on older versions of Windows that don't support Lottie animations.

Custom animations

You can create custom animations to use as an animated icon in your app. Animations can be created with Adobe AfterEffects, then you can use that output with the Lottie-Windows library to generate a custom class that implements IAnimatedVisualSource2. You can use this class as the Source for an animated icon. For more information, see Use Lottie to create animated content for an AnimatedIcon.

Control the animated icon state

You change the playback position and state of the animation by setting the AnimatedIcon.State attached property. The state property takes a string value that describes the visual state, such as "Normal", "PointerOver", or "Pressed". You can also specify a specific state transition, such as "PressedToNormal".

An animated icon Source contains Markers that map a position in the animation timeline to a visual state. The string values that a Source supports to set the State attached property are defined in the Markers collection. For more info, see Define AnimatedIcon markers.

Animated visual sources that are used in control templates often have a more complex set of Markers that map to control states, while animated visuals for more general use often have a more simple set of Markers that map to pointer events.

Where to set state

You can set the property on the AnimatedIcon or on an ancestor in the XAML tree. In either case, you need to use the attached property syntax, like this:

<muxc:AnimatedIcon muxc:AnimatedIcon.State="Normal">...</muxc:AnimatedIcon>

Important

If you add an AnimatedIcon to the XAML tree and set the State property on an ancestor element, the State property must be set to an initial value before the animated icon is first loaded in order for the icon to animate. You typically set the initial state in XAML as shown here.

<StackPanel muxc:AnimatedIcon.State="Normal" ...>
   <muxc:AnimatedIcon>
       <animatedvisuals:AnimatedBackVisualSource/>
   </muxc:AnimatedIcon>
</StackPanel>

Use visual states

You can add an AnimatedIcon to the ControlTemplate of a XAML control and use a VisualStateManager to set its state. Some controls, such as NavigationViewItem, automatically set the state for an AnimatedIcon that is set as its Icon.

To see an example that sets AnimatedIcon.State in a control template visual state, see CheckBox_themeresources.xaml in the WinUI GitHub repo. The CheckBox control uses the AnimatedAcceptVisualSource for its check mark. The visual state setters look like this:

<VisualState x:Name="CheckedPointerOver">
    ...
    <VisualState.Setters>
        <Setter Target="CheckGlyph.(AnimatedIcon.State)" Value="PointerOverOn"/>
    </VisualState.Setters>
</VisualState>

Handle pointer events

To make the AnimatedIcon respond to user interaction, you need to set the AnimatedIcon.State attached property in response to some pointer events. This table shows the pointer events you will typically handle, and common states that map to these events. (However, not every animated icon source will map to these states exactly.)

Event	State
PointerEntered	"`PointerOver`"
PointerPressed	"`Pressed`"
PointerReleased	"`Normal`"
PointerExited	"`Normal`"

Tip

If you place the AnimatedIcon inside a Button or other control that has a Click event, the PointerPressed and PointerReleased events are marked as Handled. To handle these events on a button, use the AddHandler method to connect your event handler and specify handledEventsToo as true. Use RemoveHandler to disconnect the event handler.

See the Examples section for sample code that demonstrates these event handlers.

XAML attached properties

AnimatedIcon is the host service class for a XAML attached property.

In order to support XAML processor access to the attached properties, and also to expose equivalent get and set operations to code, each XAML attached property has a pair of Get and Set accessor methods. Another way to get or set the value in code is to use the dependency property system, calling either GetValue or SetValue and passing the identifier field as the dependency property identifier.

Constructors

AnimatedIcon()

Initializes a new instance of the AnimatedIcon class.

This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

Properties

FallbackIconSource	Gets or sets the static icon to use when the animated icon cannot run. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
FallbackIconSourceProperty	Identifies the FallbackIconSource dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
MirroredWhenRightToLeft	Gets or sets a value that indicates whether the icon is mirrored when the FlowDirection is RightToLeft. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
MirroredWhenRightToLeftProperty	Identifies the MirroredWhenRightToLeft dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
Source	Gets or sets the animated visual shown by the `AnimatedIcon` object. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
SourceProperty	Identifies the Source dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
StateProperty	Identifies the AnimatedIcon.State XAML attached property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

Attached Properties

State

Property that the developer sets on AnimatedIcon.

This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

Methods

GetState(DependencyObject)

Retrieves the value of the AnimatedIcon.State attached property for the specified DependencyObject.

This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

SetState(DependencyObject, String)

Specifies the value of the AnimatedIcon.State attached property for the specified DependencyObject.

This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

Applies to

AnimatedIcon Class

Definition

Examples

Add an AnimatedIcon to a button

Remarks

Custom animations

Control the animated icon state

Where to set state

Use visual states

Handle pointer events

XAML attached properties

Constructors

Properties

Attached Properties

Methods

Applies to

See also

Feedback

Feedback

Additional resources