RadObject

RadObject represents a base class for all elements that need to interact with the dependency property system of Telerik Presentation Framework. For instance, RadElement class derives from RadObject so it participates in that system.

The main RadObject functionality is:

Method	Description
GetValue	Retrieves the stored value for a given dependency property.
SetValue	Sets a value for a given dependency property.
ResetValue	Resets the value of a given dependency property. There are several reset options specified in ValueResetFlags enumeration.
UpdateValue	Forces a re-evaluation for a given property.
GetValueSource	Indicates the source of change.
BindProperty	Creates a binding between two properties.
UnbindProperty	Destroys an existing binding between two properties.

Dependency properties are registered using RadProperty class. Refer to this article if you need to create a dependency property but you need not create a custom object that will participate in the hierarchy of visual elements, i.e. custom fill primitive that does not derive from the existing one.

Getting and Setting Values

GetValue and SetValue methods are used for getting and setting local values. Usually you have to define a CLR property for each declared RadProperty whose setter calls GetValue and whose getter calls SetValue:

internal class MyRadObject : RadObject
{
    public static readonly RadProperty HeightProperty =
    RadProperty.Register("Height",
    typeof(int),
    typeof(MyRadObject),
    new RadElementPropertyMetadata(1, ElementPropertyOptions.AffectsArrange | ElementPropertyOptions.AffectsMeasure));
    public int Height
    {
        get
        {
            return (int)this.GetValue(HeightProperty);
        }
        set
        {
            this.SetValue(HeightProperty, value);
        }
    }
}

Friend Class MyRadObject
    Inherits RadObject
    Public Shared ReadOnly HeightProperty As RadProperty = RadProperty.Register("Height", GetType(Integer), GetType(MyRadObject), New RadElementPropertyMetadata(1, ElementPropertyOptions.AffectsArrange Or ElementPropertyOptions.AffectsMeasure))
    Public Property Height() As Integer
        Get
            Return CInt(Me.GetValue(HeightProperty))
        End Get
        Set(value As Integer)
            Me.SetValue(HeightProperty, value)
        End Set
    End Property
End Class

Resetting Values

If the value is inherited, the inherited value becomes the new value. Otherwise, the value is reset to the default value.

The code snippet below reset the value of the HeightProperty declared in MyRadObject class:

radObject.ResetValue(MyRadObject.HeightProperty);

radObject.ResetValue(MyRadObject.HeightProperty)

You can pass a second parameter to the ResetValue method to specify a reset flag:

[Flags]
public enum ValueResetFlags
{
    None = 0,
    Inherited = 1,
    Binding = Inherited << 1,
    TwoWayBindingLocal = Binding << 1,
    Style = TwoWayBindingLocal << 1,
    Animation = Style << 1,
    Local = Animation << 1,
    DefaultValueOverride = Local << 1,
    All = Inherited | Binding | TwoWayBindingLocal | Style | Animation | Local | DefaultValueOverride
}

<Flags> _
Public Enum ValueResetFlags
    None = 0
    Inherited = 1
    Binding = Inherited << 1
    TwoWayBindingLocal = Binding << 1
    Style = TwoWayBindingLocal << 1
    Animation = Style << 1
    Local = Animation << 1
    DefaultValueOverride = Local << 1
    All = Inherited Or Binding Or TwoWayBindingLocal Or Style Or Animation Or Local Or DefaultValueOverride
End Enum

Updating Values

Re-evaluates the property specified as a parameter. In the example below, the HeightProperty is re-evaluated:

radObject.UpdateValue(MyRadObject.HeightProperty);

radObject.UpdateValue(MyRadObject.HeightProperty)

Getting Value Source

The value source is the reason for the current value. GetValueSource method returns the ValueSource enumeration which describes the value sources:

