Dependency​Property​Changed​Event​Args Dependency​Property​Changed​Event​Args Dependency​Property​Changed​Event​Args Class

Definition

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 sealed class DependencyPropertyChangedEventArgs : IDependencyPropertyChangedEventArgspublic sealed class DependencyPropertyChangedEventArgs : IDependencyPropertyChangedEventArgsPublic NotInheritable Class DependencyPropertyChangedEventArgs Implements IDependencyPropertyChangedEventArgs
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

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

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.

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();
    }

Private Shared Sub ValueChangedCallback(ByVal obj As DependencyObject, _
                    ByVal args As DependencyPropertyChangedEventArgs)

    Dim ctl As NumericUpDown = DirectCast(obj, NumericUpDown)
    Dim newValue As Integer = args.NewValue

    ' Update the TextElement to the new value. 
    If ctl.TextElement IsNot Nothing Then
        ctl.TextElement.Text = newValue.ToString()
    End If

Properties

NewValue NewValue NewValue

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

public PlatForm::Object NewValue { get; }public object NewValue { get; }Public ReadOnly Property NewValue As object
Value
object object object

The dependency property value after the change.

Attributes
See Also

OldValue OldValue OldValue

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

public PlatForm::Object OldValue { get; }public object OldValue { get; }Public ReadOnly Property OldValue As object
Value
object object object

The dependency property value before the change.

Attributes

Remarks

The OldValue value is often used as the value that the property is set to from within the callback, in case the NewValue value is not considered a valid value for your property's logic . For example, if you are using the callback for validation of an input value for a property that the user can set in UI, the previous value is typically a better value to use as the current value rather than resetting the value to a default. The callback is effectively canceling a change.

See Also

Property Property Property

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

public DependencyProperty Property { get; }public DependencyProperty Property { get; }Public ReadOnly Property Property As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier field of the dependency property where the value change occurred.

Attributes

Remarks

In many cases the dependency property being changed is known implicitly, because you're checking the DependencyPropertyChangedEventArgs data in a callback that's dedicated for use only by one defined dependency property. The Property property makes it possible to share a PropertyChangedCallback as a common callback for more than one PropertyMetadata instance and more than one dependency property. For example, you might have handler logic that first checks Property and then branches behavior (like knowing how to cast NewValue ) depending on which property's change invoked the handler in this event case:

private static void OnGravityPropertiesChanged(DependencyObject d, DependencyPropertyChangedEventArgs e) {
    if (e.Property==Planet.GravityFactorProperty) {
        //GravityFactor is a Double, cast e.NewValue to Double, do logic
    }
    if (e.Property==Planet.IsGravityOnProperty) {
        //IsGravityOn is a Boolean, cast e.NewValue to Boolean, do logic
    }
}
See Also

See Also