Styjun

I know the basic difference among these classes that PropertyMetadata is used when we backup property, UIPropertyMetadata when we want to have support for animation, and FrameworkMetadata for Framework properties to be used in user controls.

But I understand theoretical part only.
It will be a great hep if you please explain a simplest example that uses all these 3 classes in 3 different dependency properties distinguishing them clearly.

Thanks in advance.

Source: PropertyMetadata vs. FrameworkPropertyMetadata

When you implement a custom dependency property and you register the property by calling DependencyProperty.Register, you specify some metadata for the property by passing it an instance of PropertyMetadata. This can be an instance of the PropertyMetadata class or an instance of one of its subclasses. The differences are shown below.

PropertyMetadata – Basic metadata relating to dependency properties

• 
  CoerceValueCallback – coerce the value when being set


• 
  DefaultValue – a default value for the property


• 
  PropertyChangedCallback – respond to new effective value for the property

UIPropertyMetadata – derives from PropertyMetadata and adds:

• 
  IsAnimationProhibited – disable animations for this property?

FrameworkPropertyMetadata – derives from UIPropertyMetadata and adds:

• 
  AffectsArrange, AffectsMeasure, AffectsParentArrange, AffectsParentMeasure, AffectsRender – Should layout calculations be re-run after property value changes?


• 
  BindsTwoWayByDefault, DefaultUpdateSourceTrigger, IsDataBindingAllowed, IsNotDataBindable – Dictates how property participates in data binding


• 
  Inherits, OverridesInheritanceBehavior – Does inheritance work for this property?


• 
  Journal – Store this value when journaling?


• 
  SubPropertiesDoNotAffectRender – Check properties of this object when layout changes?

An important practical difference between PropertyMetadata and FrameworkPropertyMetadata is that the latter allows to specify a set of FrameworkPropertyMetadataOptions.

For example, specifying FrameworkPropertyMetadataOptions.AffectsRender cares for initiating a re-rendering of a UIElement on which the property has changed. Without this flag you would have to do that manually in a PropertyChangedCallback.

All of the behaviors exposed by FrameworkPropertyMetadata and UIPropertyMetadata are controlled by flag bits that are recorded in a single enum (32-bit uint) field called _flags which is declared in the PropertyMetadata base class, even though none of the flags are actually publicly exposed from there. Here is the declaration of that enum:

internal enum MetadataFlags : uint

 DefaultValueModifiedID /**/= 0b_00000000_00000000_00000000_00000001, //0x00000001
 SealedID /**/= 0b_00000000_00000000_00000000_00000010, //0x00000002
 Inherited /**/= 0b_00000000_00000000_00000000_00010000, //0x00000010
 UI_IsAnimationProhibitedID /**/= 0b_00000000_00000000_00000000_00100000, //0x00000020
 FW_AffectsMeasureID /**/= 0b_00000000_00000000_00000000_01000000, //0x00000040
 FW_AffectsArrangeID /**/= 0b_00000000_00000000_00000000_10000000, //0x00000080
 FW_AffectsParentMeasureID /**/= 0b_00000000_00000000_00000001_00000000, //0x00000100
 FW_AffectsParentArrangeID /**/= 0b_00000000_00000000_00000010_00000000, //0x00000200
 FW_AffectsRenderID /**/= 0b_00000000_00000000_00000100_00000000, //0x00000400
 FW_OverridesInheritanceBehaviorID /**/= 0b_00000000_00000000_00001000_00000000, //0x00000800
 FW_IsNotDataBindableID /**/= 0b_00000000_00000000_00010000_00000000, //0x00001000
 FW_BindsTwoWayByDefaultID /**/= 0b_00000000_00000000_00100000_00000000, //0x00002000
 FW_ShouldBeJournaledID /**/= 0b_00000000_00000000_01000000_00000000, //0x00004000
 FW_SubPropertiesDoNotAffectRenderID /**/= 0b_00000000_00000000_10000000_00000000, //0x00008000
 FW_SubPropertiesDoNotAffectRenderModifiedID= 0b_00000000_00000001_00000000_00000000, //0x00010000
 FW_InheritsModifiedID /**/= 0b_00000000_00010000_00000000_00000000, //0x00100000
 FW_OverridesInheritanceBehaviorModifiedID = 0b_00000000_00100000_00000000_00000000, //0x00200000
 FW_ShouldBeJournaledModifiedID /**/= 0b_00000001_00000000_00000000_00000000, //0x01000000
 FW_UpdatesSourceOnLostFocusByDefaultID /**/= 0b_00000010_00000000_00000000_00000000, //0x02000000
 FW_DefaultUpdateSourceTriggerModifiedID/**/= 0b_00000100_00000000_00000000_00000000, //0x04000000
 FW_ReadOnlyID /**/= 0b_00001000_00000000_00000000_00000000, //0x08000000
 FW_DefaultUpdateSourceTriggerEnumBit1 /**/= 0b_01000000_00000000_00000000_00000000, //0x40000000
 FW_DefaultUpdateSourceTriggerEnumBit2 /**/= 0b_10000000_00000000_00000000_00000000, //0x80000000
;

Note also how the following three properties, all declared by FrameworkPropertyMetadata, interact. To wit, IsDataBindingAllowed is not the same as !IsNotDataBindable; the former adds the additional restriction of ruling out the use of the incorrect binding direction for 'read-only' properties.

private bool ReadOnly => (_flags & FW_ReadOnlyID) != 0;

public bool IsDataBindingAllowed =>
 (_flags & FW_IsNotDataBindableID) == 0 && !this.ReadOnly;

public bool IsNotDataBindable => (_flags & FW_IsNotDataBindableID) != 0;

[Flags]
public enum FrameworkPropertyMetadataOptions
 // FPMO MetadataFlags
 // ---------- ----------
 // 0x00000010 ←┐
 None /**/ = 0x00000000, // │
 AffectsMeasure /**/ = 0x00000001, // << 6 0x00000040 │
 AffectsArrange /**/ = 0x00000002, // << 6 0x00000080 │
 AffectsParentMeasure /**/ = 0x00000004, // << 6 0x00000100 │
 AffectsParentArrange /**/ = 0x00000008, // << 6 0x00000200 │
 AffectsRender /**/ = 0x00000010, // << 6 0x00000400 │
 Inherits /**/ = 0x00000020, // >> 1 → → ────┘
 OverridesInheritanceBehavior /**/ = 0x00000040, // << 5 0x00000800
 NotDataBindable /**/ = 0x00000080, // << 5 0x00001000
 BindsTwoWayByDefault /**/ = 0x00000100, // << 5 0x00002000
 Journal /**/ = 0x00000400, // << 4 0x00004000
 SubPropertiesDoNotAffectRender /**/ = 0x00000800, // << 4 0x00008000
;