CoerceValueCallback Delegate

Provides a template for a method that is called whenever a dependency property value is being re-evaluated, or coercion is specifically requested.

Namespace: System.Windows
Assembly: WindowsBase (in windowsbase.dll)

public delegate Object CoerceValueCallback (
	DependencyObject d,
	Object baseValue
/** @delegate */
public delegate Object CoerceValueCallback (
	DependencyObject d, 
	Object baseValue
In XAML, you can use delegates but you cannot define your own.



The object that the property exists on. When the callback is invoked, the property system will pass this value.


The new value of the property, prior to any coercion attempt.

Return Value

The coerced value (with appropriate type).

Callbacks based on CoerceValueCallback can be assigned to a dependency property through several different techniques. Each of these techniques requires that you first create a new property metadata object (PropertyMetadata, or a derived class such as FrameworkPropertyMetadata). Create the metadata object using a constructor signature that takes the coerceValueCallback parameter, and assign that parameter to your callback handler. Or construct the metadata by any signature and set the CoerceValueCallback property prior to putting the metadata in use.

One you have this metadata, you can:

  • Define a new dependency property on a new class, using either signature of Register, giving the metadata as the typeMetadata value.

  • Override the metadata (call OverrideMetadata(Type,PropertyMetadata)) for an existing dependency property, when you derive from the class that owns the dependency property.

  • Add an existing dependency property to a new DependencyObject class, using new metadata, by calling AddOwner(Type,PropertyMetadata).

Implementations of this callback should check the value in baseValue and determine based on either the value or the type whether this is a value that needs to be further coerced.

The CoerceValueCallback for a dependency property is invoked any time that the property system or any other caller calls CoerceValue on a DependencyObject instance, specifying that property's identifier as the dp.

Changes to the property value may have come from any possible participant in the property system. This includes styles, generic invalidation, triggers, propertyvalue inheritance, and local value setting.

Generally you should avoid specifying more than one CoerceValueCallback for any given dependency property (overriding or adding with new metadata for a dependency property that already had a CoerceValueCallback). Only one of the callbacks will be able to act. The acting callback will be the one that was applied to the most derived class in the inheritance as compared to the DependencyObject caller. Other callbacks as assigned to metadata for the dependency property as it existed higher in the owner hierarchy are replaced when the metadata is overridden.

The following example includes an implementation of this callback to coerce the stored value of a dependency property based on other inputs, such as another property's value. In this case, the callback checks to see whether the ShirtType property corresponds to a type of shirt that has buttons; if so it establishes a starting default color for the ButtonColor, if the shirt type has no buttons, it coerces the ButtonColor value back to a starting value, which causes the UI (not shown) to remove that dropdown from the effective choices. For the complete sample, see Custom Classes with Dependency Properties Sample.

private static object CoerceButtonColor(DependencyObject d, object value)
    ShirtTypes newShirtType = (d as Shirt).ShirtType;
    if (newShirtType == ShirtTypes.Dress || newShirtType == ShirtTypes.Bowling)
        return ButtonColors.Black;                
    return ButtonColors.None;

Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0