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:

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.

Caution
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:

CopyC#

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

CopyVB.NET

    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 DirectCast(Me.GetValue(HeightProperty), Integer)
  End Get
  Set
   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:

CopyC#

radObject.ResetValue(MyRadObject.HeightProperty);

CopyVB.NET

radObject.ResetValue(MyRadObject.HeightProperty)

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

CopyC#

    [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
}

Updating Values

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

CopyC#

radObject.UpdateValue(RadObjectTest.HeightProperty);

CopyVB.NET

radObject.UpdateValue(RadObjectTest.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:

CopyC#

    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>
        /// Indicates that the reason for the property change is data binding.
        /// </summary>
        PropertyBinding,
        /// <summary>
        /// Indicates that the reason for the property change is an applied theme.
        /// </summary>
        Style,
        
        Local,
        /// <summary>
        /// A value is applied through two-way binding.
        /// </summary>
        LocalFromBinding,
        /// <summary>
        /// An overriden default value, has higher priority from Default and Inherited values.
        /// </summary>
        DefaultValueOverride,
        /// <summary>
        /// Indicates that the reason for the property change is an animation effect.
        /// </summary>
        Animation,
    }

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:

CopyC#

RadObjectTest radObject = new RadObjectTest();
RadObjectTest radObject2 = new RadObjectTest();
radObject2.BindProperty(RadObjectTest.HeightProperty, radObject,
RadObjectTest.HeightProperty, PropertyBindingOptions.OneWay);

CopyVB.NET

Dim radObject As New RadObjectTest()
Dim radObject2 As New RadObjectTest()
radObject2.BindProperty(RadObjectTest.HeightProperty, radObject, RadObjectTest.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:

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:

CopyC#

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

CopyVB.NET

Protected Overloads Overrides Function CoerceValue(propVal As RadPropertyValue, baseValue As Object) As Object

         If useCoercion AndAlso propVal.[Property] = RadObjectTest.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).

Note: Coercion is seldom used.

Animation

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:

CopyC#

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

CopyVB.NET

    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 DirectCast(Me.GetValue(HeightProperty), Integer)
  End Get
  Set
   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:

CopyC#

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

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

CopyC#

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

CopyVB.NET

    Protected Overloads Overrides Function GetDefaultValue(propVal As RadPropertyValue, baseDefaultValue As Object) As Object
 If propVal.[Property] = RadObjectTest.HeightProperty Then
  Return 2
 End If
 Return MyBase.GetDefaultValue(propVal, baseDefaultValue)
End Function

RadControls for WinForms

Getting and Setting Values

Resetting Values

Updating Values

Getting Value Source

Binding and Unbinding Properties

Values Precedence

Coercion

Animation

Binding

Local Value

Default Value