Class RadHostItem

Represents a RadItem that can host any external Windows Forms control, providing seamless integration between standard Windows Forms controls and the Telerik Presentation Framework.

Inheritance
System.Object
DisposableObject
RadObject
RadElement
VisualElement
RadComponentElement
RadItem
RadHostItem
GridViewHostItem
RadTextBoxItem
RadWebBrowserItem
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 RadHostItem : RadItem, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IComponent, IDisposable, IBindableComponent, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode
Remarks

RadHostItem enables any standard Windows Forms control (such as TextBox, ComboBox, DateTimePicker, or custom user controls) to be embedded within the Telerik element tree, participating in layout management, theming, and event routing while maintaining their native functionality.

The hosted control can be any descendant of the System.Windows.Forms.Control class with no restrictions. RadHostItem handles proper sizing, positioning, and lifecycle management of the hosted control, including focus management, validation events, and parent-child relationship maintenance.

Common use cases include integrating legacy Windows Forms controls into modern Telerik interfaces, hosting specialized controls within Telerik containers, and creating hybrid layouts that combine TPF elements with traditional Windows Forms controls for maximum flexibility.

Constructors

RadHostItem(Control)

Initializes a new instance of the RadHostItem class with the specified control to host.

Declaration
public RadHostItem(Control c)
Parameters
System.Windows.Forms.Control c

The System.Windows.Forms.Control to be hosted within this RadHostItem. This can be any Windows Forms control or custom control.
Remarks

The constructor automatically synchronizes inheritable properties such as ForeColor, BackColor, and Font between the host item and the hosted control.

If the hosted control is a RadControl, special handling is applied to synchronize properties with the root element rather than the control directly.

Event wiring is automatically established to ensure proper integration between the hosted control and the Telerik element hierarchy.

Fields

RadHostItemLastStateKey

This constant is not relevant for this class.

Declaration
protected const long RadHostItemLastStateKey = 8796093022208L
Field Value
System.Int64

Properties

CausesValidation

Gets or sets the CausesValidation property of the hosted control.

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

Remarks

Using this property is equivalent to using HostedControl.CausesValidation

ClipControl

Gets or sets a value that determines whether the hosted control should be clipped when it requires more space than available.

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

true if the hosted control should be clipped to fit within the available bounds; otherwise, false. The default value is true.
Remarks

When set to true, the hosted control will be automatically resized and clipped if it exceeds the available space allocated to the RadHostItem. This ensures the control does not overlap with other elements in the layout.

When set to false, the hosted control can extend beyond the bounds of the RadHostItem, which may cause visual overlap with adjacent elements.

Enabled

Gets or sets a value indicating whether the RadHostItem and its hosted control are enabled.

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

true if both the RadHostItem and its hosted control are enabled; otherwise, false.
Overrides
Remarks

When this property is set, the enabled state is automatically synchronized with the hosted control. Setting this to false will also disable the hosted control, preventing user interaction. If the hosted control supports disabled appearance, it will be rendered accordingly.

HostedControl

Gets the instance of the hosted Windows Forms control.

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

The System.Windows.Forms.Control instance that is being hosted by this RadHostItem.
Remarks

This property provides direct access to the Windows Forms control that is hosted within the RadHostItem. The hosted control maintains its native functionality while being integrated into the Telerik element tree.

The hosted control can be any descendant of the System.Windows.Forms.Control class, including standard Windows Forms controls, third-party controls, or custom user controls.

Changes to the hosted control's properties should be made through this property or through the RadHostItem's synchronized properties to ensure proper integration with the TPF framework.

RouteMessages

Gets or sets whether the mouse and keyboard messages from the hosted control can be routed to the owner control.

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

Remarks

You can use Control to get the owner control.

To get the hosted control use HostedControl property.

Methods

ArrangeCore(RectangleF)

Arranges the hosted control within the final layout rectangle, handling size synchronization.

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

The final area within which this element should arrange its hosted control.
Overrides

DisposeManagedResources()

Releases managed resources used by this element, including disposing the hosted control.

