Class RootRadElement

Represents the top-level element in a RadControl's element hierarchy, serving as the root container and coordination point for all child elements within the Telerik Presentation Framework.

Inheritance
System.Object
DisposableObject
RadObject
RadElement
VisualElement
RadComponentElement
RadItem
RootRadElement
FormRootElement
PanelRootElement
RadBindingNavigator.RadBindingNavigatorRootElement
RadCommandBar.RadCommandBarRootElement
RadDropDownListRootElement
RadLabelRootElement
RadMenu.RadMenuRootElement
RadScrollbarRootRadElement
WebCamRootRadElement
Inherited Members
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 RootRadElement : RadItem, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IComponent, IDisposable, IBindableComponent, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode
Remarks

RootRadElement serves as the foundational entry point into the TPF element tree, acting as the bridge between the Windows Forms RadControl host and the element-based architecture. Every RadControl has exactly one RootRadElement accessible through the RootElement property.

The root element manages layout coordination with suspension/resumption, property inheritance as the source for cascading properties (fonts, colors, themes), and event routing coordination for both tunneling and bubbling events. It maintains the connection between Windows Forms and TPF systems.

Critical routed events include AutoSizeChangedEvent, StretchChangedEvent, and layout events (RootLayoutSuspendedEvent, RootLayoutResumedEvent) that coordinate behavior across the control hierarchy and enable optimized batch operations.

Constructors

RootRadElement()

Declaration
public RootRadElement()

Fields

ApplyShapeToControlProperty

Declaration
public static RadProperty ApplyShapeToControlProperty
Field Value
RadProperty

AutoSizeChangedEvent

Tunnels when the AutoSize property of RadControl changes in order to notify any children that should take special actions.

Declaration
public static readonly RoutedEvent AutoSizeChangedEvent
Field Value
RoutedEvent

ControlBoundsProperty

Declaration
public static RadProperty ControlBoundsProperty
Field Value
RadProperty

ControlDefaultSizeProperty

Declaration
public static RadProperty ControlDefaultSizeProperty
Field Value
RadProperty

OnRoutedImageListChanged

Declaration
public static readonly RoutedEvent OnRoutedImageListChanged
Field Value
RoutedEvent

RootLayoutResumedEvent

Tunnels when the layout has been resumed in order to notify any children that should take special actions in this case - like RadHostItem.

Declaration
public static RoutedEvent RootLayoutResumedEvent
Field Value
RoutedEvent

RootLayoutSuspendedEvent

Tunnels when the layout has been suspended in order to notify any children that should take special actions in this case - like RadHostItem.

Declaration
public static RoutedEvent RootLayoutSuspendedEvent
Field Value
RoutedEvent

StretchChangedEvent

Tunnels when some of the stretch properties (horizontal or vertical) has changed in order to notify any children that should take special actions.

Declaration
public static readonly RoutedEvent StretchChangedEvent
Field Value
RoutedEvent

UsePaintCacheProperty

Declaration
public static RadProperty UsePaintCacheProperty
Field Value
RadProperty

Properties

Alignment

Gets or sets the alignment of the element within its container.

Declaration
public override ContentAlignment Alignment { get; set; }
Property Value
System.Drawing.ContentAlignment

Overrides

AngleTransform

Gets or sets the angle of rotation transformation applied to the element.

Declaration
public override float AngleTransform { get; set; }
Property Value
System.Single

Overrides

ApplyShapeToControl

Gets or sets value indicating whether the shape set to the root element would be applied as a region to the RadControl that contains the element.

Declaration
[RadPropertyDefaultValue("ApplyShapeToControl", typeof(RootRadElement))]
public bool ApplyShapeToControl { get; set; }
Property Value
System.Boolean

AutoSizeMode

Gets or sets the auto size mode for the root element.

Declaration
public override RadAutoSizeMode AutoSizeMode { get; set; }
Property Value
RadAutoSizeMode

Overrides

ControlBounds

Gets or sets a value corresponding to the bounding rectangle of the owning System.Windows.Forms.Control.

Declaration
[RadPropertyDefaultValue("ControlBounds", typeof(RootRadElement))]
public virtual Rectangle ControlBounds { get; set; }
Property Value
System.Drawing.Rectangle

ControlDefaultSize

Gets or sets the default size to replace the control's default size when set.

Declaration
[RadPropertyDefaultValue("ControlDefaultSize", typeof(RootRadElement))]
public Size ControlDefaultSize { get; set; }
Property Value
System.Drawing.Size

Remarks

When set, replaces the default control size. The returned value is scaled according to the current DPI scaling factor.

