Setter Setter Setter Class

Definition

Applies a value to a property in a Style or a VisualState.

public : sealed class Setter : SetterBase, ISetter, ISetter2
public sealed class Setter : SetterBase, ISetter, ISetter2
Public NotInheritable Class Setter Inherits SetterBase Implements ISetter, ISetter2
<Setter .../>
Inheritance
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Examples

This example shows how to use Setter statements in a style for TextBlock elements.

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

    <!-- Apply the TextBlockStyle to 2 different TextBlocks. -->
    <TextBlock Style="{StaticResource TextBlockStyle}" Text=”Hello”/>
    <TextBlock Style="{StaticResource TextBlockStyle}" Text=”World”/>
</StackPanel>

This example shows how to use multiple Setter statements inside the VisualState.Setters property to apply discrete property value changes on various elements (without animations) when a VisualState is applied.


<Page>
    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <VisualStateManager.VisualStateGroups>
            <VisualStateGroup>
                <VisualState x:Name="NarrowState">
                    <VisualState.Setters>
                        <Setter Target="myPanel.Orientation" Value="Vertical"/>
                        <Setter Target="myPanel.Width" Value="380"/>
                        <Setter Target="myTextBlock.MaxLines" Value="3"/>
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateManager.VisualStateGroups>

        <StackPanel x:Name="myPanel" Orientation="Horizontal">
            <TextBlock x:Name="myTextBlock" MaxLines="5" Style="{ThemeResource BodyTextBlockStyle}"/>
        </StackPanel>
    </Grid>
</Page>

Remarks

Use Setter statements to set a property value within a Style or a VisualState.

The Setter.Target property can be used in either a Style or a VisualState, but in different ways. When used in a Style, the property that needs to be modified can be specified directly. When used in VisualState, the Target property must be given a TargetPropertyPath (dotted syntax with a target element and property explicitly specified).

The Setter.Property property can be used only in a Style and not in a VisualState. Starting in Windows 10, you can use Setter.Target everywhere instead of Setter.Property.

You must specify both the Value, and the Target or Property, 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.

Migration notes

  • Windows Presentation Foundation (WPF) and Microsoft Silverlight supported the ability to use a Binding expression to supply the Value for a Setter in a Style. The Windows Runtime doesn't support a Binding usage for Setter.Value (the Binding won't evaluate and the Setter has no effect, you won't get errors, but you won't get the desired result either). When you convert XAML styles from Windows Presentation Foundation (WPF) or Microsoft Silverlight XAML, replace any Binding expression usages with strings or objects that set values, or refactor the values as shared {StaticResource} markup extension values rather than Binding -obtained values.

Constructors

Setter() Setter() Setter()

Initializes a new instance of the Setter class with no initial Property or Value.

public : Setter()
public Setter()
Public Sub New()
See Also

Setter(DependencyProperty, Object) Setter(DependencyProperty, Object) Setter(DependencyProperty, Object)

Initializes a new instance of the Setter class with initial Property and Value information.

public : Setter(DependencyProperty targetProperty, Platform::Object value)
public Setter(DependencyProperty targetProperty, Object value)
Public Sub New(targetProperty As DependencyProperty, value As Object)
Parameters
targetProperty
DependencyProperty DependencyProperty DependencyProperty

The dependency property identifier for the property that is being styled.

value
Platform::Object Object Object

The value to assign to the value when the Setter applies.

Properties

Dispatcher Dispatcher Dispatcher

Inherited from DependencyObject

IsSealed IsSealed IsSealed

Inherited from SetterBase

Property Property Property

Gets or sets the property to apply the Value to.

public : DependencyProperty Property { get; set; }
public DependencyProperty Property { get; set; }
Public ReadWrite Property Property As DependencyProperty
<Setter Property="propertyName"/>
Value
DependencyProperty DependencyProperty DependencyProperty

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.

Target Target Target

Gets or sets the path of a property on a target element to apply the Value to.

public : TargetPropertyPath Target { get; set; }
public TargetPropertyPath Target { get; set; }
Public ReadWrite Property Target As TargetPropertyPath
Value
TargetPropertyPath TargetPropertyPath TargetPropertyPath

The path of a property on a target element to apply the Value to.

Value Value Value

Gets or sets the value to apply to the property that is specified by the Setter.

public : Platform::Object Value { get; set; }
public object Value { get; set; }
Public ReadWrite Property Value As object
<Setter ...>
  <Setter.Value>
    objectValue
  </Setter.Value>
</Setter>
Value
Platform::Object object object

The value to apply to the property that is specified by the Setter.

Remarks

As you can see from the XAML syntax, there are a variety of ways to specify the Value for a Setter in XAML:

  • As an attribute, using a string value. Such a string value can be implicitly converted to a property-specific type for simple cases such as setting numeric values, named values from an enumeration, or a Uniform Resource Identifier (URI).
  • As a complete new object that's declared in XAML object element syntax, and the object element is nested within a property element usage.
  • As an attribute that has a {StaticResource} markup extension usage within the quotes. Typically the value type of the property dictates which syntax is appropriate. For more info on XAML usages, see XAML overview or XAML syntax guide. You can use attribute syntax for most XAML UI properties, and UI properties that specifically require a property element usage or a resource reference are less common. A {StaticResource} markup extension usage can be appropriate even for strings or numeric values if those values are shared by more than one style or property.

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.

Styles and templates

You can use a Setter in a Style to apply values to any dependency property. But it's the Setter for the Template property of a Control -derived class that constitutes the majority of the XAML markup in a typical Style. The Value for a Setter with Property="Template" is almost always specified as a property element that contains a ControlTemplate object element.

When a Style is used to define a control template, the TargetType of the Style element and the TargetType of the ControlTemplate element for its Control.Template setter should always use the same value.

The Template setter defines the basic template UI definition for a control instance where that template is applied. It also contains the visual states for a control, and other state-based UI definitions such as default theme transitions. For a complex control such as ListBox, the default template Style and the ControlTemplate within can have hundreds of lines of XAML. For more info on the role of Style in control templating scenarios, see Quickstart: Control templates.

Methods

ClearValue(DependencyProperty) ClearValue(DependencyProperty) ClearValue(DependencyProperty)

Inherited from DependencyObject

GetAnimationBaseValue(DependencyProperty) GetAnimationBaseValue(DependencyProperty) GetAnimationBaseValue(DependencyProperty)

Inherited from DependencyObject

GetValue(DependencyProperty) GetValue(DependencyProperty) GetValue(DependencyProperty)

Inherited from DependencyObject

ReadLocalValue(DependencyProperty) ReadLocalValue(DependencyProperty) ReadLocalValue(DependencyProperty)

Inherited from DependencyObject

RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback) RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback) RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback)

Inherited from DependencyObject

SetValue(DependencyProperty,Object) SetValue(DependencyProperty,Object) SetValue(DependencyProperty,Object)

Inherited from DependencyObject

UnregisterPropertyChangedCallback(DependencyProperty,Int64) UnregisterPropertyChangedCallback(DependencyProperty,Int64) UnregisterPropertyChangedCallback(DependencyProperty,Int64)

Inherited from DependencyObject

See Also