• Article

RelativeSource Markup Extension

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

Provides a means to specify the source of a binding in terms of a relative relationship in the run-time object graph.

XAML Attribute Usage (Self Mode)

<Binding RelativeSource="{RelativeSource Self}" .../>
-or-
<object property="{Binding RelativeSource={RelativeSource Self} ...}" .../>

XAML Attribute Usage (TemplatedParent Mode)

<Binding RelativeSource="{RelativeSource TemplatedParent}" .../>
-or-
<object property="{Binding RelativeSource={RelativeSource TemplatedParent} ...}" .../>

XAML Attribute Usage (FindAncestor Mode)

<Binding RelativeSource="{RelativeSource Mode=FindAncestor, AncestorType=typeNameString, AncestorLevel=levelInt }" .../>
-or-
<object property="{Binding RelativeSource="{RelativeSource Mode=FindAncestor, AncestorType=typeNameString, AncestorLevel=levelInt} ...}" .../>

XAML Values

{RelativeSource Self}

Produces a RelativeSource where the Mode value is 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.

{RelativeSource TemplatedParent}

Produces a RelativeSource where the Mode value is 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.

typeNameString

The name of the type that constrains the ancestor search. See AncestorType.

levelInt

A positive integer that constains the number of steps towards the object tree root that should be evaluated, when searching for types as named by typeNameString. See AncestorLevel.

Remarks

RelativeSource is 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 the { and } characters 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 "Markup Extensions" in XAML Overview. The RelativeSource markup extension is specifically required for setting the Binding.RelativeSource property as a XAML attribute.

RelativeSource is similar to Binding in that it is a markup extension that is capable of returning instances of itself, supporting a string-based construction that essentially passes an argument to the constructor. In this case, the argument being passed is the Mode value. The simple values can be either Self or TemplatedParent. The FindAncestor mode is somewhat more complex. Whenever you use FindAncestor mode, you generally specify an AncestorType value. If there is ambiguity with the tree walk that you are trying to avoid, you might also want to specify an AncestorLevel.

It is also possible to specify a verbose object element syntax for a FindAncestor mode, if that is desired for clarity. For example:

<Binding>
  <Binding.RelativeSource>
    <RelativeSource
      Mode="FindAncestor"
      AncestorType="typeName"
      AncestorLevel="levelInt"
    />
  </Binding.RelativeSource>
</Binding>

The XAML usage for RelativeSource shows only the usage for which it is intended: setting a value for Binding.RelativeSource in XAML as part of a binding expression. Theoretically, other usages are possible if setting a property where the value is RelativeSource. The Binding Markup Extension itself can set Binding.RelativeSource either as an attribute or as a component of the expression. This is why two different attribute syntaxes are shown.

The TemplatedParent mode is used for a data validation scenario where a template can establish the UI for error handling that occurs at run time. For details on this type of validation, see Validation or Data Binding.

The Self mode is useful for cases where the same element should be used as the source object and target object for a binding, but different properties are the source and the target. This is useful for binding one property of an element to another property on the same element, and is a variation on ElementName binding that does not require naming and then self-referencing the element. If you bind one property of an element to another property on the same element, either the properties must use the same property type, or you must also use a Converter on the binding to convert the values.

In WPF, RelativeSource supports a PreviousData mode; Silverlight 5 does not support that mode.