Visual​State Visual​State Visual​State Class

Definition

Represents the visual appearance of a UI element when it is in a specific state. Visual states use Setters or a Storyboard to set UI properties within pages or control templates where the VisualState is defined.

public sealed class VisualState : DependencyObject, IVisualState, IVisualState2public sealed class VisualState : DependencyObject, IVisualState, IVisualState2Public NotInheritable Class VisualState Inherits DependencyObject Implements IVisualState, IVisualState2
<VisualState x:Name="stateName" />
-or-
<VisualState x:Name="stateName">
  singleStoryboard
</VisualState>
-or-
<VisualState x:Name="stateName">
  <VisualState.Setters>
    oneOrMoreSetters
  </VisualState.Setters>
  [optional]singleStoryboard
</VisualState>
-or-
<VisualState x:Name="stateName">
  <VisualState.StateTriggers>
    oneOrMoreTriggers
  </VisualState.StateTriggers>  
  <VisualState.Setters>
    oneOrMoreSetters
  </VisualState.Setters>
  [optional]singleStoryboard
</VisualState>
Inheritance
VisualStateVisualStateVisualState
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Inherited Members

Inherited methods

Inherited properties

Remarks

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. For example:


<VisualStateGroup x:Name="CommonStates">
   <VisualState x:Name="Normal"/>
   <VisualState x:Name="PointerOver">...</VisualState>
<!-- do not need explicit VisualStateGroups.States property element, States is the XAML content property-->
</VisualStateGroup>

When you use StateTriggers, ensure that the VisualStateGroup is declared under the first child of the root in order for the triggers to take effect automatically.

Default state

It's legal and common to define a VisualState that has an x:Name attribute 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 the empty state from a GoToState call. When an empty state becomes the current state, that cancels all modifications to template properties made by a previous visual state from the same VisualStateGroup. For more info on how to use groups for visual states, see Storyboarded animations for visual states.

When you use StateTriggers, you are no longer required to create an empty VisualState to call GoToState on. When the conditions for a StateTrigger are no longer met, all the modifications to the properties made by the corresponding VisualState are automatically removed and the values provided in the default markup take effect.

VisualState and x:Name

The GoToState method (which is typically called from control code) requires a stateName parameter to inform the VisualStateManager which state should be used as a current state. Specify an x:Name attribute for each VisualState that will need to be manually applied using a GoToState call from code. If you are using StateTriggers to automatically trigger a VisualState from markup, you don’t need to specify an x:Name attribute on that VisualState.

If you use visual transitions, the x:Name attribute value of a VisualState is also referenced by the From or To values of a VisualTransition. In this case the name identifies the state or states that the VisualTransition provides the intermediate values between.

The x:Name attribute value that you specify for a VisualState must be unique within the control template XAML where the VisualState exists. Scope for state names isn't just scoped for each VisualStateGroup, it's scoped to all visual states in the template. 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 visuals state group; the unprefixed attribute "Name" won't work. VisualState and VisualStateGroup each have a Name property but these are read-only. That Name property exists for advanced scenarios that use code to examine a control template's content at run-time, not for setting from XAML.

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. States with those names must 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. So 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 an IDE such as Microsoft Visual Studio, 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, then modify them, so that you don't accidentally omit an expected visual state from your new template.

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 attribute, 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 your attribute values.

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>
<Page>
    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <VisualStateManager.VisualStateGroups>
            <VisualStateGroup>
                <VisualState>
                    <VisualState.StateTriggers>
                        <!-- VisualState to be triggered when window width is >=720 effective pixels -->
                        <AdaptiveTrigger MinWindowWidth="720"/>
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Target="myPanel.Orientation" Value="Horizontal"/>
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateManager.VisualStateGroups>
        <StackPanel x:Name="myPanel" Orientation="Vertical">
            <TextBlock x:Name="myTextBlock" MaxLines="5" Style="{ThemeResource BodyTextBlockStyle}"/>
        </StackPanel>
    </Grid>
</Page>

Constructors

VisualState() VisualState() VisualState()

Initializes a new instance of the VisualState class.

public VisualState()public VisualState()Public Sub New()
Attributes

Properties

Name Name Name

Gets the name of the VisualState.

public string Name { get; }public string Name { get; }Public ReadOnly Property Name As string
<VisualState x:Name="stateName"/>
Value
string string string

The name of the VisualState.

Attributes

Remarks

Name is a read-only property that you can check with code at run-time to read the value of the x:Name attribute that was applied to a VisualState in a XAML control template. You can't literally set Name because it's read-only, and x:Name attribute can only be set in XAML. The value is available as soon as the XAML that contains the control template and the VisualState definition is loaded.

The need to check the Name of a VisualState at run-time is anticipated to be relatively uncommon, and would only be relevant to advanced scenarios. For the most part, the definition of a VisualState in XAML combined with using VisualStateManager and VisualStateGroup events in code provides you all that you need to define and invoke visual states for a custom or Windows Runtime-defined control.

See Also

Setters Setters Setters

