• Article

RelativeSource Class

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

Implements a markup extension that describes the location of the binding source relative to the position of the binding target.

Inheritance Hierarchy

System.Object
  System.Windows.Markup.MarkupExtension
    System.Windows.Data.RelativeSource

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

Syntax

'Declaration
Public Class RelativeSource _
    Inherits MarkupExtension _
    Implements ISupportInitialize

public class RelativeSource : MarkupExtension, 
    ISupportInitialize

See Remarks

The RelativeSource type exposes the following members.

Constructors

  Name Description
Public methodSupported by Silverlight for Windows Phone RelativeSource() Initializes a new instance of the RelativeSource class by using the default relative source mode.
Public methodSupported by Silverlight for Windows Phone RelativeSource(RelativeSourceMode) Initializes a new instance of the RelativeSource class by using the specified relative source mode.

Top

Properties

  Name Description
Public property AncestorLevel Gets or sets the level of ancestor to look for, in FindAncestor mode. Use 1 to indicate the one nearest to the binding target element.
Public property AncestorType Gets or sets the type of ancestor to look for.
Public propertySupported by Silverlight for Windows Phone Mode Gets or sets a value that describes the location of the binding source relative to the position of the binding target.

Top

Methods

  Name Description
Public methodSupported by Silverlight for Windows Phone Equals(Object) Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodSupported by Silverlight for Windows Phone Finalize Allows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.)
Public methodSupported by Silverlight for Windows Phone GetHashCode Serves as a hash function for a particular type. (Inherited from Object.)
Public methodSupported by Silverlight for Windows Phone GetType Gets the Type of the current instance. (Inherited from Object.)
Protected methodSupported by Silverlight for Windows Phone MemberwiseClone Creates a shallow copy of the current Object. (Inherited from Object.)
Public method ProvideValue Returns an object that should be set as the value on the target object's property for this markup extension. For RelativeSource, this is another RelativeSource, using the appropriate source for the specified mode. (Overrides MarkupExtension.ProvideValue(IServiceProvider).)
Public methodSupported by Silverlight for Windows Phone ToString Returns a string that represents the current object. (Inherited from Object.)

Top

Explicit Interface Implementations

  Name Description
Explicit interface implemetationPrivate method ISupportInitialize.BeginInit Infrastructure. Signals the object that initialization is starting.
Explicit interface implemetationPrivate method ISupportInitialize.EndInit Infrastructure. Signals the object that initialization is complete.

Top

Remarks

For XAML usage of RelativeSource, see RelativeSource Markup Extension.

RelativeSource is a class that supports a XAML markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or to use type converters. All markup extensions in XAML use curly braces ({}) in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute. For more information, see the "Markup Extensions" section of XAML Overview. The RelativeSource Markup Extension is specifically required for setting the Binding.RelativeSource property as a XAML attribute.

Examples

The following Silverlight 5 code example demonstrates the use of this class. 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.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.