Setter.Property Setter.Property Setter.Property Setter.Property Property

Definition

Gets or sets the property to apply the Value to.

public : DependencyProperty Property { get; set; }
DependencyProperty Property();

void Property(DependencyProperty property);
public DependencyProperty Property { get; set; }
Public ReadWrite Property Property As DependencyProperty
<Setter Property="propertyName"/>

Property Value

A DependencyProperty to which the Value will be applied. The default is null.

Examples

This example creates two styles: one for a TextBlock and one for a TextBox. When setting Property attribute values in XAML, you are specifying the name of the property.

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

You can also apply setters to attached property values, by specifying the attached property name in the AttachedPropertyProvider.PropertyName form. For example, to use a Setter for the attached property Canvas.Left, use This XAML.

<Setter Property="Canvas.Left" Value="100"/>

Remarks

You must specify both the Property and Value properties on a Setter. Otherwise an exception is thrown (either a parse exception or runtime error, depending on whether the Setter is created in XAML or modified in code).

If you're accessing a Setter instance using code, you cannot change the value of any property of a Setter instance if the value of the IsSealed property on a parent Style is true. This is also reported by the IsSealed property on an individual Setter. The system sets these properties to true when the runtime applies styles to UI elements and displays them in the UI. Attempting to change a sealed Setter throws a runtime error.

You can use a Setter to style an attached property. In this case the dependency property name is a qualified name in XAML that also names the attached property's defining type. For example, <Setter Property="AutomationProperties.LiveSetting" Value="Polite" /> could be used to set the AutomationProperties.LiveSetting attached property value within the style for any control or UI element.

Note

The XAML parser also accepts dependency property names that include a qualifying class. For example the parser interprets either "Button.Background" or "Control.Background" as being a reference to the Background property in a style for a Button. Qualifying by class isn't necessary though and results in potentially confusing markup. You might encounter or use qualified property-name usages if you're migrating XAML from other platforms.

Identifying dependency properties

As noted, you can only use a Setter to adjust a property through a style if the property in question is a dependency property. The UI properties where there's a scenario for applying a style are almost always implemented as dependency properties by the Windows Runtime, and settable properties that aren't a dependency property on UI elements are quite rare. If you want to verify that a Windows Runtime property is a dependency property, check the members lists for the type that originally defines the property. If a property is in fact a dependency property, the dependency property identifier will exist on that class also, and that identifier has the same name as the property itself but with the suffix Property added. This dependency property identifier is a static read-only property that's useful in some dependency property scenarios through code. For example you could use such an identifier value in code to adjust an existing Setter.Property value so long as the parent style isn't already sealed.

Using a Setter for a custom property

For your own custom properties you should declare the property as a dependency property if you want to support styles, as well as for other scenarios such as data binding or animation. If you do so your custom property is also supported for styling on any Style with a TargetType that references your custom type. For more info, see Custom dependency properties or TargetType.