|
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.
//
// Description: Helper operations for data bindings.
//
// See spec at Data Binding.mht
//
using System.Collections;
using System.Collections.ObjectModel;
using System.Threading;
using MS.Internal.Data;
namespace System.Windows.Data
{
/// <summary>
/// Operations to manipulate data bindings.
/// </summary>
public static class BindingOperations
{
//------------------------------------------------------
//
// Public Properties
//
//------------------------------------------------------
/// <summary>
/// A sentinel object. WPF assigns this as the DataContext of elements
/// that leave an ItemsControl because (a) the corresponding item is
/// removed from the ItemsSource collection, or (b) the element is
/// scrolled out of view and re-virtualized. Bindings that use DataContext
/// react by unhooking from property-changed events. This keeps the
/// discarded elements from interfering with the still-visible elements.
/// </summary>
public static object DisconnectedSource
{
get { return BindingExpressionBase.DisconnectedItem; }
}
//------------------------------------------------------
//
// Public Methods
//
//------------------------------------------------------
/// <summary>
/// Attach a BindingExpression to a property.
/// </summary>
/// <remarks>
/// A new BindingExpression is created from the given description, and attached to
/// the given property of the given object. This method is the way to
/// attach a Binding to an arbitrary DependencyObject that may not expose
/// its own SetBinding method.
/// </remarks>
/// <param name="target">object on which to attach the Binding</param>
/// <param name="dp">property to which to attach the Binding</param>
/// <param name="binding">description of the Binding</param>
/// <exception cref="ArgumentNullException"> target and dp and binding cannot be null </exception>
public static BindingExpressionBase SetBinding(DependencyObject target, DependencyProperty dp, BindingBase binding)
{
ArgumentNullException.ThrowIfNull(target);
ArgumentNullException.ThrowIfNull(dp);
ArgumentNullException.ThrowIfNull(binding);
// target.VerifyAccess();
BindingExpressionBase bindExpr = binding.CreateBindingExpression(target, dp);
// BUG: should prevent transfers and updates until BindingExpression is ready
//BindingExpression.SetFlag(BindingFlags.iInTransfer | BindingFlags.iInUpdate);
target.SetValue(dp, bindExpr);
return bindExpr;
}
/// <summary>
/// Retrieve a BindingBase.
/// </summary>
/// <remarks>
/// This method returns null if no Binding has been set on the given
/// property.
/// </remarks>
/// <param name="target">object from which to retrieve the binding</param>
/// <param name="dp">property from which to retrieve the binding</param>
/// <exception cref="ArgumentNullException"> target and dp cannot be null </exception>
public static BindingBase GetBindingBase(DependencyObject target, DependencyProperty dp)
{
BindingExpressionBase b = GetBindingExpressionBase(target, dp);
return (b != null) ? b.ParentBindingBase : null;
}
/// <summary>
/// Retrieve a Binding.
/// </summary>
/// <remarks>
/// This method returns null if no Binding has been set on the given
/// property.
/// </remarks>
/// <param name="target">object from which to retrieve the binding</param>
/// <param name="dp">property from which to retrieve the binding</param>
/// <exception cref="ArgumentNullException"> target and dp cannot be null </exception>
public static Binding GetBinding(DependencyObject target, DependencyProperty dp)
{
return GetBindingBase(target, dp) as Binding;
}
/// <summary>
/// Retrieve a PriorityBinding.
/// </summary>
/// <remarks>
/// This method returns null if no Binding has been set on the given
/// property.
/// </remarks>
/// <param name="target">object from which to retrieve the binding</param>
/// <param name="dp">property from which to retrieve the binding</param>
/// <exception cref="ArgumentNullException"> target and dp cannot be null </exception>
public static PriorityBinding GetPriorityBinding(DependencyObject target, DependencyProperty dp)
{
return GetBindingBase(target, dp) as PriorityBinding;
}
/// <summary>
/// Retrieve a MultiBinding.
/// </summary>
/// <remarks>
/// This method returns null if no Binding has been set on the given
/// property.
/// </remarks>
/// <param name="target">object from which to retrieve the binding</param>
/// <param name="dp">property from which to retrieve the binding</param>
/// <exception cref="ArgumentNullException"> target and dp cannot be null </exception>
public static MultiBinding GetMultiBinding(DependencyObject target, DependencyProperty dp)
{
return GetBindingBase(target, dp) as MultiBinding;
}
/// <summary>
/// Retrieve a BindingExpressionBase.
/// </summary>
/// <remarks>
/// This method returns null if no Binding has been set on the given
/// property.
/// </remarks>
/// <param name="target">object from which to retrieve the BindingExpression</param>
/// <param name="dp">property from which to retrieve the BindingExpression</param>
/// <exception cref="ArgumentNullException"> target and dp cannot be null </exception>
public static BindingExpressionBase GetBindingExpressionBase(DependencyObject target, DependencyProperty dp)
{
ArgumentNullException.ThrowIfNull(target);
ArgumentNullException.ThrowIfNull(dp);
// target.VerifyAccess();
Expression expr = StyleHelper.GetExpression(target, dp);
return expr as BindingExpressionBase;
}
/// <summary>
/// Retrieve a BindingExpression.
/// </summary>
/// <remarks>
/// This method returns null if no Binding has been set on the given
/// property.
/// </remarks>
/// <param name="target">object from which to retrieve the BindingExpression</param>
/// <param name="dp">property from which to retrieve the BindingExpression</param>
/// <exception cref="ArgumentNullException"> target and dp cannot be null </exception>
public static BindingExpression GetBindingExpression(DependencyObject target, DependencyProperty dp)
{
BindingExpressionBase expr = GetBindingExpressionBase(target, dp);
PriorityBindingExpression pb = expr as PriorityBindingExpression;
if (pb != null)
expr = pb.ActiveBindingExpression;
return expr as BindingExpression;
}
/// <summary>
/// Retrieve a MultiBindingExpression.
/// </summary>
/// <remarks>
/// This method returns null if no MultiBinding has been set on the given
/// property.
/// </remarks>
/// <param name="target">object from which to retrieve the MultiBindingExpression</param>
/// <param name="dp">property from which to retrieve the MultiBindingExpression</param>
/// <exception cref="ArgumentNullException"> target and dp cannot be null </exception>
public static MultiBindingExpression GetMultiBindingExpression(DependencyObject target, DependencyProperty dp)
{
return GetBindingExpressionBase(target, dp) as MultiBindingExpression;
}
/// <summary>
/// Retrieve a PriorityBindingExpression.
/// </summary>
/// <remarks>
/// This method returns null if no PriorityBinding has been set on the given
/// property.
/// </remarks>
/// <param name="target">object from which to retrieve the PriorityBindingExpression</param>
/// <param name="dp">property from which to retrieve the PriorityBindingExpression</param>
/// <exception cref="ArgumentNullException"> target and dp cannot be null </exception>
public static PriorityBindingExpression GetPriorityBindingExpression(DependencyObject target, DependencyProperty dp)
{
return GetBindingExpressionBase(target, dp) as PriorityBindingExpression;
}
/// <summary>
/// Remove data Binding (if any) from a property.
/// </summary>
/// <remarks>
/// If the given property is data-bound, via a Binding, PriorityBinding or MultiBinding,
/// the BindingExpression is removed, and the property's value changes to what it
/// would be as if no local value had ever been set.
/// If the given property is not data-bound, this method has no effect.
/// </remarks>
/// <param name="target">object from which to remove Binding</param>
/// <param name="dp">property from which to remove Binding</param>
/// <exception cref="ArgumentNullException"> target and dp cannot be null </exception>
public static void ClearBinding(DependencyObject target, DependencyProperty dp)
{
ArgumentNullException.ThrowIfNull(target);
ArgumentNullException.ThrowIfNull(dp);
// target.VerifyAccess();
if (IsDataBound(target, dp))
target.ClearValue(dp);
}
/// <summary>
/// Remove all data Binding (if any) from a DependencyObject.
/// </summary>
/// <param name="target">object from which to remove bindings</param>
/// <exception cref="ArgumentNullException"> DependencyObject target cannot be null </exception>
public static void ClearAllBindings(DependencyObject target)
{
ArgumentNullException.ThrowIfNull(target);
// target.VerifyAccess();
LocalValueEnumerator lve = target.GetLocalValueEnumerator();
// Batch properties that have BindingExpressions since clearing
// during a local value enumeration is illegal
ArrayList batch = new ArrayList(8);
while (lve.MoveNext())
{
LocalValueEntry entry = lve.Current;
if (IsDataBound(target, entry.Property))
{
batch.Add(entry.Property);
}
}
// Clear all properties that are storing BindingExpressions
for (int i = 0; i < batch.Count; i++)
{
target.ClearValue((DependencyProperty)batch[i]);
}
}
/// <summary>Return true if the property is currently data-bound</summary>
/// <exception cref="ArgumentNullException"> DependencyObject target cannot be null </exception>
public static bool IsDataBound(DependencyObject target, DependencyProperty dp)
{
ArgumentNullException.ThrowIfNull(target);
ArgumentNullException.ThrowIfNull(dp);
// target.VerifyAccess();
object o = StyleHelper.GetExpression(target, dp);
return (o is BindingExpressionBase);
}
/// <summary>
/// Register a callback used to synchronize access to a given collection.
/// </summary>
/// <param name="collection"> The collection that needs synchronized access. </param>
/// </param name="context"> An arbitrary object. This object is passed back into
/// the callback; it is not used otherwise. It provides a way for the
/// application to store information it knows at registration time, which it
/// can then use at collection-access time. Typically this information will
/// help the application determine the synchronization mechanism used to
/// control access to the given collection. </param>
/// <param name="synchronizationCallback"> The callback to be invoked whenever
/// access to the collection is required. </param>
public static void EnableCollectionSynchronization(
IEnumerable collection,
object context,
CollectionSynchronizationCallback synchronizationCallback)
{
ArgumentNullException.ThrowIfNull(collection);
ArgumentNullException.ThrowIfNull(synchronizationCallback);
ViewManager.Current.RegisterCollectionSynchronizationCallback(
collection, context, synchronizationCallback);
}
/// <summary>
/// Register a lock object used to synchronize access to a given collection.
/// </summary>
/// <param name="collection"> The collection that needs synchronized access. </param>
/// <param name="lockObject"> The object to lock when accessing the collection. </param>
public static void EnableCollectionSynchronization(
IEnumerable collection,
object lockObject)
{
ArgumentNullException.ThrowIfNull(collection);
ArgumentNullException.ThrowIfNull(lockObject);
ViewManager.Current.RegisterCollectionSynchronizationCallback(
collection, lockObject, null);
}
/// <summary>
/// Remove the synchronization registered for a given collection. Any subsequent
/// access to the collection will be unsynchronized.
/// </summary>
/// <param name="collection"> The collection that needs its synchronized access removed. </param>
public static void DisableCollectionSynchronization(
IEnumerable collection)
{
ArgumentNullException.ThrowIfNull(collection);
ViewManager.Current.RegisterCollectionSynchronizationCallback(
collection, null, null);
}
/// <summary>
/// A caller can use this method to access a collection using the
/// synchronization that the application has registered for that collection.
/// If no synchronization is registered, the access method is simply called
/// directly.
/// </summary>
/// <notes>
/// 1. This method is provided chiefly for collection views, which need to
/// redirect access through the application-provided synchronization pattern.
/// An application typically doesn't need to call it, as the application
/// can use its synchronization directly.
/// 2. It is usually convenient to provide a closure as the access
/// method. This closure will have access to local variables at the
/// site of the call. For example, the following code reads _collection[3]:
/// void MyMethod()
/// {
/// int index = 3;
/// int result = 0;
/// BindingOperations.AccessCollection(
/// _collection,
/// () => { result = _collection[index]; },
/// false); // read-access
/// }
/// Note that the access method refers to local variables (index, result)
/// of MyMethod, as well as to an instance variable (_collection) of the
/// 'this' object.
/// </notes>
public static void AccessCollection(
IEnumerable collection,
Action accessMethod,
bool writeAccess)
{
ViewManager vm = ViewManager.Current;
if (vm == null)
throw new InvalidOperationException(SR.Format(SR.AccessCollectionAfterShutDown, collection));
vm.AccessCollection(collection, accessMethod, writeAccess);
}
/// <summary>
/// Returns a list of all binding expressions that are:
/// a) top-level (do not belong to a parent MultiBindingExpression or BindingGroup)
/// b) source-updating (binding mode is TwoWay or OneWayToSource)
/// c) currently dirty or invalid
/// and d) attached to a descendant of the given DependencyObject (if non-null).
/// These are the bindings that may need attention before executing a command.
/// </summary>
public static ReadOnlyCollection<BindingExpressionBase> GetSourceUpdatingBindings(DependencyObject root)
{
List<BindingExpressionBase> list = DataBindEngine.CurrentDataBindEngine.CommitManager.GetBindingsInScope(root);
return new ReadOnlyCollection<BindingExpressionBase>(list);
}
/// <summary>
/// Returns a list of all BindingGroups that are:
/// a) currently dirty or invalid
/// and b) attached to a descendant of the given DependencyObject (if non-null).
/// </summary>
public static ReadOnlyCollection<BindingGroup> GetSourceUpdatingBindingGroups(DependencyObject root)
{
List<BindingGroup> list = DataBindEngine.CurrentDataBindEngine.CommitManager.GetBindingGroupsInScope(root);
return new ReadOnlyCollection<BindingGroup>(list);
}
//------------------------------------------------------
//
// Public Events
//
//------------------------------------------------------
/// <summary>
/// This event is raised when a collection is first noticed by the data-binding system.
/// It provides an opportunity to register information about the collection,
/// before the data-binding system begins to use the collection.
/// </summary>
/// <notes>
/// In an application with multiple UI threads (i.e. multiple Dispatchers),
/// this event is raised independently on each thread the first time the
/// collection is noticed on that thread.
/// </notes>
public static event EventHandler<CollectionRegisteringEventArgs> CollectionRegistering;
/// <summary>
/// This event is raised when a collection view is first noticed by the data-binding system.
/// It provides an opportunity to modify the collection view,
/// before the data-binding system begins to use it.
/// </summary>
/// <notes>
/// In an application with multiple UI threads (i.e. multiple Dispatchers),
/// each thread has its own set of collection views. This event is raised
/// on the thread that owns the given collection view.
/// </notes>
public static event EventHandler<CollectionViewRegisteringEventArgs> CollectionViewRegistering;
//------------------------------------------------------
//
// Internal Methods
//
//------------------------------------------------------
// return false if this is an invalid value for UpdateSourceTrigger
internal static bool IsValidUpdateSourceTrigger(UpdateSourceTrigger value)
{
switch (value)
{
case UpdateSourceTrigger.Default:
case UpdateSourceTrigger.PropertyChanged:
case UpdateSourceTrigger.LostFocus:
case UpdateSourceTrigger.Explicit:
return true;
default:
return false;
}
}
// The following properties and methods have no internal callers. They
// can be called by suitably privileged external callers via reflection.
// They are intended to be used by test programs and the DRT.
// Enable or disable the cleanup pass. For use by tests that measure
// perf, to avoid noise from the cleanup pass.
internal static bool IsCleanupEnabled
{
get { return DataBindEngine.CurrentDataBindEngine.CleanupEnabled; }
set { DataBindEngine.CurrentDataBindEngine.CleanupEnabled = value; }
}
// Force a cleanup pass (even if IsCleanupEnabled is true). For use
// by leak-detection tests, to avoid false leak reports about objects
// held by the DataBindEngine that can be cleaned up. Returns true
// if something was actually cleaned up.
internal static bool Cleanup()
{
return DataBindEngine.CurrentDataBindEngine.Cleanup();
}
// Print various interesting statistics
[Conditional("DEBUG")]
internal static void PrintStats()
{
DataBindEngine.CurrentDataBindEngine.AccessorTable.PrintStats();
}
// Trace the size of the accessor table after each generation
internal static bool TraceAccessorTableSize
{
get { return DataBindEngine.CurrentDataBindEngine.AccessorTable.TraceSize; }
set { DataBindEngine.CurrentDataBindEngine.AccessorTable.TraceSize = value; }
}
// Raise the CollectionRegistering event
internal static void OnCollectionRegistering(IEnumerable collection, object parent)
{
if (CollectionRegistering != null)
CollectionRegistering(null, new CollectionRegisteringEventArgs(collection, parent));
}
// Raise the CollectionViewRegistering event
internal static void OnCollectionViewRegistering(CollectionView view)
{
if (CollectionViewRegistering != null)
CollectionViewRegistering(null, new CollectionViewRegisteringEventArgs(view));
}
#if LiveShapingInstrumentation
public static void SetNodeSize(int nodeSize)
{
LiveShapingBlock.SetNodeSize(nodeSize);
}
public static void SetQuickSortThreshold(int threshold)
{
LiveShapingTree.SetQuickSortThreshold(threshold);
}
public static void SetBinarySearchThreshold(int threshold)
{
LiveShapingTree.SetBinarySearchThreshold(threshold);
}
public static void ResetComparisons(ListCollectionView lcv)
{
lcv.ResetComparisons();
}
public static void ResetCopies(ListCollectionView lcv)
{
lcv.ResetCopies();
}
public static void ResetAverageCopy(ListCollectionView lcv)
{
lcv.ResetAverageCopy();
}
public static int GetComparisons(ListCollectionView lcv)
{
return lcv.GetComparisons();
}
public static int GetCopies(ListCollectionView lcv)
{
return lcv.GetCopies();
}
public static double GetAverageCopy(ListCollectionView lcv)
{
return lcv.GetAverageCopy();
}
#endif // LiveShapingInstrumentation
#region Exception logging
// For use when testing whether an exception is thrown, even though the
// exception is caught. The catch-block logs the exception, and the
// test code can examine the log.
// Enable exception-logging.
// Test code uses the following pattern (suitably translated to reflection-based calls):
// using (ExceptionLogger logger = BindingOperations.EnableExceptionLogging())
// {
// DoSomethingThatMightThrowACaughtException();
// if (logger.Log.Count > 0)
// {
// // an exception was thrown - react appropriately
// }
// }
internal static IDisposable EnableExceptionLogging()
{
ExceptionLogger newLogger = new ExceptionLogger();
Interlocked.CompareExchange<ExceptionLogger>(ref _exceptionLogger, newLogger, null);
return _exceptionLogger;
}
// Log an exception, if logging is active (called from framework catch-blocks that opt-in)
internal static void LogException(Exception ex)
{
ExceptionLogger logger = _exceptionLogger;
if (logger != null)
{
logger.LogException(ex);
}
}
private static ExceptionLogger _exceptionLogger;
internal class ExceptionLogger : IDisposable
{
// Log an exception
internal void LogException(Exception ex)
{
_log.Add(ex);
}
// when the active logger is disposed, turn off logging
void IDisposable.Dispose()
{
Interlocked.CompareExchange<ExceptionLogger>(ref _exceptionLogger, null, this);
}
internal List<Exception> Log { get { return _log; } }
List<Exception> _log = new List<Exception>();
}
#endregion Exception logging
}
}
|