Setter.Property property

Applies to Windows and Windows Phone

Gets or sets the property to apply the Value to.

Syntax


public DependencyProperty Property { get; set; }


<Setter Property="propertyName"/>

XAML Values

propertyName

A string that specifies the name of the property being set. This property must be a dependency property.

Property value

Type: DependencyProperty

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

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.

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.


<StackPanel>
  <StackPanel.Resources>
    <!--Create a Style for a TextBlock to specify that the
              Foreground equals Navy, FontSize equals 14, and
              VerticalAlignment equals Botton.-->
    <Style TargetType="TextBlock" x:Key="TextBlockStyle">
      <Setter Property="Foreground" Value="Navy"/>
      <Setter Property="FontSize" Value="14"/>
      <Setter Property="VerticalAlignment" Value="Bottom"/>
    </Style>

    <!--Create a Style for a TextBlock that specifies that
              the Width is 200, Height is 20, Margin is 4,
              Background is LightBlue, and FontSize is 14.-->
    <Style TargetType="TextBox" x:Key="TextBoxStyle">
      <Setter Property="Width" Value="200"/>
      <Setter Property="Height" Value="30"/>
      <Setter Property="Margin" Value="4"/>
      <Setter Property="FontSize" Value="14"/>
      <Setter Property="Background">
        <Setter.Value>
          <LinearGradientBrush StartPoint="0,0.5" EndPoint="1,0.5">
            <GradientStop Color="White" Offset="0.0"/>
            <GradientStop Color="LightBlue" Offset="0.5"/>
            <GradientStop Color="Navy" Offset="1"/>
          </LinearGradientBrush>
        </Setter.Value>
      </Setter>
    </Style>
  </StackPanel.Resources>

  <!--Apply the TextBlockStyle and TextBoxStyle to each 
          TextBlock and TextBox, respectively.-->
  <StackPanel Orientation="Horizontal">
    <TextBlock Style="{StaticResource TextBlockStyle}">
              First Name:
          </TextBlock>
    <TextBox Style="{StaticResource TextBoxStyle}"/>
  </StackPanel>
  <StackPanel Orientation="Horizontal">
    <TextBlock Style="{StaticResource TextBlockStyle}">
              Last Name:
          </TextBlock>
    <TextBox Style="{StaticResource TextBoxStyle}"  
                   Margin="6,4,4,4"/>
  </StackPanel>
</StackPanel>


In this first example the names are all simple names, unqualified by an owning type name. In this usage the property is always assumed to exist on class that is the explicit or implicit TargetType of the style.

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

Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

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

Metadata

Windows.winmd

See also

Setter

 

 

Show:
© 2014 Microsoft