PropertyMetadata PropertyMetadata PropertyMetadata PropertyMetadata Class

Definition

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.

public : class PropertyMetadata : IPropertyMetadata
public class PropertyMetadata : IPropertyMetadata
Public Class PropertyMetadata Implements IPropertyMetadata
var propertyMetadata = new propertyMetadata(defaultValue);
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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) PropertyMetadata(Object) PropertyMetadata(Object) PropertyMetadata(Object)

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

public : PropertyMetadata(Platform::Object defaultValue)
public PropertyMetadata(Object defaultValue)
Public Sub New(defaultValue As Object)
var propertyMetadata = new propertyMetadata(defaultValue);
Parameters
defaultValue
Platform::Object Object Object Object

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

PropertyMetadata(Object, PropertyChangedCallback) PropertyMetadata(Object, PropertyChangedCallback) PropertyMetadata(Object, PropertyChangedCallback) PropertyMetadata(Object, PropertyChangedCallback)

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

public : PropertyMetadata(Platform::Object defaultValue, PropertyChangedCallback propertyChangedCallback)
public PropertyMetadata(Object defaultValue, PropertyChangedCallback propertyChangedCallback)
Public Sub New(defaultValue As Object, propertyChangedCallback As PropertyChangedCallback)
var propertyMetadata = new propertyMetadata(defaultValue, propertyChangedCallback);
Parameters
defaultValue
Platform::Object Object Object Object

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

propertyChangedCallback
PropertyChangedCallback PropertyChangedCallback PropertyChangedCallback PropertyChangedCallback

A reference to the callback to call for property changed behavior.

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

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 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.

See Also

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
var createDefaultValueCallback = propertyMetadata.createDefaultValueCallback;
Value
CreateDefaultValueCallback CreateDefaultValueCallback CreateDefaultValueCallback CreateDefaultValueCallback

A reference to the callback method that provides a default 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 methods instead of using the PropertyMetadata constructor when you define the metadata for the property. That metadata is submitted to the Register 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.

See Also

DefaultValue DefaultValue DefaultValue DefaultValue

Gets the default value for the dependency property.

public : Platform::Object DefaultValue { get; }
public object DefaultValue { get; }
Public ReadOnly Property DefaultValue As object
var object = propertyMetadata.defaultValue;
Value
Platform::Object object object object

The default value for the dependency property.

Remarks

Defining the DefaultValue 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.

See Also

Methods

Create(Object) Create(Object) Create(Object) Create(Object)

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

public : static PropertyMetadata Create(Platform::Object defaultValue)
public static PropertyMetadata Create(Object defaultValue)
Public Static Function Create(defaultValue As Object) As PropertyMetadata
var propertyMetadata = Windows.UI.Xaml.PropertyMetadata.create(defaultValue);
Parameters
defaultValue
Platform::Object Object Object Object

The dependency property default value to apply.

Returns

The newly created dependency property metadata.

See Also

Create(Object, PropertyChangedCallback) Create(Object, PropertyChangedCallback) Create(Object, PropertyChangedCallback) Create(Object, PropertyChangedCallback)

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

public : static PropertyMetadata Create(Platform::Object defaultValue, PropertyChangedCallback propertyChangedCallback)
public static PropertyMetadata Create(Object defaultValue, PropertyChangedCallback propertyChangedCallback)
Public Static Function Create(defaultValue As Object, propertyChangedCallback As PropertyChangedCallback) As PropertyMetadata
var propertyMetadata = Windows.UI.Xaml.PropertyMetadata.create(defaultValue, propertyChangedCallback);
Parameters
defaultValue
Platform::Object Object Object Object

The dependency property default value to apply.

propertyChangedCallback
PropertyChangedCallback PropertyChangedCallback PropertyChangedCallback PropertyChangedCallback

A reference to the callback method that is invoked by the property system when a dependency property value changes.

Returns

The newly created dependency property metadata.

See Also

Create(CreateDefaultValueCallback) Create(CreateDefaultValueCallback) Create(CreateDefaultValueCallback) Create(CreateDefaultValueCallback)

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

public : static PropertyMetadata Create(CreateDefaultValueCallback createDefaultValueCallback)
public static PropertyMetadata Create(CreateDefaultValueCallback createDefaultValueCallback)
Public Static Function Create(createDefaultValueCallback As CreateDefaultValueCallback) As PropertyMetadata
var propertyMetadata = Windows.UI.Xaml.PropertyMetadata.create(createDefaultValueCallback);
Parameters
createDefaultValueCallback
CreateDefaultValueCallback CreateDefaultValueCallback CreateDefaultValueCallback CreateDefaultValueCallback

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

Returns

The newly created dependency property metadata.

Examples

This example shows pseudocode for using CreateDefaultValueCallback in a custom dependency property scenario. Specifically, this creates PropertyMetadata to be used in a DependencyProperty.Register 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
        }
    })

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 methods instead of using the PropertyMetadata constructor when you define the metadata for the property. That metadata is submitted to the Register 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.

See Also

Create(CreateDefaultValueCallback, PropertyChangedCallback) Create(CreateDefaultValueCallback, PropertyChangedCallback) Create(CreateDefaultValueCallback, PropertyChangedCallback) Create(CreateDefaultValueCallback, 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(CreateDefaultValueCallback createDefaultValueCallback, PropertyChangedCallback propertyChangedCallback)
public static PropertyMetadata Create(CreateDefaultValueCallback createDefaultValueCallback, PropertyChangedCallback propertyChangedCallback)
Public Static Function Create(createDefaultValueCallback As CreateDefaultValueCallback, propertyChangedCallback As PropertyChangedCallback) As PropertyMetadata
var propertyMetadata = Windows.UI.Xaml.PropertyMetadata.create(createDefaultValueCallback, propertyChangedCallback);
Parameters
createDefaultValueCallback
CreateDefaultValueCallback CreateDefaultValueCallback CreateDefaultValueCallback CreateDefaultValueCallback

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

propertyChangedCallback
PropertyChangedCallback PropertyChangedCallback PropertyChangedCallback PropertyChangedCallback

A reference to the callback method that is invoked by the property system when a dependency property value changes.

Returns

The newly created dependency property metadata.

See Also

See Also