DependencyProperty.UnsetValue property

Applies to Windows and Windows Phone

Specifies a static value that is used by the property system rather than null to indicate that the property exists, but does not have its value set by the property system or by any app code.

Syntax


Public Shared ReadOnly Property UnsetValue As Object

Property value

Type: System.Object [.NET] | Platform::Object [C++]

The sentinel value for an unset value.

Remarks

UnsetValue is a sentinel value that is used for scenarios where the dependency property system is unable to determine a requested dependency property value. UnsetValue is used rather than null, because null is a valid property value for most reference-type values, and is a frequently used DefaultValue in metadata for a dependency property.

UnsetValue is never returned out of a DependencyObject.GetValue call. When you call DependencyObject.GetValue for a dependency property, one of these conditions is always true:

  • A dependency property has a default value established in metadata and that value is returned. This value might come from the property metadata's DefaultValue. This might be null.
  • Some other value was established through value precedence (for example a style was applied, or a Binding was evaluated), and the default value is no longer relevant. Even though specifically set, this still might be null. For more info on value precedence, see Dependency properties overview.

DependencyObject.ReadLocalValue returns UnsetValue when the requested property has not been locally set.

Caution  Do not register a dependency property with the default value of UnsetValue. This will be confusing for property consumers and will have unintended consequences within the property system.

UnsetValue should be returned from an IValueConverter implementation that provides conversion in a data binding to a dependency property, in any case where the converter is unable to convert a source value. Converters shouldn't throw exceptions for that case in IValueConverter.Convert, these will surface as run-time exceptions that you'd need to add handling for in UnhandledException or worse yet appear to users as actual run-time exceptions. Converter implementations should follow the general binding pattern that any failed binding does nothing and does not provide a value, and UnsetValue rather than null is the sentinel value for that case that the binding engine understands. For more info, see "Data conversions" section of the Data binding overview topic.

Examples

This example checks for an existing local value with ReadLocalValue. If there is a local value, as indicated by not returning UnsetValue, then the existing local value is removed by calling ClearValue.


Public Shared Function ClearSetProperty(targetObject As DependencyObject, targetDP As DependencyProperty) As Boolean
    If targetObject Is Nothing Or targetDP Is Nothing Then
        Throw New ArgumentNullException()
    End If
    Dim localValue As Object = targetObject.ReadLocalValue(targetDP)
    If localValue = DependencyProperty.UnsetValue Then
        ClearSetProperty = False
    Else
        targetObject.ClearValue(targetDP)
        ClearSetProperty = True
    End If
End Function


Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml
Windows::UI::Xaml [C++]

Metadata

Windows.winmd

See also

DependencyProperty
IValueConverter.Convert
Custom dependency properties
Dependency properties overview
Data binding overview

 

 

Show:
© 2014 Microsoft