PropertyMetadata PropertyMetadata PropertyMetadata Class

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.

Syntax

Declaration

public class PropertyMetadatapublic class PropertyMetadataPublic Class PropertyMetadata

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 Register(System.String,Windows.UI.Xaml.Interop.TypeName,Windows.UI.Xaml.Interop.TypeName,Windows.UI.Xaml.PropertyMetadata).

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 Create(System.Object) method. Each of these methods has multiple signatures. It's more common to use the constructors. However, you must use Create(System.Object) 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.

Examples

This example calls the @Windows.UI.Xaml.PropertyMetadata.#ctor(System.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(System.String,Windows.UI.Xaml.Interop.TypeName,Windows.UI.Xaml.Interop.TypeName,Windows.UI.Xaml.PropertyMetadata) is called.

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

    public static readonly DependencyProperty BouyancyProperty = DependencyProperty.RegisterAttached(
      "Bouyancy",
      typeof(Bouyancy),
      typeof(AquariumServices),
      new PropertyMetadata(Bouyancy.Floats)
    );
    public static void SetBouyancy(DependencyObject element, Bouyancy value)
    {
        element.SetValue(BouyancyProperty, value);
    }
    public static Bouyancy GetBouyancy(DependencyObject element)
    {
        return (Bouyancy)element.GetValue(BouyancyProperty);
    }
}
Public Class AquariumServices
    Inherits DependencyObject
    Public Enum Bouyancy
        Floats
        Sinks
        Drifts
    End Enum

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


    Public Sub SetBouyancy(element As DependencyObject, value As Bouyancy)
        element.SetValue(BouyancyProperty, value)
    End Sub
    Public Function GetBouyancy(element As DependencyObject) As Bouyancy
        GetBouyancy = CType(element.GetValue(BouyancyProperty), Bouyancy)
    End Function
End Class

Constructors summary

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

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

Properties summary

Gets a reference to the callback method that provides a default property value.

Gets the default value for the dependency property.

Methods summary

Creates a PropertyMetadata value, specifying a fixed default value for a dependency property.

Creates a PropertyMetadata value, specifying a fixed default value for a dependency property, and a property-changed callback.

Creates a PropertyMetadata value, specifying a callback that establishes a default value for a dependency property.

Creates a PropertyMetadata value, specifying a callback that establishes a default value for a dependency property, and a property-changed callback.

Constructors

  • PropertyMetadata(System.Object)
    PropertyMetadata(System.Object)
    PropertyMetadata(System.Object)
    PropertyMetadata(System.Object)

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

    public PropertyMetadata(System.Object)public PropertyMetadata(System.Object)Public Function PropertyMetadata(System.Object) As

    Parameters

    • defaultValue
      System.Object
      System.Object
      System.Object

      A default value for the property where this PropertyMetadata is applied.

  • PropertyMetadata(System.Object,Windows.UI.Xaml.PropertyChangedCallback)
    PropertyMetadata(System.Object,Windows.UI.Xaml.PropertyChangedCallback)
    PropertyMetadata(System.Object,Windows.UI.Xaml.PropertyChangedCallback)
    PropertyMetadata(System.Object,Windows.UI.Xaml.PropertyChangedCallback)

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

    public PropertyMetadata(System.Object,Windows.UI.Xaml.PropertyChangedCallback)public PropertyMetadata(System.Object,Windows.UI.Xaml.PropertyChangedCallback)Public Function PropertyMetadata(System.Object,Windows.UI.Xaml.PropertyChangedCallback) As

    Parameters

    Remarks

    If you want to establish a PropertyMetadata instance that has a property-changed callback method but not a default value, pass null for defaultValue.

    If you pass a value for defaultValue, make sure that the type of that value is valid for the propertyType type from the dependency property's definition through the Register(System.String,Windows.UI.Xaml.Interop.TypeName,Windows.UI.Xaml.Interop.TypeName,Windows.UI.Xaml.PropertyMetadata) call. If you've created a type mismatch between registration parameter and metadata, the issue only manifests itself indirectly. You'll get runtime errors when you try to instantiate a type that has this dependency property value, you won't get any design-time or compile-time warning or error.

    Examples

    This example shows usage of this constructor. OnLabelChanged refers to a delegate implementation for a PropertyChangedCallback (not shown). To see more code that puts this example in context, see Custom dependency properties.

    public static readonly DependencyProperty LabelProperty = DependencyProperty.Register(
      "Label",
      typeof(String),
      typeof(ImageWithLabelControl),
      new PropertyMetadata(null,new PropertyChangedCallback(OnLabelChanged))
    );
    
    Public Shared ReadOnly LabelProperty As DependencyProperty = _
        DependencyProperty.Register("Label", _
          GetType(String), GetType(ImageWithLabelControl), _
          New PropertyMetadata(Nothing, new PropertyChangedCallback(AddressOf OnLabelChanged)))
    
    DependencyProperty^ ImageWithLabelControl::_LabelProperty = 
        DependencyProperty::Register("Label", 
        Platform::String::typeid,
        ImageWithLabelControl::typeid, 
        ref new PropertyMetadata(nullptr,
          ref new PropertyChangedCallback(&ImageWithLabelControl::OnLabelChanged))
        );
    