DisableControlSizeSet

This property is not relevant for this class.

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

FlipText

Gets or sets a value indicating whether text should be flipped.

Declaration
public override bool FlipText { get; set; }
Property Value
System.Boolean

Overrides

ForeColor

Gets or sets the foreground color of the element.

Declaration
public override Color ForeColor { get; set; }
Property Value
System.Drawing.Color

Overrides

IsElementVisible

Gets a value indicating whether this element is visible, taking into account both element and control visibility.

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

Overrides

KeyTip

Gets or sets the key tip text for the element.

Declaration
public override string KeyTip { get; set; }
Property Value
System.String

Overrides

Margin

Gets or sets the margin spacing around the element.

Declaration
public override Padding Margin { get; set; }
Property Value
System.Windows.Forms.Padding

Overrides

MaxSize

Gets or sets the maximum size to apply on an element when layout is calculated.

Declaration
public override Size MaxSize { get; set; }
Property Value
System.Drawing.Size

Overrides
Remarks

For the root element, this property returns the unscaled maximum size since the control's MaximumSize property handles DPI scaling internally.

MinSize

Gets or sets the minimum size to apply on an element when layout is calculated.

Declaration
public override Size MinSize { get; set; }
Property Value
System.Drawing.Size

Overrides
Remarks

For the root element, this property returns the unscaled minimum size since the control's MinimumSize property handles DPI scaling internally.

Padding

This property is not relevant for this class.

Declaration
public override Padding Padding { get; set; }
Property Value
System.Windows.Forms.Padding

Overrides

RightToLeft

Gets or sets a value indicating whether the element's text and content is rendered right-to-left.

Declaration
public override bool RightToLeft { get; set; }
Property Value
System.Boolean

Overrides

Text

Gets or sets the text associated with this element.

Declaration
public override string Text { get; set; }
Property Value
System.String

Overrides
Remarks

For the root element, this property is not serialized and is not localizable.

TextOrientation

Gets or sets the orientation of text within the element.

Declaration
public override Orientation TextOrientation { get; set; }
Property Value
System.Windows.Forms.Orientation

Overrides

ToolTipText

Gets or sets the tool tip text displayed when the mouse pointer hovers over the element.

Declaration
public override string ToolTipText { get; set; }
Property Value
System.String

Overrides

UseCompatibleTextRendering

Gets or sets a value indicating whether to use compatible text rendering engine (GDI+) or not (GDI).

Declaration
public override bool UseCompatibleTextRendering { get; set; }
Property Value
System.Boolean

Overrides

UsePaintCache

Gets or sets a value indicating whether to use paint cache for optimized rendering performance.

Declaration
[RadPropertyDefaultValue("UsePaintCache", typeof(RootRadElement))]
public bool UsePaintCache { get; set; }
Property Value
System.Boolean

Methods

ArrangeCore(RectangleF)

Declaration
protected override void ArrangeCore(RectangleF finalRect)
Parameters
System.Drawing.RectangleF finalRect

Overrides

ArrangeOverride(SizeF)

Arranges child elements within the final layout size and returns the actual size used.

Declaration
protected override SizeF ArrangeOverride(SizeF finalSize)
Parameters
System.Drawing.SizeF finalSize

The final area within which the root element should arrange its child elements.
Returns
System.Drawing.SizeF

The actual size used during the arrange pass.
Overrides

CoerceValue(RadPropertyValue, Object)

Coerces the value of the specified property, applying validation and default values where appropriate.

Declaration
protected override object CoerceValue(RadPropertyValue propVal, object baseValue)
Parameters
RadPropertyValue propVal

The property value wrapper containing metadata and the property definition.
System.Object baseValue

The base value before coercion.
Returns
System.Object

The coerced value.
Overrides

DisposeManagedResources()

Declaration
protected override void DisposeManagedResources()
Overrides

DpiScaleChanged(SizeF)

Called when the DPI scaling changes, updating the scale factor for this element and all children.

Declaration
public override void DpiScaleChanged(SizeF scaleFactor)
Parameters
System.Drawing.SizeF scaleFactor

The new DPI scale factor to apply.
Overrides

GetArrangeRect(RectangleF)

Declaration
protected override RectangleF GetArrangeRect(RectangleF proposed)
Parameters
System.Drawing.RectangleF proposed

Returns
System.Drawing.RectangleF

Overrides

GetInheritedValue(RadProperty)

Gets the inherited value for a property from the component tree handler.

Declaration
protected override object GetInheritedValue(RadProperty property)
Parameters
RadProperty property

The property to get the inherited value for.
Returns
System.Object