Gets a collection of Setter objects that define discrete property values that control the appearance of UIElement s when this VisualState is applied.

public SetterBaseCollection Setters { get; }public SetterBaseCollection Setters { get; }Public ReadOnly Property Setters As SetterBaseCollection
Value
SetterBaseCollection SetterBaseCollection SetterBaseCollection

A collection of Setter objects. The default is an empty collection.

Attributes

Remarks

Use this property to make discrete property value changes on multiple UI elements at one time when a VisualState is applied.

Examples

The following example shows how to use multiple Setter statements inside the VisualState.Setters property to apply multiple discrete property value changes on 2 different elements when a VisualState is applied.

<Page>
    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <VisualStateManager.VisualStateGroups>
            <VisualStateGroup>
                <VisualState x:Name="NarrowState">
                    <VisualState.Setters>
                        <Setter Target="myPanel.Orientation" Value="Vertical" />
                        <Setter Target="myPanel.Width" Value="380" />
                        <Setter Target="myTextBlock.MaxLines" Value="3" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateManager.VisualStateGroups>
        <StackPanel x:Name="myPanel" Orientation="Horizontal">
            <TextBlock x:Name="myTextBlock" MaxLines="5" Style="{ThemeResource BodyTextBlockStyle}"/>
        </StackPanel>
    </Grid>
</Page>

StateTriggers StateTriggers StateTriggers

Gets a collection of StateTriggerBase objects that indicate when this VisualState should be applied. If any (not all) of the triggers are active, the VisualState will be applied.

public IVector<StateTriggerBase> StateTriggers { get; }public IVector<StateTriggerBase> StateTriggers { get; }Public ReadOnly Property StateTriggers As IVector<StateTriggerBase>
Value

A collection of StateTriggerBase objects. The default is an empty collection.

Attributes

Remarks

Use this property to create rules in XAML that specify when a particular VisualState is to be applied. You use StateTriggers directly in your XAML markup instead of calling VisualStateManager.GoToState in your code.

You can use the built-in AdaptiveTrigger to create rules based on window size, which is useful for creating responsive UI. You can also extend StateTriggerBase to create your own custom triggers and use them within the StateTriggers property.

For more examples, see the XAML Responsive Techniques sample and the State Triggers sample.

Examples

This example shows how to use the StateTriggers property with an AdaptiveTrigger to create a declarative rule in XAML markup based on window size. By default, the StackPanel orientation is Vertical. When the window width is >= 720 effective pixels, the VisualState change is triggered, and the StackPanel orientation is changed to Horizontal.

<Page>
    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <VisualStateManager.VisualStateGroups>
            <VisualStateGroup>
                <VisualState>
                    <VisualState.StateTriggers>
                    <!--VisualState to be triggered when window width is >=720 effective pixels.-->
                        <AdaptiveTrigger MinWindowWidth="720" />
                    </VisualState.StateTriggers>

                    <VisualState.Setters>
                        <Setter Target="myPanel.Orientation" Value="Horizontal" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateManager.VisualStateGroups>
        <StackPanel x:Name="myPanel" Orientation="Vertical">
            <TextBlock Text="This is a block of text. It is text block 1. " 
                       Style="{ThemeResource BodyTextBlockStyle}"/>
            <TextBlock Text="This is a block of text. It is text block 2. " 
                       Style="{ThemeResource BodyTextBlockStyle}"/>
            <TextBlock Text="This is a block of text. It is text block 3. " 
                       Style="{ThemeResource BodyTextBlockStyle}"/>
        </StackPanel>
    </Grid>
</Page>
See Also

Storyboard Storyboard Storyboard

Gets or sets a Storyboard that defines state-specific property values and appearance of the control when it is using this visual state.

public Storyboard Storyboard { get; set; }public Storyboard Storyboard { get; set; }Public ReadWrite Property Storyboard As Storyboard
<VisualState>
  singleStoryboard
</VisualState>

Value
Storyboard Storyboard Storyboard

A Storyboard that defines the property changes to apply to the control when this VisualState is used as the current visual state.

Attributes

Remarks

The value of the Storyboard property is either null or a single Storyboard object. A Storyboard is like a container for animations; it can contain one or more animation definitions. Each such animation can target a specific dependency property on a specific named target. The named target must be an element in the control template that has a Name or x:Name attribute value defined in the template itself. The dependency property must be a property that exists in that object's object model, or an attached property. To target animations, you use the Storyboard.TargetName and Storyboard.TargetProperty attached properties. For more info on how to define animations with XAML syntax, and the types of animations you can use, see Storyboarded animations.

Animations that affect layout are potentially dependent animations, which can have performance consequences for users of your control when the control loads a VisualState. For more info, see Storyboarded animations for visual states.

Examples

This example creates a simple ControlTemplate for a Button that contains one Grid. The VisualState with the x:Name attribute value of "PointerOver" has a Storyboard that changes the color of the button content (a Grid ) from green to red when the user puts the pointer over the Button. The VisualState with the x:Name attribute value of "Normal" is included so that when the user moves the pointer off the button, the Grid background returns 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>
See Also

See Also