Properties

  • CreateDefaultValueCallback
    CreateDefaultValueCallback
    CreateDefaultValueCallback
    CreateDefaultValueCallback

    Gets a reference to the callback method that provides a default property value.

    public CreateDefaultValueCallback CreateDefaultValueCallback { get; }public CreateDefaultValueCallback CreateDefaultValueCallback { get; }Public ReadOnly Property CreateDefaultValueCallback As CreateDefaultValueCallback

    Property Value

    Remarks

    Use a CreateDefaultValueCallback instead of a fixed constant default value in any case where the default value of a dependency property might be thread-bound. The CreateDefaultValueCallback becomes a factory for default values whenever there is a need to get default values of properties on threads other than the main UI thread.

    In order to establish a CreateDefaultValueCallback pattern for a dependency property, use one of the static Create(System.Object) methods instead of using the @Windows.UI.Xaml.PropertyMetadata.#ctor(System.Object,Windows.UI.Xaml.PropertyChangedCallback) constructor when you define the metadata for the property. That metadata is submitted to the Register(System.String,Windows.UI.Xaml.Interop.TypeName,Windows.UI.Xaml.Interop.TypeName,Windows.UI.Xaml.PropertyMetadata) call. For more info, see Custom dependency properties. As with a property-changed callback, the CreateDefaultValueCallback method should be a static method of the type that registers the dependency property. The method does not have to be public.

  • DefaultValue
    DefaultValue
    DefaultValue
    DefaultValue

    Gets the default value for the dependency property.

    public object DefaultValue { get; }public object DefaultValue { get; }Public ReadOnly Property DefaultValue As object

    Property Value

    • object
      object
      object

      The default value for the dependency property.

    Remarks

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

    The default value for a dependency property is often not the apparent value at run time, even if the property is not explicitly set. For more info, see Dependency properties overview.

