PropertyMetadata Class

  • Reference

Definition

Namespace:
Windows.UI.Xaml
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(Windows.Foundation.UniversalApiContract, 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(Windows.Foundation.UniversalApiContract), 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

Windows requirements

Device family
Windows 10 (introduced in 10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced in v1.0)

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

Public Class AquariumServices
    Inherits DependencyObject
    Public Enum Buoyancy
        Floats
        Sinks
        Drifts
    End Enum

    Public Shared ReadOnly BuoyancyProperty As DependencyProperty = _
          DependencyProperty.RegisterAttached(
          "Buoyancy", _
          GetType(Buoyancy), _
          GetType(AquariumServices), _
          New PropertyMetadata(Buoyancy.Floats))


    Public Sub SetBuoyancy(element As DependencyObject, value As Buoyancy)
        element.SetValue(BuoyancyProperty, value)
    End Sub
    Public Function GetBuoyancy(element As DependencyObject) As Buoyancy
        GetBuoyancy = CType(element.GetValue(BuoyancyProperty), Buoyancy)
    End Function
End Class

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)

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

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

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)

Creates a PropertyMetadata value, specifying a callback that establishes a default value for a dependency property.
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(Object)

Creates a PropertyMetadata value, specifying a fixed 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.

Applies to

See also