VisualStateManager VisualStateManager VisualStateManager VisualStateManager Class

Definition

Manages visual states and the logic for transitions between visual states for controls. Also provides the attached property support for VisualStateManager.VisualStateGroups, which is how you define visual states in XAML for a control template.

public : class VisualStateManager : DependencyObject, IVisualStateManager, IVisualStateManagerOverrides, IVisualStateManagerProtected
struct winrt::Windows::UI::Xaml::VisualStateManager : DependencyObject, IVisualStateManager, IVisualStateManagerOverrides, IVisualStateManagerProtected
public class VisualStateManager : DependencyObject, IVisualStateManager, IVisualStateManagerOverrides, IVisualStateManagerProtected
Public Class VisualStateManager Inherits DependencyObject Implements IVisualStateManager, IVisualStateManagerOverrides, IVisualStateManagerProtected
Inheritance
VisualStateManagerVisualStateManagerVisualStateManagerVisualStateManager
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Examples

This example shows how to use the VisualStateManager.VisualStateGroups XAML attached property. Note how there is otherwise no "VisualStateManager" tag defined. Conceptually, VisualStateManager.VisualStateGroups contains the visual states for a control, as an immediate child tag of the template root in a control template.

The particular set of visual states contains one VisualStateGroup, called "CommonStates", which defines the "PointerOver" and "Normal"**VisualState objects. When the user puts the pointer over the Button, the Grid changes from green to red in .5 seconds. When the user moves the pointer away from the button, the Grid immediately changes back to green.

<ControlTemplate TargetType="Button">
  <Grid >
    <VisualStateManager.VisualStateGroups>
      <VisualStateGroup x:Name="CommonStates">

        <VisualStateGroup.Transitions>

          <!--Take one half second to transition to the PointerOver state.-->
          <VisualTransition To="PointerOver" 
                              GeneratedDuration="0:0:0.5"/>
        </VisualStateGroup.Transitions>
        
        <VisualState x:Name="Normal" />

        <!--Change the SolidColorBrush, ButtonBrush, to red when the
            Pointer is over the button.-->
        <VisualState x:Name="PointerOver">
          <Storyboard>
            <ColorAnimation Storyboard.TargetName="ButtonBrush" 
                            Storyboard.TargetProperty="Color" To="Red" />
          </Storyboard>
        </VisualState>
      </VisualStateGroup>
    </VisualStateManager.VisualStateGroups>
    <Grid.Background>
      <SolidColorBrush x:Name="ButtonBrush" Color="Green"/>
    </Grid.Background>
  </Grid>
</ControlTemplate>
<common:LayoutAwarePage>
  <Grid>
...
    <VisualStateManager.VisualStateGroups>
    <!-- Visual states reflect the application's window size -->
      <VisualStateGroup>
        <VisualState x:Name="DefaultLayout">
           <Storyboard>
           </Storyboard>
        </VisualState>
        <VisualState x:Name="Below768Layout">
           <Storyboard>
             <ObjectAnimationUsingKeyFrames Storyboard.TargetProperty="(FrameworkElement.Margin)"
               Storyboard.TargetName="ContentRoot">
               <DiscreteObjectKeyFrame KeyTime="0">
                 <DiscreteObjectKeyFrame.Value>
                   <Thickness>20,20,20,20</Thickness>
                 </DiscreteObjectKeyFrame.Value>
               </DiscreteObjectKeyFrame>
             </ObjectAnimationUsingKeyFrames>
             <ObjectAnimationUsingKeyFrames Storyboard.TargetProperty="(FrameworkElement.HorizontalAlignment)"
               Storyboard.TargetName="FooterPanel">
               <DiscreteObjectKeyFrame KeyTime="0">
                 <DiscreteObjectKeyFrame.Value>
                    <HorizontalAlignment>Left</HorizontalAlignment>
                 </DiscreteObjectKeyFrame.Value>
               </DiscreteObjectKeyFrame>
             </ObjectAnimationUsingKeyFrames>
           </Storyboard>
         </VisualState>
       </VisualStateGroup>
     </VisualStateManager.VisualStateGroups>
   </Grid>
</common:LayoutAwarePage>

