Setter Setter Setter Class

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

Syntax

Declaration

public sealed class Setterpublic sealed class SetterPublic NotInheritable Class Setter
<Setter .../>

Inheritance Hierarchy

Remarks

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

The 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 Property property can be used only in a Style and not in a VisualState. Starting in Windows 10, you can use Target everywhere instead of 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 Binding (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.

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

Constructors summary

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

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

Properties summary

Gets or sets the property to apply the Value to.

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

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

Constructors

  • Setter()
    Setter()
    Setter()
    Setter()

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

    public Setter()public New()Public Sub New()public Setter()
  • Setter(DependencyProperty, Object)
    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, Object value)public New(DependencyProperty targetProperty, Object value)Public Sub New(targetProperty As DependencyProperty, value As Object)public Setter(DependencyProperty targetProperty, Object value)

    Parameters

Properties

  • Property
    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 DependencyPropertypublic DependencyProperty Property { get; set; }
    <Setter Property="propertyName"/>
    

    Property Value

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

    <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 LeftProperty, use This XAML.

    <Setter Property="Canvas.Left" Value="100"/>
    
  • Target
    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 TargetPropertyPathpublic TargetPropertyPath Target { get; set; }

    Property Value

  • Value
    Value
    Value
    Value

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

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

    Property Value

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

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Xaml.dll