VisualState class

Represents the visual appearance of the control when it is in a specific state. Visual states use a Storyboard to set UI properties of control element parts of the control template where the VisualState exists.

Inheritance

Object

  DependencyObject

    VisualState

Syntax

Public NotInheritable Class VisualState  
    Inherits DependencyObject

<VisualState x:Name="stateName" />
-or-
<VisualState x:Name="stateName">
  singleStoryboard
</VisualState>

XAML Values

stateName

The name of this VisualState for purposes of targeting it from a GoToState call. See Remarks.

singleStoryboard

A single Storyboard object element. This Storyboard should contain the specific timeline animations that the VisualState should use to modify control template properties when it is loaded.

Attributes

ActivatableAttribute(NTDDI_WIN8)

ContentPropertyAttribute(Name=Storyboard)

MarshalingBehaviorAttribute(Agile)

ThreadingAttribute(Both)

VersionAttribute(NTDDI_WIN8)

WebHostHiddenAttribute()

Members

The VisualState class has these types of members:

• Constructors
• Methods
• Properties

Constructors

The VisualState class has these constructors.

Methods

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

Properties

The VisualState class has these properties.

Remarks

Always specify an x:Name value for each VisualState you define. If you don't give it a name, you can't load the VisualState. The GoToState call (which is made from control code) requires a stateName parameter to inform the VisualStateManager which state should be loaded. The x:Name value of a VisualState is also referenced by the From or To values of a VisualTransition, to identify the state or states that the VisualTransition applies to.

The x:Name you give a VisualState must be unique within the control template XAML where the VisualState exists, not just within a specific VisualStateGroup. For example, you can't define two different states named "Focused" in the same template XAML, even if they are in different groups.

You must use the x:Name attribute to name a visual state or group; the unprefixed attribute "Name" won't work. VisualState and VisualStateGroup each have a Name property but these are read-only, and exist for advanced scenarios that use code to examine a control template's content at run-time.

A VisualState element must always be contained within a VisualStateGroup parent in the XAML markup. The VisualStateGroup has an implicit collection property States, so you can put each VisualState as an immediate child element of the VisualStateGroup parent.

It's legal and common to define a VisualState that has an x:Name but doesn't specify anything in the Storyboard. This is useful because such a VisualState will use whatever values are present in the default template. You can then specifically request that state from a GoToState call and cancel any previous modifications to template properties that were applied by a previous visual state from the same VisualStateGroup.

Replacing an existing control's control template

If you are an app developer using a control in your app UI, you can replace the control template by setting the Control.Template property to a different value. Or you can replace the template by declaring a new style that uses the implicit style key for that control. For more info on these concepts, see Quickstart: Control templates. When you replace a control template, it's important that you reproduce all the existing named VisualState elements from the original control template's VisualStateManager.VisualStateGroups content in XAML. The control code (which you aren't modifying) is calling GoToState and expects visual states with those names to exist in the control template. A request for a missing VisualState won't throw exceptions, but it often will leave the control in a visual state that will be confusing to the user. For example, if you don't supply a VisualState named "Checked" for a CheckBox control, no visual feedback appears when the user selects the control. The user will expect that there's something visually different to distinguish a checked CheckBox from an unchecked CheckBox, and a failure to reproduce the visual states on the app developer's part will make the control seem broken to the user.

When you use tools such as Microsoft Visual Studio or Blend for Microsoft Visual Studio 2012 for Windows 8, the actions that you use to replace a control template provide the option to start with a copy of the original template XAML, so you can see all the original named VisualState elements and other control composition you are replacing. It's best to start with template copies and modify them if you're unfamiliar with the templates and states of a control.

Attributing a custom control's named visual states

If you are defining a custom control that has visual states in its control template XAML, it's a best practice to attribute the control class to indicate to control consumers which visual states are available. To do this, apply one or more TemplateVisualState attributes at the class level of your control definition code. Each attribute should specify the state's x:Name, which is the stateName value a control consumer would pass in a GoToState call to use that visual state. If the VisualState is part of a VisualStateGroup, that should also be indicated in the attribute definition.

Examples

This example creates a VisualStateGroup in the ControlTemplate of a Button called "CommonStates" and adds VisualState objects for the states, "Normal", "Pressed", and "PointerOver". The Button also defines a state called "Disabled" that is in the "CommonStates" named VisualStateGroup, but the example omits it for brevity.

<ControlTemplate TargetType="Button">
  <Border x:Name="RootElement">

    <VisualStateManager.VisualStateGroups>

      <!--Define the states for the common states.
          The states in the VisualStateGroup are mutually exclusive to
          each other.-->
      <VisualStateGroup x:Name="CommonStates">

        <!--The Normal state is the state the button is in
            when it is not in another state from this VisualStateGroup.-->
        <VisualState x:Name="Normal" />

        <!--Change the SolidColorBrush, BorderBrush, to red when the
            Pointer is over the button.-->
        <VisualState x:Name="PointerOver">
          <Storyboard>
            <ColorAnimation Storyboard.TargetName="BorderBrush" 
                              Storyboard.TargetProperty="Color" To="Red" />

          </Storyboard>

        </VisualState>

        <!--Change the SolidColorBrush, BorderBrush, to Transparent when the
            button is pressed.-->
        <VisualState x:Name="Pressed">
          <Storyboard >
            <ColorAnimation Storyboard.TargetName="BorderBrush" 
                              Storyboard.TargetProperty="Color" To="Transparent"/>
          </Storyboard>
        </VisualState>
          <!--The Disabled state is omitted for brevity.-->
        </VisualStateGroup>
  
    </VisualStateManager.VisualStateGroups>
    

    <Border.Background>
      <SolidColorBrush x:Name="BorderBrush" Color="Black"/>
    </Border.Background>

    <Grid Background="{TemplateBinding Background}" Margin="4">
      <ContentPresenter
        HorizontalAlignment="{TemplateBinding HorizontalContentAlignment}"
        VerticalAlignment="{TemplateBinding VerticalContentAlignment}"
        Margin="4,5,4,4" />

    </Grid>


  </Border>
</ControlTemplate>

Requirements

See also

DependencyObject

VisualStateGroup

Storyboarded animations for visual states

Storyboarded animations

x:Name attribute

Quickstart: Control templates

XAML control and app styling sample

Build date: 1/31/2013