public enum ValueSource : short
{
    /// <summary>
    /// Indicates that the reason is unknown.
    /// </summary>
    Unknown = 0,
    /// <summary>
    /// Indicates that the default value is set.
    /// </summary>
    DefaultValue,
    /// <summary>
    /// Indicates that the property changed is inherited.
    /// </summary>
    Inherited,
    /// <summary>
    /// An overriden default value, has higher priority than Default and Inherited source.
    /// </summary>
    DefaultValueOverride,
    /// <summary>
    /// Indicates that the reason for the property change is an applied theme.
    /// </summary>
    Style,
    /// <summary>
    /// Value is set locally through a CLR property setter.
    /// </summary>
    Local,
    /// <summary>
    /// Indicates that the reason for the property change is data binding.
    /// </summary>
    PropertyBinding,
    /// <summary>
    /// A value is applied through two-way binding.
    /// </summary>
    LocalFromBinding,
    /// <summary>
    /// Indicates that the reason for the property change is an animation effect.
    /// </summary>
    Animation,
}

Public Enum ValueSource As Short
    ''' <summary>
    ''' Indicates that the reason is unknown.
    ''' </summary>
    Unknown = 0
    ''' <summary>
    ''' Indicates that the default value is set.
    ''' </summary>
    DefaultValue
    ''' <summary>
    ''' Indicates that the property changed is inherited.
    ''' </summary>
    Inherited
    ''' <summary>
    ''' An overriden default value, has higher priority than Default and Inherited source.
    ''' </summary>
    DefaultValueOverride
    ''' <summary>
    ''' Indicates that the reason for the property change is an applied theme.
    ''' </summary>
    Style
    ''' <summary>
    ''' Value is set locally through a CLR property setter.
    ''' </summary>
    Local
    ''' <summary>
    ''' Indicates that the reason for the property change is data binding.
    ''' </summary>
    PropertyBinding
    ''' <summary>
    ''' A value is applied through two-way binding.
    ''' </summary>
    LocalFromBinding
    ''' <summary>
    ''' Indicates that the reason for the property change is an animation effect.
    ''' </summary>
    Animation
End Enum

Binding and Unbinding Properties

Properties can be bound to other properties either one-way or two-way. The code snippet below binds two properties one-way:

MyRadObject radObject1 = new MyRadObject();
MyRadObject radObject2 = new MyRadObject();
radObject2.BindProperty(MyRadObject.HeightProperty, radObject1,
MyRadObject.HeightProperty, PropertyBindingOptions.OneWay);

Dim radObject1 As New MyRadObject()
Dim radObject2 As New MyRadObject()
radObject2.BindProperty(MyRadObject.HeightProperty, radObject1, MyRadObject.HeightProperty, PropertyBindingOptions.OneWay)

If the binding is one way the source property is the one passed as a parameter to BindProperty method.

Values Precedence

Dependency properties are more advanced than the ordinary properties; they support advance features such as inheritance, and animation. For this reason, precedence rules have to be established. The table below summarizes the precedence rules from highest precedence to lowest:

Value	Description
Coercion	This is the final step when you can change the value of a given property. Please refer to the subsection below about implementing value coercion.
Animation	When the animation is finished, you can either store the last value or remove it and therefore allow previous modifiers to participate in value composition. This behavior is controlled by AnimatedPropertySetting.RemoveAfterApply property. Note: Animation in TPF is controlled by AnimatedPropertySetting object which value has different meanings depending on whether it is specified through StyleSheet or not. If the latter is true, the animation is treated as Style Setting rather than animation.
Binding	Properties can be bound either one-way or two way. Refer to the subsection about binding below.
Local Value	The value that is set through a CLR Property Setter or the publicly exposed SetValue method.
Style Setting	A PropertySetting which comes from a StyleSheet.Note: it can be AnimatedPropertySetting which will be treated as a Style rather than Animation.
Inherited Value	Value that comes from the current InheritanceParent for the object. An inherited value is cached once retrieved and stored until caching is marked as Invalid. Note: Only properties, whose metadata object has the IsInherited flag set, are target of inheritance.
Default Value	A default value can be set either using the dependency property metadata or by overriding the method GetDefaultValue . Refer to the subsection below about default values.

Coercion

You need to override CoerceValue method:

protected override object CoerceValue(RadPropertyValue propVal, object baseValue)
{
    if (useCoercion && propVal.Property == MyRadObject.HeightProperty)
    {
        return 105; //coerce value which for the example sake is integer
    }
    return base.CoerceValue(propVal, baseValue);
}

Protected Overrides Function CoerceValue(propVal As RadPropertyValue, baseValue As Object) As Object
    If useCoercion AndAlso propVal.Property.Equals(MyRadObject.HeightProperty) Then
        'coerce value which for the example sake is integer
        Return 105
    End If
    Return MyBase.CoerceValue(propVal, baseValue)
End Function

In the example above, the value of the Height property is coerced to 105 (Height is an integer property).

Coercion is seldom used.

Binding

A property of one RadObject instance can be bound to a property of another RadObject instance. There are two binding models:

One way	Change in the source triggers change in the bound target property. The only exception to this case is that animation in progress can change the value of the bound property.
Two ways	Value change in one of the properties triggers change in the other.

Local Value

Local values are set and get using SetValue and GetValue methods:

internal class MyRadObject : RadObject
{
    public static readonly RadProperty HeightProperty =
    RadProperty.Register("Height",
    typeof(int),
    typeof(MyRadObject),
    new RadElementPropertyMetadata(1, ElementPropertyOptions.AffectsArrange | ElementPropertyOptions.AffectsMeasure));
    public int Height
    {
        get
        {
            return (int)this.GetValue(HeightProperty);
        }
        set
        {
            this.SetValue(HeightProperty, value);
        }
    }
}

Friend Class MyRadObject
    Inherits RadObject
    Public Shared ReadOnly HeightProperty As RadProperty = RadProperty.Register("Height", GetType(Integer), GetType(MyRadObject), New RadElementPropertyMetadata(1, ElementPropertyOptions.AffectsArrange Or ElementPropertyOptions.AffectsMeasure))
    Public Property Height() As Integer
        Get
            Return CInt(Me.GetValue(HeightProperty))
        End Get
        Set(value As Integer)
            Me.SetValue(HeightProperty, value)
        End Set
    End Property
End Class

Default Value 

When you define a dependency property, you create a RadElementPropertyMetadata whose first constructor argument is default value:

public static readonly RadProperty HeightProperty =
    RadProperty.Register("Height",
    typeof(int),
    typeof(MyRadObject),
    new RadElementPropertyMetadata(1, ElementPropertyOptions.AffectsArrange | ElementPropertyOptions.AffectsMeasure));

Public Shared ReadOnly HeightProperty As RadProperty = RadProperty.Register("Height", GetType(Integer), GetType(MyRadObject), New RadElementPropertyMetadata(1, ElementPropertyOptions.AffectsArrange Or ElementPropertyOptions.AffectsMeasure))

In some rare cases, you might want to override the GetDefaultValue and specify the default value there:

protected override object GetDefaultValue(RadPropertyValue propVal, object baseDefaultValue)
{
    if (propVal.Property == MyRadObject.HeightProperty)
    {
        return 2;
    }
    return base.GetDefaultValue(propVal, baseDefaultValue);
}

Protected Overrides Function GetDefaultValue(propVal As RadPropertyValue, baseDefaultValue As Object) As Object
    If propVal.Property.Equals(MyRadObject.HeightProperty) Then
        Return 2
    End If
    Return MyBase.GetDefaultValue(propVal, baseDefaultValue)
End Function

See Also

• BasePrimitive

• Choosing an Ancestor Class

• Class Hierarchy Overview

• LayoutPanel

• RadComponent, RadComponentElement

• RadControl

• RadElement

• RadItem