IComponentTreeHandler
Defines the contract for handling component tree operations and ambient property management in RadControls.
IComponentTreeHandler extends ILayoutHandler to provide comprehensive component tree management capabilities including element tree creation, initialization, and ambient property handling. This interface is essential for RadControls that need to manage complex element hierarchies.
The interface handles ambient properties (properties that can be inherited from parent controls such as BackColor, ForeColor, and Font), theme management, tooltip support, and focus cues. It provides the foundation for RadControl's element tree architecture.
Implementers are responsible for creating and managing the root element, handling tree loading operations, and coordinating with the layout system to ensure proper rendering and behavior.
Definition
Namespace:Telerik.WinControls
Assembly:Telerik.WinControls.dll
Syntax:
public interface IComponentTreeHandler : ILayoutHandler
Inherited Members
Properties
Gets the behavior object that routes input between the control and its element tree.
ComponentInputBehavior Behavior { get; }
Gets the theme-aware element tree managed by this component.
ComponentThemableElementTree ElementTree { get; }
Gets or sets the image list used for images in the component.
ImageList ImageList { get; set; }
Gets or sets the size used to render images from ImageList.
Size ImageScalingSize { get; set; }
Gets whether the component is being initialized or its element tree has not yet been loaded.
bool Initializing { get; }
Gets whether the component is hosted in a design environment.
bool IsDesignMode { get; }
Gets the root element of the component's element tree.
RootRadElement RootElement { get; }
Gets or sets the image list used for small images in the component.
ImageList SmallImageList { get; set; }
Gets or sets the size used to render small images from SmallImageList.
Size SmallImageScalingSize { get; set; }
Gets or sets the class identifier used when resolving themes for elements in the tree.
string ThemeClassName { get; set; }
Methods
Dispatches a mouse-capture change notification to the component.
void CallOnMouseCaptureChanged(EventArgs e)
Event data for the capture change.
Dispatches a screen-tip request to the component.
void CallOnScreenTipNeeded(object sender, ScreenTipNeededEventArgs e)
The object requesting the screen tip.
eScreenTipNeededEventArgsThe screen-tip request data.
Dispatches a theme-name change notification to the component.
void CallOnThemeNameChanged(ThemeNameChangedEventArgs e)
The old and new theme names.
Dispatches an element's tooltip-text request to the component.
void CallOnToolTipTextNeeded(object sender, ToolTipTextNeededEventArgs e)
The element requesting tooltip text.
eToolTipTextNeededEventArgsThe request data, including the tooltip text that can be supplied.
Determines whether the component supplies the theme for the specified element.
bool ControlDefinesThemeForElement(RadElement element)
The element whose theme ownership is being checked.
Returns:true when theme resolution should not assign a theme to the element.
Notifies the component that its resolved theme has changed.
void ControlThemeChangedCallback()
Adds the component-specific child elements to the specified parent.
void CreateChildItems(RadElement parent)
The element that will receive the child elements.
Creates the root element for this component's element tree.
RootRadElement CreateRootElement()
The root element that will host the component's child elements.
Returns the value for some ambient properties like BackColor, ForelColor, Font, etc.
Initializes the root element after it has been created for the component tree.
void InitializeRootElement(RootRadElement rootElement)
The root element to initialize.
Requests repainting the specified bounds for an element.
void InvalidateElement(RadElement element, Rectangle bounds)
The element associated with the invalidation.
boundsRectangleThe bounds to invalidate.
Requests repainting the specified element using its invalidation bounds.
void InvalidateElement(RadElement element)
The element whose bounds need repainting.
Invalidates the component unless updates are currently suspended.
void InvalidateIfNotSuspended()
Loads the element tree using the handler's current control size.
void LoadElementTree()
Loads the element tree using the specified initial size. Layout is unavailable until the tree is loaded.
Updates after a change in an ambient property like BackColor, ForeColor, Font, etc.
Forwards an element's request to change mouse capture to the component.
Notifies the handler that the root element's Display property changed.
void OnDisplayPropertyChanged(RadPropertyChangedEventArgs e)
The property-change data for the display update.
Forwards a focus request from an element to the component.
bool OnFocusRequested(RadElement element)
The element requesting focus.
Returns:Adds the hosted control for a RadHostItem to the component's control collection.
void RegisterHostedControl(RadHostItem hostElement)
The host item whose control should be registered.
Resumes component updates and invalidates after the final suspension is released.
void ResumeUpdate()
Suspends component updates; calls can be nested and must be balanced with ResumeUpdate().
void SuspendUpdate()
Unregisters a hosted control and optionally removes it from the component's control collection.
void UnregisterHostedControl(RadHostItem hostElement, bool removeControl)
The host item whose control should be unregistered.
removeControlbooltrue to remove the hosted control from the collection.
Events
Occurs when the component's theme name changes.
event ThemeNameChangedEventHandler ThemeNameChanged
Occurs when an element requests tooltip text from the component.
event ToolTipTextNeededEventHandler ToolTipTextNeeded