RadElement
RadElement is a key class that represents the smallest unit in a RadControl that can be painted or laid out on the screen. RadElement is the base class of all elements that take advantage of TPF features, e.g. property inheritance, layouts and styling. RadElement has a size and location specified in coordinates according to its parent. Other important RadElement features are:
Behaviors: Each property can be handled by an arbitrary external object.
StyleProperty: This dependency property is a collection of predefined values for properties that are applied optionally when a certain condition is met. Styles can be grouped into a Theme.
Automatic element response on property changes: Response is controlled by RadPropertyMetadata options, e.g. AffectsDisplay, AffectsLayout.
Efficient painting: Only invalidated regions are painted. Painting does not occur exactly when a region is invalidated, other invalidated regions are combined. The frequency that elements are painted and animated is controlled by the RadElement RenderingMaxFramerate property. RadElement also handles the z-ordering if children and this is also taken into account when painting.
Layout Mechanism: RadElement participates in the TPF layout mechanism. The layout is a basic implementation of box-model sizing (see http://www.w3.org/ for more information on the box-model standard) that handles padding, margins, size and calculations of various bounds related rectangles. RadElement implements the IRadLayoutElement interface and so defines GetPreferredSize and PerFormLayout methods.
3 state visibility: RadElements can be Visible, Hidden or Collapsed where a state of hidden does not alter the layout.
Property Changes
Each property change of a RadElement or inheritance parent results in calling the OnPropertyChanged method. The override of OnPropertyChanged in RadElement:
Notifies child RadElements.
Processes behaviors (see below)
Raises bubbling and tunneling events.
Invokes layout changes if appropriate.
Handles style changes.
Handles mouse input.
Handles focus changes.
Handles z-index reordering.
Behaviors
Behaviors are a mechanism that trigger actions when specific properties are changed. For example, the ItemSelectedBehavior class shown below reacts to BackColor property changes in a RadPageViewItem.
public class ItemSelectedBehavior : PropertyChangeBehavior
{
RadPageViewItem pageViewItem;
Color backColor;
public ItemSelectedBehavior(RadPageViewItem tabStrip, Color backColor) : base(RadPageViewItem.IsSelectedProperty)
{
this.pageViewItem = tabStrip;
this.backColor = backColor;
}
public override void OnPropertyChange(Telerik.WinControls.RadElement element, RadPropertyChangedEventArgs e)
{
if ((bool)e.NewValue == true)
{
this.pageViewItem.BackColor = backColor;
}
}
}
Public Class ItemSelectedBehavior
Inherits PropertyChangeBehavior
Private pageViewItem As RadPageViewItem
Private backColor As Color
Public Sub New(tabStrip As RadPageViewItem, backColor As Color)
MyBase.New(RadPageViewItem.IsSelectedProperty)
Me.pageViewItem = tabStrip
Me.backColor = backColor
End Sub
Public Overrides Sub OnPropertyChange(element As Telerik.WinControls.RadElement, e As RadPropertyChangedEventArgs)
If CBool(e.NewValue) = True Then
Me.pageViewItem.BackColor = backColor
End If
End Sub
End Class
RadElement Lifecycle
A RadElement instance can be in one of the following states:
Constructing: The element is in a process of being constructed. Layout operations are forbidden and Property Notifications are not raised.
Constructed: The element has already been successfully constructed and its child elements are created. Layout operations are forbidden, but Property Notifications are allowed.
Loading: The element is in a process of being loaded. Layout operations are not allowed.
Loaded: The element has already been successfully loaded. An element is considered Loaded when the owning RadControl handle has been successfully created and the control may be visualized on the screen. At this stage, all layout operations as well as property notifications are allowed.
Unloaded: A special state which indicates that the element has been successfully loaded one or more times, but now it either does not reside in a valid element tree, or its owning RadControl does not have a created handle. Layout operations are not allowed.
Disposing: The element is in a process of being disposed. All layout operations and Property Notifications are forbidden.
Disposed: The element has already been successfully disposed and cannot be used any further, otherwise ObjectDisposedException is thrown.
Usability and Extensibility
You can extend the current functionality by overriding the following methods:
| Method | Description |
|---|---|
| OnLoad | Implements the load semantic. |
| OnLoaded | Notifies the element that it has been successfully loaded. |
| OnUnload | Implements the core unload semantic. |
| OnUnloaded | Notifies the element that it has been successfully unloaded. |
| OnElementTreeChanged | Provides convenient way for inheritors to add custom logic for element tree change. |
| OnParentChanged | Provides convenient way for inheritors to add custom logic upon parent change. |
| UpdateReferences | Implements the core semantic for caching references in the current element tree and layout manager as well as updating of some parent-dependent values such as tree level, inheritable element state, etc. |