Specifies the types of framework-level property behavior that pertain to a particular dependency property in the Windows Presentation Foundation (WPF) property system.
Member nameDescriptionNoneNo options are specified; the dependency property uses the default behavior of the Windows Presentation Foundation (WPF) property system.AffectsMeasureThe measure pass of layout compositions is affected by value changes to this dependency property. AffectsArrangeThe arrange pass of layout composition is affected by value changes to this dependency property. AffectsParentMeasureThe measure pass on the parent element is affected by value changes to this dependency property.AffectsParentArrangeThe arrange pass on the parent element is affected by value changes to this dependency property.AffectsRenderSome aspect of rendering or layout composition (other than measure or arrange) is affected by value changes to this dependency property.InheritsThe values of this dependency property are inherited by child elements.OverridesInheritanceBehaviorThe values of this dependency property span separated trees for purposes of property value inheritance. NotDataBindableData binding to this dependency property is not allowed.BindsTwoWayByDefaultThe BindingMode for data bindings on this dependency property defaults to TwoWay.JournalThe values of this dependency property should be saved or restored by journaling processes, or when navigating by Uniform resource identifiers (URIs). SubPropertiesDoNotAffectRenderThe subproperties on the value of this dependency property do not affect any aspect of rendering.
Setting Appropriate Metadata Flags
If your property (and value changes to it) affects the user interface (UI), and in particular affects how the layout system should size or render your element in a page, set one or more of the following flags: AffectsMeasure, AffectsArrange, AffectsRender.
AffectsMeasure indicates that a change to this property requires a change to UI rendering where the containing object might require more or less space within the parent. For example, a "Width" property should have this flag set.
AffectsArrange indicates that a change to this property requires a change to UI rendering that typically does not require a change in the dedicated space, but does indicate that the positioning within the space has changed. For example, an "Alignment" property should have this flag set.
AffectsRender indicates that some other change has occurred that will not affect layout and measure, but does require another render. An example would be a property that changes a color of an existing element, such as "Background".
These flags are often used as a protocol in metadata for your own override implementations of property system or layout callbacks. For instance, you might have an OnPropertyChanged callback that will call InvalidateArrange if any property of the instance reports a value change and has AffectsArrange as true in its metadata.
Some properties may affect the rendering characteristics of the containing parent element, in ways above and beyond the changes in required size mentioned above. An example is the MinOrphanLines property used in the flow document model, where changes to that property can change the overall rendering of the flow document that contains the paragraph. Use AffectsParentArrange or AffectsParentMeasure to identify similar cases in your own properties.
By default, dependency properties support data binding. You can deliberately disable data binding, for cases where there is no realistic scenario for data binding, or where performance in data binding for a large object is recognized as a problem.
By default, data binding Mode for dependency properties defaults to OneWay. You can always change the binding to be TwoWay per binding instance; for details, see How to: Specify the Direction of the Binding. But as the dependency property author, you can choose to make the property use TwoWay binding mode by default. Examples in existing dependency properties include ; the scenario for this property is that the IsSubmenuOpen setting logic and the compositing of MenuItem interact with the default theme style. The IsSubmenuOpen property logic uses data binding natively to maintain the state of the property in accordance to other state properties and method calls. Another example property that binds TwoWay by default is TextBox.Text.
You can also enable property inheritance in a custom dependency property by setting the Inherits flag. Property inheritance is useful for a scenario where parent elements and child elements have a property in common, and it makes sense for the child elements to have that particular property value set to the same value as the parent set it. An example inheritable property is DataContext, which is used for binding operations to enable the important master-detail scenario for data presentation. By making DataContext inheritable, any child elements inherit that data context also. Because of property value inheritance, you can specify a data context at the page or application root, and do not need to respecify it for bindings in all possible child elements. DataContext is also a good example to illustrate that inheritance overrides the default value, but it can always be set locally on any particular child element; for details, see How to: Use the Master-Detail Pattern with Hierarchical Data. Property value inheritance does have a possible performance cost, and thus should be used sparingly; for details, see Property Value Inheritance.
Set the Journal flag to indicate if your dependency property should be detected or used by navigation journaling services. An example is the SelectedIndex property; any item selected in a selection control should be persisted when the journaling history is navigated.