The next snippet is code to go along with the XAML, showing how an app might detect the app window width and use that info to call the appropriate visual state.

String state = (Window.Current.Bounds.Width > 768) ? "DefaultLayout" : "Below768Layout";
VisualStateManager.GoToState(this, state, false); // 'this' is the LayoutAwarePage, scope is page code-behind

Remarks

VisualStateManager supports two important features for control authors, and for app developers who are applying a custom template to a control:

  • Control authors or app developers add VisualStateGroup object elements to the root element of a control template definition in XAML, using the VisualStateManager.VisualStateGroups attached property. Within a VisualStateGroup element, each VisualState represents a discrete visual state of a control. Each VisualState has a name that is representative of a UI state that can be changed by the user, or changed by control logic. A VisualState consists mainly of a Storyboard. This Storyboard targets individual dependency property values that should be applied whenever the control is in that visual state. For more info on how to write visual states in XAML, including example code, see Storyboarded animations for visual states.
  • Control authors or app developers transition between these states by calling the static GoToState method of VisualStateManager. Control authors do this whenever the control logic handles events that indicate a change of state, or control logic initiates a state change by itself. It's more common for control definition code to do this rather than app code, so that all the possible visual states and their transitions and trigger conditions are there by default for app code, and the logic is encapsulated by the control.

Most developers will use just two of the VisualStateManager API: VisualStateManager.VisualStateGroups, and GoToState, as described above. The remaining API are all for extension support and creating a custom VisualStateManager. For more info see "Custom VisualStateManager" section in this topic.

When you edit copies of styles as enabled by the XAML design surface of Microsoft Visual Studio, the visual states from the default template are defined in the XAML you are editing. Make sure you don't delete these states or change their names, because the control logic is expecting that these visual states exist in the template.

In addition to the visual states, the visual state model also includes transitions. Transitions are animation actions controlled by a Storyboard that occur between each visual state when the state is changed. The transition can be defined differently for each combination of starting state and ending state as defined by your control's set of visual states. Transitions are defined by the Transitions property of VisualStateGroup, in XAML using property element syntax. Most default control templates don't define transitions. In absence of specifically defined transitions, the transitions between states happen instantaneously (zero-duration). For more info, see VisualTransition.

Attached properties defined by VisualStateManager

VisualStateManager supports these XAML attached properties: + VisualStateManager.VisualStateGroups (a collection)

Custom VisualStateManager

As an advanced scenario, it is possible to derive from VisualStateManager and change the default GoToState behavior. Follow these guidelines:

That's the basic requirements for creating and using a custom VisualStateManager. You also can choose to override a few more behaviors:

All the other API (CustomVisualStateManagerProperty, GetCustomVisualStateManager, GetVisualStateGroups, SetCustomVisualStateManager) are infrastructure for attached property support, and you don't need to call them or do anything with them.

Visual states for elements that aren't controls

Visual states are sometimes useful for scenarios where you want to change the state of some area of UI that's not immediately a Control subclass. You can't do this directly because the control parameter of the GoToState method requires a Control subclass, which refers to the object that the VisualStateManager acts upon. Page is a Control subclass, and it's fairly rare that you'd be showing UI in a context where you don't have a Page, or your Window.Content root isn't a Control subclass. We recommend you define a custom UserControl to either be the Window.Content root or be a container for other content you want to apply states to (such as a Panel ). Then you can call GoToState on your UserControl and apply states regardless of whether the rest of the content is a Control. For example you could apply visual states to UI that otherwise consists of just a SwapChainPanel so long as you placed that within your UserControl and declared named states that apply to the properties of the parent UserControl or of the named SwapChainPanel part of the template.

Constructors

VisualStateManager() VisualStateManager() VisualStateManager() VisualStateManager()

Initializes a new instance of the VisualStateManager class.

Properties

CustomVisualStateManagerProperty CustomVisualStateManagerProperty CustomVisualStateManagerProperty CustomVisualStateManagerProperty

Identifies the VisualStateManager.CustomVisualStateManager dependency property.

Dispatcher Dispatcher Dispatcher Dispatcher

Gets the CoreDispatcher that this object is associated with. The CoreDispatcher 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)