Methods

  • Create(System.Object)
    Create(System.Object)
    Create(System.Object)
    Create(System.Object)

    Creates a PropertyMetadata value, specifying a fixed default value for a dependency property.

    public static PropertyMetadata Create(System.Object)public static PropertyMetadata Create(System.Object)Public Static Function Create(System.Object) As PropertyMetadata

    Parameters

    • defaultValue
      System.Object
      System.Object
      System.Object

      The dependency property default value to apply.

    Returns

  • Create(System.Object,Windows.UI.Xaml.PropertyChangedCallback)
    Create(System.Object,Windows.UI.Xaml.PropertyChangedCallback)
    Create(System.Object,Windows.UI.Xaml.PropertyChangedCallback)
    Create(System.Object,Windows.UI.Xaml.PropertyChangedCallback)

    Creates a PropertyMetadata value, specifying a fixed default value for a dependency property, and a property-changed callback.

    public static PropertyMetadata Create(System.Object,Windows.UI.Xaml.PropertyChangedCallback)public static PropertyMetadata Create(System.Object,Windows.UI.Xaml.PropertyChangedCallback)Public Static Function Create(System.Object,Windows.UI.Xaml.PropertyChangedCallback) As PropertyMetadata

    Parameters

    Returns

  • Create(Windows.UI.Xaml.CreateDefaultValueCallback)
    Create(Windows.UI.Xaml.CreateDefaultValueCallback)
    Create(Windows.UI.Xaml.CreateDefaultValueCallback)
    Create(Windows.UI.Xaml.CreateDefaultValueCallback)

    Creates a PropertyMetadata value, specifying a callback that establishes a default value for a dependency property.

    public static PropertyMetadata Create(Windows.UI.Xaml.CreateDefaultValueCallback)public static PropertyMetadata Create(Windows.UI.Xaml.CreateDefaultValueCallback)Public Static Function Create(Windows.UI.Xaml.CreateDefaultValueCallback) As PropertyMetadata

    Parameters

    Returns

    Remarks

    Use a CreateDefaultValueCallback instead of a fixed constant default value in any case where the default value of a dependency property might be thread-bound. The CreateDefaultValueCallback becomes a factory for default values whenever there is a need to get default values of properties on threads other than the main UI thread.

    In order to establish a CreateDefaultValueCallback pattern for a dependency property, use one of the static Create(System.Object) methods instead of using the @Windows.UI.Xaml.PropertyMetadata.#ctor(System.Object,Windows.UI.Xaml.PropertyChangedCallback) constructor when you define the metadata for the property. That metadata is submitted to the Register(System.String,Windows.UI.Xaml.Interop.TypeName,Windows.UI.Xaml.Interop.TypeName,Windows.UI.Xaml.PropertyMetadata) call. For more info, see Custom dependency properties. As with a property-changed callback, the CreateDefaultValueCallback method should be a static method of the type that registers the dependency property. The method does not have to be public.

    Examples

    This example shows pseudocode for using CreateDefaultValueCallback in a custom dependency property scenario. Specifically, this creates PropertyMetadata to be used in a Register(System.String,Windows.UI.Xaml.Interop.TypeName,Windows.UI.Xaml.Interop.TypeName,Windows.UI.Xaml.PropertyMetadata) call (not shown).

    PropertyMetadata metadata = PropertyMetadata.Create(
        new CreateDefaultValueCallback(() =>
        {
            return new CustomClass() //a DependencyObject
            {
                CustomProperty1 = "default", //DependencyProperty of type String 
                CustomProperty2 = -1; //DependencyProperty of type Int32
            }
        })
    
  • Create(Windows.UI.Xaml.CreateDefaultValueCallback,Windows.UI.Xaml.PropertyChangedCallback)
    Create(Windows.UI.Xaml.CreateDefaultValueCallback,Windows.UI.Xaml.PropertyChangedCallback)
    Create(Windows.UI.Xaml.CreateDefaultValueCallback,Windows.UI.Xaml.PropertyChangedCallback)
    Create(Windows.UI.Xaml.CreateDefaultValueCallback,Windows.UI.Xaml.PropertyChangedCallback)

    Creates a PropertyMetadata value, specifying a callback that establishes a default value for a dependency property, and a property-changed callback.

    public static PropertyMetadata Create(Windows.UI.Xaml.CreateDefaultValueCallback,Windows.UI.Xaml.PropertyChangedCallback)public static PropertyMetadata Create(Windows.UI.Xaml.CreateDefaultValueCallback,Windows.UI.Xaml.PropertyChangedCallback)Public Static Function Create(Windows.UI.Xaml.CreateDefaultValueCallback,Windows.UI.Xaml.PropertyChangedCallback) As PropertyMetadata

    Parameters

    Returns

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute
Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.StaticAttribute

Details

Assembly

Windows.UI.Xaml.dll