The inherited property value.
Overrides

InitializeFields()

Declaration
protected override void InitializeFields()
Overrides

MeasureCore(SizeF)

Measures the core size of the root element, applying size constraints and stretch behavior.

Declaration
protected override SizeF MeasureCore(SizeF availableSize)
Parameters
System.Drawing.SizeF availableSize

The available size for measuring.
Returns
System.Drawing.SizeF

The measured size for the root element.
Overrides

MeasureOverride(SizeF)

Measures the size required for child elements and returns the cumulative size needed.

Declaration
protected override SizeF MeasureOverride(SizeF availableSize)
Parameters
System.Drawing.SizeF availableSize

The available size that the root element can allocate to child elements.
Returns
System.Drawing.SizeF

The desired size needed by the root element based on its children.
Overrides

NotifyControlImageListChanged()

This method is used internally.

Declaration
public void NotifyControlImageListChanged()

OnBoundsChanged(RadPropertyChangedEventArgs)

Declaration
protected override void OnBoundsChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

Overrides

OnControlDefaultSizeChanged(RadPropertyChangedEventArgs)

Declaration
protected virtual void OnControlDefaultSizeChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

OnDisplayPropertyChanged(RadPropertyChangedEventArgs)

Declaration
protected override void OnDisplayPropertyChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

Overrides

OnDpiScaleFactorChanged()

Raises the DpiScaleFactorChanged event.

Declaration
protected virtual void OnDpiScaleFactorChanged()

OnLayoutPropertyChanged(RadPropertyChangedEventArgs)

Declaration
protected override void OnLayoutPropertyChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

Overrides

OnLoaded()

Called when the element is loaded and ready for display operations.

Declaration
protected override void OnLoaded()
Overrides

OnLocationChanged(RadPropertyChangedEventArgs)

Declaration
protected override void OnLocationChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

Overrides

OnPropertyChanged(RadPropertyChangedEventArgs)

Called when a property value has changed, handling root element specific property change logic.

Declaration
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

The property changed event arguments.
Overrides

OnPropertyChanging(RadPropertyChangingEventArgs)

Called before a property value is changed, allowing for validation or cancellation.

Declaration
protected override void OnPropertyChanging(RadPropertyChangingEventArgs args)
Parameters
RadPropertyChangingEventArgs args

The property changing event arguments.
Overrides

Paint(IGraphics, Rectangle)

Paints the RootElement and its element tree. Intended for use by RadControl inheritors.

Declaration
public void Paint(IGraphics graphics, Rectangle clipRectangle)
Parameters
IGraphics graphics

Graphics object to be used to paint elements.
System.Drawing.Rectangle clipRectangle

Clipping rectangle to be painted. Only those elements from the tree which intersect with this rectangle will be painted.

Paint(IGraphics, Rectangle, Boolean)

Paints the RootElement and its element tree. Intended for use by RadControl inheritors.

Declaration
public void Paint(IGraphics graphics, Rectangle clipRectangle, bool useRelativeTransformation)
Parameters
IGraphics graphics

Graphics object to be used to paint elements.
System.Drawing.Rectangle clipRectangle

Clipping rectangle to be painted. Only those elements from the tree which intersect with this rectangle will be painted.
System.Boolean useRelativeTransformation

True to use relative transformation; otherwise, false.

PaintControlShadow()

Paints a shadow effect behind the control when the element shadow is enabled.

Declaration
public void PaintControlShadow()

Parent_Paint(Object, PaintEventArgs)

Declaration
protected void Parent_Paint(object sender, PaintEventArgs e)
Parameters
System.Object sender

System.Windows.Forms.PaintEventArgs e

PerformLayoutTransformation(ref RadMatrix)

Indicates that no layout transformation is needed for the root element as it represents the control itself.

Declaration
protected override bool PerformLayoutTransformation(ref RadMatrix matrix)
Parameters
RadMatrix matrix

The transformation matrix (not used for root element).
Returns
System.Boolean

False, indicating no layout transformation is applied.
Overrides

SaveCurrentStretchModeAsDefault()

This method is not relevant for this class.

Declaration
public void SaveCurrentStretchModeAsDefault()

ShouldSerializeProperty(PropertyDescriptor)

Declaration
public override bool? ShouldSerializeProperty(PropertyDescriptor property)
Parameters
System.ComponentModel.PropertyDescriptor property

Returns
System.Nullable<System.Boolean>

Overrides

Events

DpiScaleFactorChanged

Declaration
public event EventHandler DpiScaleFactorChanged
Event Type
System.EventHandler

Extension Methods