Declaration
protected override void DisposeManagedResources()
Overrides

DpiScaleChanged(SizeF)

Called when the DPI scaling changes, updating the font synchronization for the hosted control.

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

The new DPI scale factor.
Overrides

EnsureHostedControl()

Ensures the hosted control is properly registered with the component tree handler.

Declaration
protected void EnsureHostedControl()

Focus()

Attempts to set focus to the hosted control.

Declaration
public override bool Focus()
Returns
System.Boolean

true if the hosted control successfully received focus; otherwise, false.
Overrides
Remarks

This method attempts to set focus to the hosted control. If the hosted control implements IComponentTreeHandler, the focus request is routed through the interface. Otherwise, the default focus behavior is applied.

InitializeFields()

Initializes the fields of this instance with their default values.

Declaration
protected override void InitializeFields()
Overrides

MeasureOverride(SizeF)

Measures the size required by the hosted control and returns the desired size.

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

The available size that this element can allocate to the hosted control.
Returns
System.Drawing.SizeF

The desired size needed by this element based on the hosted control's size requirements.
Overrides

OnElementTreeChanged(ComponentThemableElementTree)

Called when the element tree changes, handling registration and unregistration of the hosted control.

Declaration
protected override void OnElementTreeChanged(ComponentThemableElementTree previousTree)
Parameters
ComponentThemableElementTree previousTree

The previous element tree that this element was part of.
Overrides

OnGotFocus(EventArgs)

Raises the GotFocus event.

Declaration
protected virtual void OnGotFocus(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.

OnLoaded()

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

Declaration
protected override void OnLoaded()
Overrides

OnLostFocus(EventArgs)

Raises the LostFocus event.

Declaration
protected virtual void OnLostFocus(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.

OnPropertyChanged(RadPropertyChangedEventArgs)

Called when a property value has changed, handling synchronization of properties between the RadHostItem and the hosted control.

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

The property changed event arguments.
Overrides

OnTransformationInvalidated()

Called when transformation is invalidated, synchronizing bounds with the hosted control.

Declaration
protected override void OnTransformationInvalidated()
Overrides

OnTunnelEvent(RadElement, RoutedEventArgs)

Called when a tunnel event is received, handling layout suspension/resumption for the hosted control.

Declaration
protected override void OnTunnelEvent(RadElement sender, RoutedEventArgs args)
Parameters
RadElement sender

The element that raised the event.
RoutedEventArgs args

The routed event arguments.
Overrides

OnValidated(EventArgs)

Raises the Validated event.

Declaration
protected virtual void OnValidated(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.

OnValidating(CancelEventArgs)

Raises the Validating event.

Declaration
protected virtual void OnValidating(CancelEventArgs e)
Parameters
System.ComponentModel.CancelEventArgs e

A System.ComponentModel.CancelEventArgs that contains the event data.

SyncBoundsWithHostedControl()

Synchronizes the bounds of the hosted control with the RadHostItem's current position and size.

Declaration
protected virtual void SyncBoundsWithHostedControl()

SyncFont(Font)

Synchronizes the font of the hosted control with the RadHostItem's font, applying DPI scaling if necessary.

Declaration
protected virtual void SyncFont(Font font)
Parameters
System.Drawing.Font font

The font to synchronize with the hosted control.

UpdateControlVisibility()

Updates the visibility, which is bound to the item's current IsVisible state, of the hosted control.

Declaration
public void UpdateControlVisibility()

Events

GotFocus

Occurs when the element receives focus.

Declaration
public event EventHandler GotFocus
Event Type
System.EventHandler

LostFocus

Occurs when the element loses focus.

Declaration
public event EventHandler LostFocus
Event Type
System.EventHandler

Validated

Corresponds to the hosted control's Validated event.

Declaration
public event EventHandler Validated
Event Type
System.EventHandler

Validating

Corresponds to the hosted control's Validating event.

Declaration
public event CancelEventHandler Validating
Event Type
System.ComponentModel.CancelEventHandler

Extension Methods