Export (0) Print
Expand All
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

VisualStateGroup class

Applies to Windows and Windows Phone

Contains mutually exclusive VisualState objects and VisualTransition objects that are used to go from one state to another.

Inheritance

Object
  DependencyObject
    VisualStateGroup

Syntax


public sealed class VisualStateGroup : DependencyObject


<VisualStateManager.VisualStateGroups>
   <VisualStateGroup x:Name="groupname" ...>
     oneOrMoreVisualStates
   </VisualStateGroup>
   <!--- other peer VisualStateGroup's here ... -->
</VisualStateManager.VisualStateGroups>

XAML Values

oneOrMoreVisualStates

One or more object elements that is of type VisualState.

groupname

A descriptive name that describes the VisualState behaviors that are grouped by the VisualStateGroup. See Remarks.

Attributes

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

Members

The VisualStateGroup class has these types of members:

Constructors

The VisualStateGroup class has these constructors.

ConstructorDescription
VisualStateGroup Initializes a new instance of the VisualStateGroup class.

 

Events

The VisualStateGroup class has these events.

EventDescription
CurrentStateChanged Occurs after a control changes into a different state.
CurrentStateChanging Occurs when a control begins changing into a different state.

 

Methods

The VisualStateGroup 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)
SetValue Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject)

 

Properties

The VisualStateGroup class has these properties.

PropertyAccess typeDescription

CurrentState

Read-onlyGets the most recently set VisualState from a successful call to the GoToState method.

Dispatcher

Read-onlyGets the CoreDispatcher that this object is associated with. (Inherited from DependencyObject)

Name

Read-onlyGets the name of the VisualStateGroup.

States

Read-onlyGets the collection of mutually exclusive VisualState objects.

Transitions

Read-onlyGets the collection of VisualTransition objects.

 

Remarks

Each VisualStateGroup declared in XAML as part of a control template should always have an x:Name attribute set on it. Each name string used in the set of VisualStateGroups in a control template must be unique in that template. It's common to use the same group names for different controls though. For example, almost all existing control templates have a VisualStateGroup with x:Name of "CommonStates".

The set of visual states within each VisualStateGroup should be mutually exclusive in the group. In other words, the control should be using exactly one of the visual states from each of its defined VisualStateGroup groups at all times. Whenever there's a case where a control is intended to be simultaneously in two states, make sure that the two states are in different groups. For example, it's possible for a drop-down control to simultaneously be focused and have its drop-down open. In a correct visual state design, you'd have a separate VisualStateGroup for each state so they can both be active at once. Such groups might have names like "FocusStates" and "DropDownStates".

Whenever you define a VisualStateGroup that enables a temporary storyboarded behavior in one of its VisualState elements, make sure that group also contains a second VisualState that can be called to cancel the previous state. This can be as simple as declaring the second VisualState with no Storyboard at all, just an x:Name.

The x:Name value you set for a VisualStateGroup is not used for a call to VisualStateManager.GoToState; instead it's the x:Name of a VisualState that is used for VisualStateManager.GoToState. Anyone that uses VisualStateManager.GoToState should be aware of all the groups and states available, so that each call correctly transitions from old states to new states within a group.

In addition to a set of VisualState elements, a VisualStateGroup can also define a set of VisualTransition elements, where each VisualTransition pertains to at least one of the named VisualState elements defined in the group. In XAML, the set of VisualState elements can be declared as immediate object element child elements of the VisualStateGroup. This is possible because the States property, which is the collection of visual states, is the XAML content property for VisualStateGroup. In contrast, to set the collection of visual transitions, you must declare that collection within a VisualStateGroup.Transitions property element in XAML. For more info on XAML content properties, see Basic XAML syntax guide.

VisualStateGroup APIs that support custom VisualStateManager implementation

Many of the APIs of VisualStateGroup exist only to support custom VisualStateManager implementation. These include: Name, CurrentState, CurrentStateChanging, CurrentStateChanged. Most common usages of visual states for control templates won't need these APIs. In particular it's not typical to handle the events. Most logic operations for a control should involve its own properties and events. For most app and control definition scenarios, visual state changes that happen to the control should only be an end result of logic that the control applies to its template, not a trigger for other logic.

Examples

This example creates a simple ControlTemplate for a Button that contains one Grid. It also contains a VisualStateGroup called "CommonStates", which defines the "PointerOver" and "Normal" states. The VisualStateGroup also has a VisualTransition that specifies that it takes one half second for the Grid to change from green to red when the user puts the pointer over the Button.


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


Requirements

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

See also

DependencyObject
VisualStateManager
VisualState
Quickstart: Control templates
Storyboarded animations
Storyboarded animations for visual states
XAML control and app styling sample

 

 

Show:
© 2014 Microsoft