DependencyPropertyChangedEventArgs
DependencyPropertyChangedEventArgs
DependencyPropertyChangedEventArgs
DependencyPropertyChangedEventArgs
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// This API is not available in Javascript.
- Attributes
| Device family |
Windows 10 (introduced v10.0.10240.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v1)
|
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
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 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// This API is not available in Javascript.
- Value
- PlatForm::Object object object object
The dependency property value after the change.
- See Also
OldValue 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// This API is not available in Javascript.
- Value
- PlatForm::Object object object object
The dependency property value before the change.
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 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// This API is not available in Javascript.
The identifier field of the dependency property where the value change occurred.
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