PropertyMetadata Class

Reference

Definition

Namespace:: Microsoft.UI.Xaml

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

Defines behavior aspects of a dependency property, including conditions it was registered with. For more info on how PropertyMetadata is used for dependency properties, see Custom dependency properties.

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class PropertyMetadata

[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class PropertyMetadata

Public Class PropertyMetadata

Inheritance: Object IInspectable PropertyMetadata

Attributes: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Examples

This example calls the PropertyMetadata(Object) constructor, which creates a PropertyMetadata that reports a default value for a DependencyProperty. The PropertyMetadata is then used for an attached property registration when RegisterAttached is called.

public abstract class AquariumServices : DependencyObject
{
    public enum Buoyancy { Floats, Sinks, Drifts }

    public static readonly DependencyProperty BuoyancyProperty = DependencyProperty.RegisterAttached(
      "Buoyancy",
      typeof(Buoyancy),
      typeof(AquariumServices),
      new PropertyMetadata(Buoyancy.Floats)
    );
    public static void SetBuoyancy(DependencyObject element, Buoyancy value)
    {
        element.SetValue(BuoyancyProperty, value);
    }
    public static Buoyancy GetBuoyancy(DependencyObject element)
    {
        return (Buoyancy)element.GetValue(BuoyancyProperty);
    }
}

Remarks

Defining a PropertyMetadata instance is part of the scenario for defining a custom dependency property. For info and examples, see Custom dependency properties.

A PropertyMetadata value represents two aspects of dependency property behavior:

Provides a default value, which is used as the value of the property unless the owner type specifically initializes the value, or the value is set by user code or other mechanisms.
References a callback that is invoked if the dependency property system detects that the dependency property has changed. Typically, a dependency property only needs a PropertyMetadata value if one or both of these behaviors is desired. Otherwise, a value of null can be passed for the propertyMetadata parameter when a dependency property is registered with the dependency property system. For more info, see DependencyProperty.Register.

If your PropertyMetadata includes a property-changed callback reference, that method must be a static method of the class that exposes the DependencyProperty identifier where that PropertyMetadata is applied. How to write this method is described in Custom dependency properties and also the reference topic for the PropertyChangedCallback delegate.

Note

Once created, a PropertyMetadata instance doesn't have a property that can be used to find the callback or even to determine the callback's method name. That information is considered an implementation detail of a dependency property and only the dependency property system itself needs to be able to invoke that method.

Instantiating a PropertyMetadata value

There are two methods that can instantiate a PropertyMetadata instance: a constructor, and a static PropertyMetadata.Create method. Each of these methods has multiple signatures. It's more common to use the constructors. However, you must use PropertyMetadata.Create if you want the default value mechanism for your dependency property to be thread-safe. For more info, see the "Property metadata for a custom dependency property" section of the Custom dependency properties topic.

Constructors

PropertyMetadata(Object, PropertyChangedCallback)	Initializes a new instance of the PropertyMetadata class, using a property default value and callback reference.
PropertyMetadata(Object)	Initializes a new instance of the PropertyMetadata class, using a property default value.

Properties

CreateDefaultValueCallback	Gets a reference to the callback method that provides a default property value.
DefaultValue	Gets the default value for the dependency property.

Methods

Create(CreateDefaultValueCallback, PropertyChangedCallback)	Creates a PropertyMetadata value, specifying a callback that establishes a default value for a dependency property, and a property-changed callback.
Create(CreateDefaultValueCallback)	Creates a PropertyMetadata value, specifying a callback that establishes a default value for a dependency property.
Create(Object, PropertyChangedCallback)	Creates a PropertyMetadata value, specifying a fixed default value for a dependency property, and a property-changed callback.
Create(Object)	Creates a PropertyMetadata value, specifying a fixed default value for a dependency property.

Applies to

Share via