Share via

DependencyPropertyChangedEventArgs Class

  • Reference

Definition

Namespace:
Microsoft.UI.Xaml
Edit

Provides data for a PropertyChangedCallback implementation that is invoked when a dependency property changes its value. Also provides event data for the Control.IsEnabledChanged event and any other event that uses the DependencyPropertyChangedEventHandler delegate.

public ref class DependencyPropertyChangedEventArgs sealed
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
class DependencyPropertyChangedEventArgs final
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
public sealed class DependencyPropertyChangedEventArgs
Public NotInheritable Class DependencyPropertyChangedEventArgs
Inheritance
Object Platform::Object IInspectable DependencyPropertyChangedEventArgs
Attributes
ContractVersionAttribute MarshalingBehaviorAttribute

Examples

This example shows a PropertyChangedCallback implementation that uses the DependencyPropertyChangedEventArgs event data. In particular, it uses NewValue to set a related property, which displays the underlying numeric DependencyProperty value as text, in a TextBlock part of a composite control.

private static void ValueChangedCallback(DependencyObject obj, DependencyPropertyChangedEventArgs args)
{
    NumericUpDown ctl = (NumericUpDown)obj;
    Int32 newValue = (Int32)args.NewValue;

    // Update the TextElement to the new value.
    if (ctl.TextElement != null)
    {
        ctl.TextElement.Text = newValue.ToString();
    }

Remarks

DependencyPropertyChangedEventArgs provides data for two different situations that involve changes to dependency property values:

  • Situational callback information as used by a PropertyChangedCallback for a custom dependency property. This is the more common case.
  • Event data for an event based on DependencyPropertyChangedEventHandler. This is less common because the only Windows Runtime event that uses this delegate is the Control.IsEnabledChanged event. For more info on how to use the DependencyPropertyChangedEventArgs event data in this case, see DependencyPropertyChangedEventHandler or Control.IsEnabledChanged.

A PropertyChangedCallback implementation is an optional part of the property metadata that you provide when you register a dependency property. The callback is invoked by the dependency property system internally. For more info on dependency properties in general, see Custom dependency properties and Dependency properties overview.

Typically you define the method with private or internal access. The method must be static. Because the method is static, the DependencyObject parameter (d) of the PropertyChangedCallback delegate is important. That's what identifies the specific dependency object instance where the property is changing. For many operations, such as correcting or coercing a value, or changing another calculated property value in response on the same object, you'll reference this DependencyObject. You'll typically want to cast it to the owner type of the property that changes. The owner type is the type referenced by name in the DependencyProperty.Register call; the metadata where your PropertyChangedCallback is assigned to property metadata is part of that same call.

Be aware of the possibility for recursion. If you change the value of a dependency property that the PropertyChangedCallback is invoked for, it will be invoked again. For example, if you created a callback for a Double property where the callback always divided the value by 2, that callback would be called recursively and your app would be in an infinite loop.

It's legal to have two or more different dependency properties define callbacks to change each other, but again be careful to not create an unintentional circular dependency that doesn't enable the values to stabilize.

A PropertyChangedCallback is only invoked if OldValue and NewValue in the event data is different.

OldValue and NewValue come untyped, so any comparison you perform probably needs a cast. Many dependency property values are using a value type, which means you'll be relying on the operators or other API of the value type to make the comparisons. That functionality is usually available on the structure that represents a value, as a utility API. For example, the language-specific utility API on a Thickness value enables you to compare Thickness values.

Note

If you are programming using C++, a few of the Windows Runtime structures don't support nondata members, so don't support operators or other utility. For these, there is a companion Helper class that provides comparison API that C++ code can use. For example, use the ColorHelper class to compare Color values.

Using DependencyPropertyChangedEventArgs for a custom event

A custom control implementer might consider using DependencyPropertyChangedEventHandler as the delegate type if a custom event is fired as a result of a dependency property value change. You can only fire such an event from within the context of a PropertyChangedCallback. This is because the value that changed (the property, the old and new value) should be in the DependencyPropertyChangedEventArgs that are reported for the event at the property-system level. But there aren't any constructors for DependencyPropertyChangedEventArgs and none of its properties are settable, so the only way to get a DependencyPropertyChangedEventArgs value is to get it from the original PropertyChangedCallback parameters and pass it through when you fire your custom event.

Properties

NewValue

Gets the value of the dependency property after the reported change.
OldValue

Gets the value of the dependency property before the reported change.
Property

Gets the identifier for the dependency property where the value change occurred.

Applies to

See also