Export (0) Print
Expand All

PriorityBinding Class

Describes a collection of Binding objects that is attached to a single binding target property, which receives its value from the first binding in the collection that produces a value successfully.

Namespace:  System.Windows.Data
Assembly:  PresentationFramework (in PresentationFramework.dll)
XMLNS for XAML: http://schemas.microsoft.com/winfx/2006/xaml/presentation, http://schemas.microsoft.com/netfx/2007/xaml/presentation

[ContentPropertyAttribute("Bindings")]
public class PriorityBinding : BindingBase, 
	IAddChild
<PriorityBinding>
  Bindings
</PriorityBinding>

The PriorityBinding type exposes the following members.

  NameDescription
Public methodPriorityBindingInitializes a new instance of the PriorityBinding class.
Top

  NameDescription
Public propertyBindingGroupNameGets or sets the name of the BindingGroup to which this binding belongs. (Inherited from BindingBase.)
Public propertyBindingsGets the collection of Binding objects that is established for this instance of PriorityBinding.
Public propertyDelayGets or sets the amount of time, in milliseconds, to wait before updating the binding source after the value on the target changes. (Inherited from BindingBase.)
Public propertyFallbackValueGets or sets the value to use when the binding is unable to return a value. (Inherited from BindingBase.)
Public propertyStringFormatGets or sets a string that specifies how to format the binding if it displays the bound value as a string. (Inherited from BindingBase.)
Public propertyTargetNullValueGets or sets the value that is used in the target when the value of the source is null. (Inherited from BindingBase.)
Top

  NameDescription
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodProvideValueReturns an object that should be set on the property where this binding and extension are applied. (Inherited from BindingBase.)
Public methodShouldSerializeBindingsReturns a value that indicates whether serialization processes should serialize the effective value of the Bindings property on instances of this class.
Public methodShouldSerializeFallbackValueReturns a value that indicates whether serialization processes should serialize the effective value of the FallbackValue property on instances of this class. (Inherited from BindingBase.)
Public methodShouldSerializeTargetNullValueReturns a value that indicates whether the TargetNullValue property should be serialized. (Inherited from BindingBase.)
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

  NameDescription
Explicit interface implemetationPrivate methodIAddChild.AddChildThis member supports the Windows Presentation Foundation (WPF) infrastructure and is not intended to be used directly from your code.
Explicit interface implemetationPrivate methodIAddChild.AddTextThis member supports the Windows Presentation Foundation (WPF) infrastructure and is not intended to be used directly from your code.
Top

PriorityBinding lets you associate a binding target (target) property with a list of bindings. The first binding that returns a value successfully becomes the active binding.

A binding returns a value successfully if:

  1. The path to the binding source resolves successfully.

  2. The value converter, if any, is able to convert the resulting value.

  3. The resulting value is valid for the target property.

The value DependencyProperty.UnsetValue is not considered a successful return value.

The priority of the bindings is determined by their order in the list. The binding that appears first in the list has the highest priority.

The binding engine starts with the first binding in the list and verifies whether that binding returns a value successfully; if it does, the value from that binding is used. If the first binding does not return a value successfully, the binding engine examines the second binding to determine whether it returns a value successfully; if it does, the value from the second binding becomes the active value. This verification process continues to the end of the list of bindings. If none of the bindings returns a value successfully, the binding uses the FallbackValue.

The binding engine continues to listen for changes on all bindings. If at any point one of the bindings that has a higher priority returns a value successfully, the value for that binding becomes the active value and replaces the current value.

PriorityBinding in Windows Presentation Foundation (WPF) works by specifying a list of bindings. The list of bindings is ordered from highest priority to lowest priority. If the highest priority binding returns a value successfully when it is processed then there is never a need to process the other bindings in the list. It could be the case that the highest priority binding takes a long time to be evaluated, the next highest priority that returns a value successfully will be used until a binding of a higher priority returns a value successfully.

To demonstrate how PriorityBinding works, the AsyncDataSource object has been created with the following three properties: FastDP, SlowerDP, and SlowestDP.

The get accessor of FastDP returns the value of the _fastDP data member.

The get accessor of SlowerDP waits for 3 seconds before returning the value of the _slowerDP data member.

The get accessor of SlowestDP waits for 5 seconds before returning the value of the _slowestDP data member.

NoteNote

This example is for demonstration purposes only. The Microsoft .NET guidelines recommend against defining properties that are orders of magnitude slower than a field set would be. For more information, see Choosing Between Properties and Methods.

public class AsyncDataSource
{
	private string _fastDP;
	private string _slowerDP;
	private string _slowestDP;

	public AsyncDataSource()
	{
	}

	public string FastDP
	{
    get { return _fastDP; }
    set { _fastDP = value; }
	}

	public string SlowerDP
	{
    get
    {
      // This simulates a lengthy time before the 
      // data being bound to is actualy available.
      Thread.Sleep(3000);
      return _slowerDP;
    }
    set { _slowerDP = value; }
	}

	public string SlowestDP
	{
    get
    {
      // This simulates a lengthy time before the 
      // data being bound to is actualy available.
      Thread.Sleep(5000);
      return _slowestDP;
    }
    set { _slowestDP = value; }
	}
}

The Text property binds to the above AsyncDS using PriorityBinding:

<Window.Resources>
  <c:AsyncDataSource SlowestDP="Slowest Value" SlowerDP="Slower Value"
                     FastDP="Fast Value" x:Key="AsyncDS" />
</Window.Resources>
	
<StackPanel HorizontalAlignment="Center" VerticalAlignment="Center"
  DataContext="{Binding Source={StaticResource AsyncDS}}">
  <TextBlock FontSize="18" FontWeight="Bold" Margin="10"
    HorizontalAlignment="Center">Priority Binding</TextBlock>
  <TextBlock Background="Honeydew" Width="100" HorizontalAlignment="Center">
    <TextBlock.Text>
      <PriorityBinding FallbackValue="defaultvalue">
        <Binding Path="SlowestDP" IsAsync="True"/>
        <Binding Path="SlowerDP" IsAsync="True"/>
        <Binding Path="FastDP" />
      </PriorityBinding>
    </TextBlock.Text>
  </TextBlock>	
</StackPanel>

When the binding engine processes the Binding objects, it starts with the first Binding, which is bound to the SlowestDP property. When this Binding is processed, it does not return a value successfully because it is sleeping for 5 seconds, so the next Binding element is processed. The next Binding does not return a value successfully because it is sleeping for 3 seconds. The binding engine then moves onto the next Binding element, which is bound to the FastDP property. This Binding returns the value "Fast Value". The TextBlock now displays the value "Fast Value".

After 3 seconds elapses, the SlowerDP property returns the value "Slower Value". The TextBlock then displays the value "Slower Value".

After 5 seconds elapses, the SlowestDP property returns the value "Slowest Value". That binding has the highest priority because it is listed first. The TextBlock now displays the value "Slowest Value".

See PriorityBinding for information about what is considered a successful return value from a binding.

.NET Framework

Supported in: 4.6, 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

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