Setter.Value property

Applies to Windows and Windows Phone

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

Syntax


public object Value { get; set; }


<Setter ...>
  <Setter.Value>
    objectValue
  </Setter.Value>
</Setter>


<Setter Value="attributeValue"/>
-or-
<Setter Value="extensionUsage"/>

XAML Values

objectValue

An object element that specifies the value of the property being set.

attributeValue

A string that specifies the attribute value of the property being set. The format and interpretation of the string provided for the attribute value depends on the property being set.

extensionUsage

One of several possible extension mechanisms that specify the property value to be obtained from an existing value. The most common of these is StaticResource.

Property value

Type: System.Object [.NET] | Platform::Object [C++]

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 Basic XAML syntax. 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 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.

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 WPF or Silverlight XAML, replace any Binding expression usages with strings or objects that set values, or refactor the values as shared StaticResource values rather than Binding-obtained values.

Examples

This example creates two styles: one for a TextBlock and one for a TextBox. Each style is applied to two instances of a control to create a uniform appearance for each TextBlock and TextBox. The style for the TextBlock sets the Foreground, FontSize, and VerticalAlignment properties. The style for the TextBox sets the Width, Height, Margin, Background, and FontSize properties. Notice that the setter for the Background of the TextBox uses the property element syntax for the value so that the Background can use a LinearGradientBrush.


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


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