Class RadElementTree

Represents the visual element tree for a Telerik control. Every Telerik control has a corresponding tree of RadElements. This provides flexibility in building controls and enables property inheritance from ancestor nodes.

Inheritance
System.Object
RadElementTree
ComponentThemableElementTree
Inherited Members
System.Object.ToString()
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: Telerik.WinControls
Assembly: Telerik.WinControls.dll

Syntax

public class RadElementTree : IDisposable
Remarks

The RadElementTree manages the hierarchy of visual elements that make up a Telerik control. It handles layout operations, element hit testing, and provides infrastructure for element management and disposal. The tree structure allows for complex visual compositions while maintaining efficient layout and rendering performance.

Constructors

RadElementTree(IComponentTreeHandler)

Initializes a new instance of the RadElementTree class.

Declaration
public RadElementTree(IComponentTreeHandler component)
Parameters
IComponentTreeHandler component

The component tree handler that manages this element tree.

Properties

ComponentTreeHandler

Gets the component tree handler that bridges the abstract RadElement layout and the RadControl instance.

Declaration
public IComponentTreeHandler ComponentTreeHandler { get; }
Property Value
IComponentTreeHandler

The IComponentTreeHandler that manages this element tree.

Control

Gets the Windows Forms control that hosts this element tree.

Declaration
public Control Control { get; }
Property Value
System.Windows.Forms.Control

The Control instance that contains this element tree.

Disposing

Gets a value indicating whether the element tree is currently being disposed.

Declaration
public bool Disposing { get; }
Property Value
System.Boolean

true if the tree is disposing; otherwise, false.

IsLayoutSuspended

Gets a value indicating whether layout operations are currently suspended.

Declaration
public bool IsLayoutSuspended { get; }
Property Value
System.Boolean

true if layout is suspended; otherwise, false.
Remarks

Layout suspension is used to improve performance during bulk operations by preventing unnecessary layout calculations until the operations are complete.

RootElement

Gets the root element of the element tree.

Declaration
public RootRadElement RootElement { get; }
Property Value
RootRadElement

The RootRadElement that serves as the root of the element hierarchy.
Remarks

The root element is the top-level container for all visual elements in the control. It manages the overall layout and serves as the entry point for element tree operations.

TreeName

Gets the unique name of this element tree.

Declaration
public string TreeName { get; }
Property Value
System.String

A string representing the tree name, typically in the format "VisualTree" followed by an instance number.

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration
public void Dispose()
Implements
System.IDisposable.Dispose()

Dispose(Boolean)

Releases the unmanaged resources used by the RadElementTree and optionally releases the managed resources.

Declaration
protected virtual void Dispose(bool disposing)
Parameters
System.Boolean disposing

true to release both managed and unmanaged resources; false to release only unmanaged resources.

GetElementAtPoint(Point)

Gets the element at the specified coordinates that handles mouse input.

Declaration
public RadElement GetElementAtPoint(Point point)
Parameters
System.Drawing.Point point

The coordinates to test, in control coordinates.
Returns
RadElement

The RadElement at the specified point that can handle mouse input, or null if no suitable element is found.

GetElementAtPoint(Point, Predicate<RadElement>)

Gets the element at the specified coordinates that meets the predicate criteria.

Declaration
public RadElement GetElementAtPoint(Point point, Predicate<RadElement> predicate)
Parameters
System.Drawing.Point point

The coordinates to test, in control coordinates.
System.Predicate<RadElement> predicate

A predicate function to test each element, or null to return the first element found.
Returns
RadElement

The RadElement that meets the criteria, or null if no suitable element is found.

GetElementAtPoint(RadElement, Point, List<RadElement>)

Declaration
public RadElement GetElementAtPoint(RadElement parent, Point point, List<RadElement> foundElements)
Parameters
RadElement parent

System.Drawing.Point point

System.Collections.Generic.List<RadElement> foundElements

Returns
RadElement

GetElementAtPoint(RadElement, Point, List<RadElement>, Predicate<RadElement>)

Declaration
public RadElement GetElementAtPoint(RadElement parent, Point point, List<RadElement> foundElements, Predicate<RadElement> predicate)
Parameters
RadElement parent

System.Drawing.Point point

System.Collections.Generic.List<RadElement> foundElements

System.Predicate<RadElement> predicate

Returns
RadElement

GetElementAtPoint<T>(Point)

Gets the first element of the specified type at the given coordinates that handles mouse input.

Declaration
public T GetElementAtPoint<T>(Point point)
    where T : class
Parameters
System.Drawing.Point point

The coordinates to test, in control coordinates.
Returns
T

The element of type T at the specified point, or null if no suitable element is found.
Type Parameters
T

The type of element to search for.

GetPreferredSize(Size, Size)

Calculates the preferred size of the control based on the element tree layout. This method is called when AutoSize is true to determine the optimal control size.

Declaration
public virtual Size GetPreferredSize(Size proposedSize, Size sizeConstraints)
Parameters
System.Drawing.Size proposedSize

The proposed size for the control.
System.Drawing.Size sizeConstraints

Size constraints to apply during calculation.
Returns
System.Drawing.Size

The preferred System.Drawing.Size for the control.
Remarks

This method considers stretch properties of the root element and performs measure and arrange operations to determine the optimal size.

InitializeRootElement()

Initializes the root element of the tree and creates the initial element hierarchy.

Declaration
public virtual void InitializeRootElement()
Remarks

This method creates the root element if it doesn't exist, initializes it through the component tree handler, and sets up the initial child elements. It also manages layout suspension during initialization to improve performance.

OnAutoSizeChanged(EventArgs)

Handles the AutoSize property change event of the associated control.

Declaration
public virtual void OnAutoSizeChanged(EventArgs e)
Parameters
System.EventArgs e

The event arguments.
Remarks

This method updates the layout when AutoSize changes and notifies the root element of the AutoSize state change.

PerformInnerLayout(Boolean, Int32, Int32, Int32, Int32)

Performs the internal layout operation with specified parameters.

Declaration
public Size PerformInnerLayout(bool performMeasure, int x, int y, int width, int height)
Parameters
System.Boolean performMeasure

Whether to perform the measure phase of layout.
System.Int32 x

The x-coordinate for layout.
System.Int32 y

The y-coordinate for layout.
System.Int32 width

The width for layout.
System.Int32 height

The height for layout.
Returns
System.Drawing.Size

The resulting System.Drawing.Size after layout.
Remarks

This method handles the core layout logic including measure, arrange, and size calculation while respecting AutoSize settings and stretch properties.

PerformLayout()

Performs a layout operation on the element tree using the control's current bounds.

Declaration
public void PerformLayout()
Remarks

This method triggers a complete layout cycle including measure and arrange phases, and updates the control's size based on the layout results.

Extension Methods