Article
11/18/2011

Binding.RelativeSource Property

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Gets or sets the binding source by specifying its location relative to the position of the binding target.

Namespace: System.Windows.Data
Assembly: System.Windows (in System.Windows.dll)

Syntax

'Declaration
Public Property RelativeSource As RelativeSource

public RelativeSource RelativeSource { get; set; }

<Binding RelativeSource="{RelativeSource TemplatedParent}"/>
-or-
<Binding RelativeSource="{RelativeSource Self}"/>

XAML Values

{RelativeSource TemplatedParent}
The control where a ControlTemplate is applied is the source for this binding. This is useful for applying validation error information in bindings at the template level.
{RelativeSource Self}
The target element should be used as the source for this binding. This is useful for binding one property of an element to another property on the same element.

Property Value

Type: System.Windows.Data.RelativeSource
The relative location of the binding source to use. The default is nulla null reference (Nothing in Visual Basic).

Exceptions

Exception	Condition
InvalidOperationException	The Binding has already been attached to a target element, and cannot be modified. -or- The ElementName or Source property has already been set.

InvalidOperationException

The Binding has already been attached to a target element, and cannot be modified.

-or-

The ElementName or Source property has already been set.

Remarks

Source, RelativeSource, and ElementName are mutually exclusive in a binding. If you have set one of these attributes, then setting either of the other two in a binding (through XAML or through code) will cause an exception.

Setting RelativeSource in XAML always requires the use of the RelativeSource Markup Extension. This is also true if you are creating the entire binding as a Binding Markup Extension, in which case the RelativeSource Markup Extension is nested within the RelativeSource component of the expression.

Examples

The following Silverlight 5 code example demonstrates the use of this property. In this example, a ListBox is bound to a collection of Customer objects. Each item in the list box is bound to a single Customer in the collection, and its visual appearance is defined by the ItemTemplate property. Because of the item-to-customer binding, the template can bind the TextBlock.Text property directly to the Customer.Name property without qualification. However, the FontSize property is bound to a property of the page-level data context, which is inaccessible from the Customer object.

For this reason, the FontSize binding uses the RelativeSource markup extension with AncestorType set to UserControl, and a binding path of DataContext.CustomFontSize. This means that the binding uses the nearest UserControl ancestor as the data source, then binds to the CustomFontSize property of the object assigned to the DataContext property. If there were multiple, nested UserControl instances and the template needed to bind to an even higher-level data source, it could specify an AncestorLevel value of 2 or more.

<UserControl x:Class="SL5DataBindingFeatures.RelativeSourceFindAncestorTestPage"
  xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:d="https://schemas.microsoft.com/expression/blend/2008"
  xmlns:mc="https://schemas.openxmlformats.org/markup-compatibility/2006"
  xmlns:local="clr-namespace:SL5DataBindingFeatures" 
  mc:Ignorable="d"
  d:DesignHeight="300" d:DesignWidth="400">

  <UserControl.DataContext>
    <local:CustomerViewModel CustomFontSize="35">
      <local:CustomerViewModel.Customers>
        <local:CustomerCollection>
          <local:Customer Name="Customer1"/>
          <local:Customer Name="Customer2"/>
        </local:CustomerCollection>
      </local:CustomerViewModel.Customers>
    </local:CustomerViewModel>
  </UserControl.DataContext>

  <Grid x:Name="LayoutRoot" Background="White">

    <ListBox ItemsSource="{Binding Customers}">
      <ListBox.ItemTemplate>
        <DataTemplate>
          <TextBlock Text="{Binding Name}" 
            FontSize="{Binding DataContext.CustomFontSize, 
            RelativeSource={RelativeSource AncestorType=UserControl}}"/>
        </DataTemplate>
      </ListBox.ItemTemplate>
    </ListBox>

  </Grid>
</UserControl>

Public Class Customer
    Public Property Name As String
End Class

Public Class CustomerCollection
    Inherits ObservableCollection(Of Customer)
End Class

Public Class CustomerViewModel
    Public Property CustomFontSize As Double
    Public Property Customers As CustomerCollection
End Class

public class Customer { public string Name { get; set; } }
public class CustomerCollection : List<Customer> { }
public class CustomerViewModel
{
    public double CustomFontSize { get; set; }
    public CustomerCollection Customers { get; set; }
}

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Partager via