VisualStateManager class

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.

Inheritance

Object

  DependencyObject

    VisualStateManager

Syntax

public class VisualStateManager : DependencyObject

Attributes

MarshalingBehaviorAttribute(Agile)

StaticAttribute(Windows.UI.Xaml.IVisualStateManagerStatics, NTDDI_WIN8)

ThreadingAttribute(Both)

VersionAttribute(NTDDI_WIN8)

WebHostHiddenAttribute()

Members

The VisualStateManager class has these types of members:

• Constructors
• Methods
• Attached Properties
• Properties

Constructors

The VisualStateManager class has these constructors.

Methods

The VisualStateManager class has these methods. It also inherits methods from the Object class.

Attached Properties

The VisualStateManager class has these attached properties.

Properties

The VisualStateManager class has these properties.

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.

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

When you edit styles in StandardStyles.xaml or 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 and are usually defined in XAML. Most default control templates don't define transitions, and in this case the transitions between states happen instantaneously. For more info, see VisualTransition.

Attached properties defined by VisualStateManager

VisualStateManager supports these XAML attached properties:

• VisualStateManager.VisualStateGroups (a collection)
• VisualStateManager.CustomVisualStateManager (for advanced scenarios)

Custom VisualStateManager

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

• The derived class should override the protected GoToStateCore method. Any instance of the custom VisualStateManager uses this Core logic when its GoToState method is called.
• To use a custom VisualStateManager in app code, reference the custom class as a resource using the VisualStateManager.CustomVisualStateManager attached property. You set VisualStateManager.CustomVisualStateManager on the root element of a ControlTemplate, alongside the VisualStateManager.VisualStateGroups attached property usage that defines the visual states for the template.

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

• Override RaiseCurrentStateChanged to control when the CurrentStateChanged event is fired by a VisualStateGroup being managed by the VisualStateManager.
• Override RaiseCurrentStateChanging to control when the CurrentStateChanging event is fired by a VisualStateGroup being managed by the VisualStateManager.
• Override or overload the constructor if your custom class needs additional information to initialize with.

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

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 over one half second. 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>

This example shows one possible pattern for calling GoToState from app logic. This is a handler for the Window.SizeChanged event, and the scenario here is that you are using visual states of a Page to control page layout for each of the possible view states of an app (full, portrait, snapped, fill).

        public void OnSizeChanged(object sender, Windows.UI.Core.WindowSizeChangedEventArgs args)
        {
            switch (Windows.UI.ViewManagement.ApplicationView.Value)
            {
                case Windows.UI.ViewManagement.ApplicationViewState.Filled:
                    VisualStateManager.GoToState(this, "Fill", false);
                    break;
                case Windows.UI.ViewManagement.ApplicationViewState.FullScreenLandscape:
                    VisualStateManager.GoToState(this, "Full", false);
                    break;
                case Windows.UI.ViewManagement.ApplicationViewState.Snapped:
                    VisualStateManager.GoToState(this, "Snapped", false);
                    break;
                case Windows.UI.ViewManagement.ApplicationViewState.FullScreenPortrait:
                    VisualStateManager.GoToState(this, "Portrait", false);
                    break;
                default:
                    break;
            }

            this.ShowCurrentViewState();
        }

For another example that shows how to define a visual state that changes the Visibility of an element of control composition (a very common situation in visual state design), see the example XAML in Storyboarded animations for visual states.

Requirements

See also

DependencyObject

VisualStateGroup

VisualState

Storyboard

Quickstart: Control templates

Storyboarded animations

Storyboarded animations for visual states

Attached properties overview

Snap sample

XAML control and app styling sample

Build date: 1/31/2013