AnimatedIcon Class
Definition
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.
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
-
AnimatedIcon
- Attributes
Examples
Tip
For more info, design guidance, and code examples, see Animated icon.
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 totrue
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 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). |