Windows Dev Center

VisualState class

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.

Inheritance

Object
  DependencyObject
    VisualState

Syntax


public sealed class VisualState : DependencyObject


<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>

XAML Values

stateName

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

oneOrMoreTriggers

One or more triggers that can be an AdaptiveTrigger or a custom trigger derived from StateTriggerBase. These can be used to indicate when the corresponding VisualState needs to be applied automatically without an explicit GoToState call. See Remarks on the StateTriggers property for more info.

oneOrMoreSetters

On or more Setter statements that target any number of UIElements within the page or control template. These Setter statements should be used to make discrete property changes that do not need animations when a VisualState is used as the current state.

singleStoryboard

Starting in Windows 10, optional if Setters are specified.

A single Storyboard object element. This Storyboard should contain the specific timeline animations that the VisualState should use. Each animation will modify property values within the control template when the visual state is used as the current state.

Members

The VisualState class has these types of members:

Constructors

The VisualState class has these constructors.

ConstructorDescription
VisualState Initializes a new instance of the VisualState class.

 

Methods

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

MethodDescription
ClearValue Clears the local value of a dependency property. (Inherited from DependencyObject)
GetAnimationBaseValue Returns any base value established for a dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject)
GetValue Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject)
ReadLocalValue Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject)
RegisterPropertyChangedCallback Registers an instance-specific property value for a property-changed notification that comes from the core property system. (Inherited from DependencyObject)
SetValue Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject)
UnregisterPropertyChangedCallback Cancels a change notification that was previously registered by calling RegisterPropertyChangedCallback. (Inherited from DependencyObject)

 

Properties

The VisualState class has these properties.

PropertyAccess typeDescription

Dispatcher

Read-onlyGets 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)

Name

Read-onlyGets the name of the VisualState.

Setters

Read-onlyGets a collection of Setter objects that define discrete property values that control the appearance of UIElements when this VisualState is applied.

StateTriggers

Read-onlyGets a collection of StateTriggerBase objects that indicate when this VisualState should be applied.

Storyboard

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

 

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 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 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 on that VisualState.

If you use visual transitions, the x:Name 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 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, 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>


This example creates a VisualStateGroup in a Page with a VisualState that gets automatically applied based on window width triggers. The Setter statement in the VisualState targets a discrete property change (Orientation from Vertical to Horizontal) on a target UIElement (myPanel). When the AdaptiveTrigger is evaluated to be true, this VisualState gets automatically applied and the orientation of myPanel is changed from Vertical 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 x:Name="myTextBlock" MaxLines="5" Style="{ThemeResource BodyTextBlockStyle}"/>
        </StackPanel>
    </Grid>
</Page>


Requirements (Windows 10 device family)

Device family

Universal

API contract

Windows.Foundation.UniversalApiContract, introduced version 1.0

Namespace

Windows.UI.Xaml
Windows::UI::Xaml [C++]

Metadata

Windows.Foundation.UniversalApiContract.winmd

Requirements (Windows 8.x and Windows Phone 8.x)

Minimum supported client

Windows 8 [Windows Store apps only]

Minimum supported server

Windows Server 2012 [Windows Store apps only]

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml
Windows::UI::Xaml [C++]

Metadata

Windows.winmd

Attributes

[ContentProperty("Name=Storyboard")]
[MarshalingBehavior(Agile)]
[Threading(Both)]
[Version(0x06020000)]
[WebHostHidden()]

See also

Object
DependencyObject
VisualStateGroup
Storyboarded animations for visual states
Storyboarded animations
x:Name attribute
Quickstart: Control templates
XAML control and app styling sample

 

 

Show:
© 2015 Microsoft