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 : IPropertyMetadatapublic class PropertyMetadata : IPropertyMetadataPublic Class PropertyMetadata Implements IPropertyMetadata// This API is not available in Javascript.
- Attributes
| 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 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
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)// This API is not available in Javascript.
- 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)// This API is not available in Javascript.
- 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// This API is not available in Javascript.
- 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// This API is not available in Javascript.
- 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// This API is not available in Javascript.
- defaultValue
- PlatForm::Object Object Object Object
The dependency property default value to apply.
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// This API is not available in Javascript.
- 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.
The newly created dependency property metadata.
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// This API is not available in Javascript.
- createDefaultValueCallback
- CreateDefaultValueCallback CreateDefaultValueCallback CreateDefaultValueCallback CreateDefaultValueCallback
A reference to the callback method that provides a default property value.
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.
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// This API is not available in Javascript.
- 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.
The newly created dependency property metadata.
- See Also