VisualStateManager.VisualStateGroups attached property

Gets the collection of VisualStateGroup elements that are defined by a root element of a template definition. A control typically defines this as part of its template.

<templateRoot>
  <VisualStateManager.VisualStateGroups>
    oneOrMoreVisualStateGroups
  </VisualStateManager.VisualStateGroups>
</templateRoot>

XAML Values

templateRoot

The root UIElement as defined within a control template (a ControlTemplate object element).

oneOrMoreVisualStateGroups

One or more VisualStateGroup elements. Each such VisualStateGroup is expected to have a unique x:Name within its definition scope. Each VisualStateGroup typically contains at least one VisualState definition for an animated transition.

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

VisualStateManager.VisualStateGroups is an attached property, which supports a XAML usage. When getting this property in code, use GetVisualStateGroups. This returns a collection object, which you can then add items to, paralleling the XAML processing behavior of any child elements of a <VisualStateManager.VisualStateGroups> property element usage. Because there is no public dependency property identifier for this particular attached property, you cannot use GetValue plus the identifier to get this attached property via the property system APIs.

A VisualStateManager.VisualStateGroups value is not interpreted by any tangible VisualStateManager object that is part of the same visual tree. Instead, the property provides a generalized container property that can be used on any possible UIElement that serves as the root element of a template definition.

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>

Requirements

See also

VisualStateManager

VisualStateGroup

VisualState

Storyboard

Quickstart: Control templates

Attached properties overview

Build date: 1/31/2013