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.
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.
Definition
Namespace:Telerik.WinControls
Assembly:Telerik.WinControls.dll
Syntax:
public class RootRadElement : RadItem, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IBindableComponent, IComponent, IDisposable, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode
Inheritance: objectDisposableObjectRadObjectRadElementVisualElementRadComponentElementRadItemRootRadElement...
Derived Classes:
Implements:
Inherited Members
Constructors
public RootRadElement()
Fields
Identifies the property that applies the root element's shape as the owning control's window region.
public static RadProperty ApplyShapeToControlProperty
Tunnels when the AutoSize property of RadControl changes in order to notify any children that should take special actions.
public static readonly RoutedEvent AutoSizeChangedEvent
Identifies the property that synchronizes the root element's bounds with its owning control.
public static RadProperty ControlBoundsProperty
Identifies the property that replaces the owning control's default size.
public static RadProperty ControlDefaultSizeProperty
Tunnels a notification that the owning control's image list changed so image primitives can refresh their content.
public static readonly RoutedEvent OnRoutedImageListChanged
Tunnels when the layout has been resumed in order to notify any children that should take special actions in this case - like RadHostItem.
public static RoutedEvent RootLayoutResumedEvent
Tunnels when the layout has been suspended in order to notify any children that should take special actions in this case - like RadHostItem.
public static RoutedEvent RootLayoutSuspendedEvent
Tunnels when some of the stretch properties (horizontal or vertical) has changed in order to notify any children that should take special actions.
public static readonly RoutedEvent StretchChangedEvent
Identifies the root element's paint-cache option exposed by UsePaintCache.
public static RadProperty UsePaintCacheProperty
Properties
Gets or sets the alignment of the element within its container.
[Browsable(false)]
public override ContentAlignment Alignment { get; set; }
Overrides:
Gets or sets the angle of rotation transformation applied to the element.
[Browsable(false)]
public override float AngleTransform { get; set; }
Overrides:
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.
public bool ApplyShapeToControl { get; set; }
Gets or sets the auto size mode for the root element.
public override RadAutoSizeMode AutoSizeMode { get; set; }
Overrides:
Gets or sets a value corresponding to the bounding rectangle of the owning Control.
public virtual Rectangle ControlBounds { get; set; }
Gets or sets the default size to replace the control's default size when set.
public Size ControlDefaultSize { get; set; }
When set, replaces the default control size. The returned value is scaled according to the current DPI scaling factor.
Gets or sets a value indicating whether text should be flipped.
[Browsable(false)]
public override bool FlipText { get; set; }
Overrides:
Gets or sets the foreground color of the element.
[TypeConverter(typeof(RadColorEditorConverter))]
public override Color ForeColor { get; set; }
Overrides:
Gets a value indicating whether this element is visible, taking into account both element and control visibility.
public override bool IsElementVisible { get; }
Overrides:
Gets or sets the key tip text for the element.
[Browsable(false)]
public override string KeyTip { get; set; }
Overrides:
Gets or sets the margin spacing around the element.
[Browsable(false)]
public override Padding Margin { get; set; }
Overrides:
Gets or sets the maximum size to apply on an element when layout is calculated.
public override Size MaxSize { get; set; }
Overrides:
For the root element, this property returns the unscaled maximum size since the control's MaximumSize property handles DPI scaling internally.
Gets or sets the minimum size to apply on an element when layout is calculated.
public override Size MinSize { get; set; }
Overrides:
For the root element, this property returns the unscaled minimum size since the control's MinimumSize property handles DPI scaling internally.
This property is not relevant for this class.
[Browsable(false)]
public override Padding Padding { get; set; }
Overrides:
Gets or sets a value indicating whether the element's text and content is rendered right-to-left.
[Browsable(false)]
public override bool RightToLeft { get; set; }
Overrides:
Gets or sets the text associated with this element.
public override string Text { get; set; }
Overrides:
For the root element, this property is not serialized and is not localizable.
Gets or sets the orientation of text within the element.
[Browsable(false)]
public override Orientation TextOrientation { get; set; }
Overrides:
Gets or sets the tool tip text displayed when the mouse pointer hovers over the element.
[Browsable(false)]
public override string ToolTipText { get; set; }
Overrides:
Gets or sets a value indicating whether to use compatible text rendering engine (GDI+) or not (GDI).
[Browsable(false)]
public override bool UseCompatibleTextRendering { get; set; }
Overrides:
Gets or sets a value indicating whether to use paint cache for optimized rendering performance.
public bool UsePaintCache { get; set; }
Methods
Applies the root's sizing constraints to the rectangle allocated by the layout manager.
protected override void ArrangeCore(RectangleF finalRect)
The rectangle allocated to the root by the layout manager.
Overrides:
Stretch settings and min/max constraints determine the root's final size. When the owning control is auto-sized, its size is updated to match the arranged root unless control-size synchronization is disabled.
Arranges child elements within the final layout size and returns the actual size used.
Coerces the value of the specified property, applying validation and default values where appropriate.
protected override object CoerceValue(RadPropertyValue propVal, object baseValue)
The property value wrapper containing metadata and the property definition.
baseValueobjectThe base value before coercion.
Returns:The coerced value.
Overrides:
Releases parent-control paint tracking before disposing the root element's base resources.
protected override void DisposeManagedResources()
Overrides:
Called when the DPI scaling changes, updating the scale factor for this element and all children.
public override void DpiScaleChanged(SizeF scaleFactor)
The new DPI scale factor to apply.
Overrides:
Resolves the root's arrange rectangle when the proposed size is not positive in both dimensions.
protected override RectangleF GetArrangeRect(RectangleF proposed)
The rectangle proposed by the layout manager.
Returns:The proposed rectangle when both dimensions are positive; otherwise, the control bounds with any positive-infinite dimensions replaced by the root's desired size.
Overrides:
Gets the inherited value for a property from the component tree handler.
protected override object GetInheritedValue(RadProperty property)
The property to get the inherited value for.
Returns:The inherited property value.
Overrides:
Sets the root to fit the available layout size and disables direct mouse-input handling after base initialization.
protected override void InitializeFields()
Overrides:
Measures the size required for child elements and returns the cumulative size needed.
Synchronizes the hosted control's size with the root element when automatic sizing is enabled.
protected override void OnBoundsChanged(RadPropertyChangedEventArgs e)
The root-element bounds change.
Overrides:
Synchronization is skipped while the layout manager is updating.
Applies a new default size to the hosted control when its current size still follows the default.
protected virtual void OnControlDefaultSizeChanged(RadPropertyChangedEventArgs e)
The default-size property change.
If the control has a custom size, this method increases its height only when it is below the new default; it does not adjust the width in that case.
Forwards display-affecting property changes to the component-tree handler.
protected override void OnDisplayPropertyChanged(RadPropertyChangedEventArgs e)
The display-affecting property change.
Overrides:
The change is forwarded only when the root element is in a valid state.
Raises the DpiScaleFactorChanged event.
protected virtual void OnDpiScaleFactorChanged()
Performs layout immediately for stretch-direction changes when the component tree can handle the request.
protected override void OnLayoutPropertyChanged(RadPropertyChangedEventArgs e)
The layout-affecting property change.
Overrides:
Other changes, or stretch changes without a component-tree handler, use the base layout invalidation.
Called when the element is loaded and ready for display operations.
protected override void OnLoaded()
Overrides:
Synchronizes the hosted control's location with the new root-element bounds.
protected override void OnLocationChanged(RadPropertyChangedEventArgs e)
The root-element bounds change containing the new location.
Overrides:
Synchronization is skipped while the layout manager is updating.
Called when a property value has changed, handling root element specific property change logic.
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
The property changed event arguments.
Overrides:
Called before a property value is changed, allowing for validation or cancellation.
protected override void OnPropertyChanging(RadPropertyChangingEventArgs args)
The property changing event arguments.
Overrides:
Paints the RootElement and its element tree. Intended for use by RadControl inheritors.
public void Paint(IGraphics graphics, Rectangle clipRectangle, bool useRelativeTransformation)
Graphics object to be used to paint elements.
clipRectangleRectangleClipping rectangle to be painted. Only those elements from the tree which intersect with this rectangle will be painted.
useRelativeTransformationboolTrue to use relative transformation; otherwise, false.
Paints the RootElement and its element tree. Intended for use by RadControl inheritors.
Paints a shadow effect behind the control when the element shadow is enabled.
public void PaintControlShadow()
Paints the root element's shadow onto its parent control while the owning control is visible.
protected void Parent_Paint(object sender, PaintEventArgs e)
The parent control that raised the paint event.
ePaintEventArgsThe paint context whose graphics surface receives the shadow.
Indicates that no layout transformation is needed for the root element as it represents the control itself.
Applies root-specific rules when deciding whether a property should be included in designer serialization.
public override bool? ShouldSerializeProperty(PropertyDescriptor property)
bool?
Overrides:
Stretch settings are serialized only when they differ from the root's recorded defaults.
ToolTipTextis included only when non-empty;Alignment,AngleTransform,FlipText,Margin, andTextOrientationare included only when they differ from their metadata defaults. Root-managed properties are suppressed, while other properties return null so the designer's default handling can apply.
Events
Occurs after DPI scaling has been applied to the root element and its descendants.
public event EventHandler DpiScaleFactorChanged
This event is not raised when EnableDpiScaling is disabled.