Methods

ClearValue(DependencyProperty) ClearValue(DependencyProperty) ClearValue(DependencyProperty) ClearValue(DependencyProperty)

Clears the local value of a dependency property.

(Inherited from DependencyObject)
GetAnimationBaseValue(DependencyProperty) GetAnimationBaseValue(DependencyProperty) GetAnimationBaseValue(DependencyProperty) 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)
GetCustomVisualStateManager(FrameworkElement) GetCustomVisualStateManager(FrameworkElement) GetCustomVisualStateManager(FrameworkElement) GetCustomVisualStateManager(FrameworkElement)

Gets the value of the VisualStateManager.CustomVisualStateManager attached property.

GetValue(DependencyProperty) GetValue(DependencyProperty) GetValue(DependencyProperty) GetValue(DependencyProperty)

Returns the current effective value of a dependency property from a DependencyObject.

(Inherited from DependencyObject)
GetVisualStateGroups(FrameworkElement) GetVisualStateGroups(FrameworkElement) GetVisualStateGroups(FrameworkElement) GetVisualStateGroups(FrameworkElement)

Gets the value of the VisualStateManager.VisualStateGroups attached property.

GoToState(Control, String, Boolean) GoToState(Control, String, Boolean) GoToState(Control, String, Boolean) GoToState(Control, String, Boolean)

Transitions a control between two states, by requesting a new VisualState by name.

GoToStateCore(Control, FrameworkElement, String, VisualStateGroup, VisualState, Boolean) GoToStateCore(Control, FrameworkElement, String, VisualStateGroup, VisualState, Boolean) GoToStateCore(Control, FrameworkElement, String, VisualStateGroup, VisualState, Boolean) GoToStateCore(Control, FrameworkElement, String, VisualStateGroup, VisualState, Boolean)

When overridden in a derived class, transitions a control between states.

RaiseCurrentStateChanged(VisualStateGroup, VisualState, VisualState, Control) RaiseCurrentStateChanged(VisualStateGroup, VisualState, VisualState, Control) RaiseCurrentStateChanged(VisualStateGroup, VisualState, VisualState, Control) RaiseCurrentStateChanged(VisualStateGroup, VisualState, VisualState, Control)

When overridden in a derived class, fires the CurrentStateChanged event on the specified VisualStateGroup.

RaiseCurrentStateChanging(VisualStateGroup, VisualState, VisualState, Control) RaiseCurrentStateChanging(VisualStateGroup, VisualState, VisualState, Control) RaiseCurrentStateChanging(VisualStateGroup, VisualState, VisualState, Control) RaiseCurrentStateChanging(VisualStateGroup, VisualState, VisualState, Control)

When overridden in a derived class, fires the CurrentStateChanging event on the specified VisualStateGroup.

ReadLocalValue(DependencyProperty) ReadLocalValue(DependencyProperty) ReadLocalValue(DependencyProperty) ReadLocalValue(DependencyProperty)

Returns the local value of a dependency property, if a local value is set.

(Inherited from DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback) RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback) RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback) RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback)

Registers a notification function for listening to changes to a specific DependencyProperty on this DependencyObject instance.

(Inherited from DependencyObject)
SetCustomVisualStateManager(FrameworkElement, VisualStateManager) SetCustomVisualStateManager(FrameworkElement, VisualStateManager) SetCustomVisualStateManager(FrameworkElement, VisualStateManager) SetCustomVisualStateManager(FrameworkElement, VisualStateManager)

Sets the value of the VisualStateManager.CustomVisualStateManager attached property.

SetValue(DependencyProperty,Object) SetValue(DependencyProperty,Object) SetValue(DependencyProperty,Object) SetValue(DependencyProperty,Object)

Sets the local value of a dependency property on a DependencyObject.

(Inherited from DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty,Int64) UnregisterPropertyChangedCallback(DependencyProperty,Int64) UnregisterPropertyChangedCallback(DependencyProperty,Int64) UnregisterPropertyChangedCallback(DependencyProperty,Int64)

Cancels a change notification that was previously registered by calling RegisterPropertyChangedCallback.

(Inherited from DependencyObject)

See Also