ComponentBehavior
Manages behavioral aspects of RadControl components including input handling, element selection, keyboard navigation, tooltips, and visual feedback mechanisms.
ComponentBehavior serves as a centralized behavioral controller for RadControl instances, handling complex interactions between the control and its element tree. It manages mouse and keyboard input routing, element selection states, focus management, and various user interface feedback mechanisms.
Key responsibilities include:
- Element capture and selection management
- Keyboard navigation and shortcut handling
- Tooltip and screen tip presentation
- Mnemonic activation and processing
- Visual state management (pressed, selected, focused elements)
- Resource management for rendering optimizations
The behavior component works closely with the IComponentTreeHandler interface to provide seamless integration between Windows Forms control behavior and the RadElement tree structure.
Definition
Namespace:Telerik.WinControls
Assembly:Telerik.WinControls.dll
Syntax:
public class ComponentBehavior : IDisposable
Inheritance: objectComponentBehavior
Derived Classes:
Implements:
Constructors
Initializes a new instance of the ComponentBehavior class for the specified component tree handler.
public ComponentBehavior(IComponentTreeHandler owner)
The IComponentTreeHandler that owns this behavior instance.
The constructor establishes the relationship between the behavior manager and its owner component, enabling the behavior to manage input, focus, and visual state for the associated control and its element tree.
Fields
Tracks the captured item's hit-test state while input is routed to it.
protected bool ItemCaptureState
Properties
Indicates focus cues display, when available, based on the corresponding control type and the current UI state.
public virtual bool AllowShowFocusCues { get; set; }
Gets the fill repository used to cache bitmaps shared by the component's drawing primitives.
public FillRepository BitmapRepository { get; }
Gets the input bindings used to associate keyboard gestures with commands.
[TypeConverter(typeof(ExpandableObjectConverter))]
public InputBindingsCollection CommandBindings { get; }
Gets the default tooltip visibility used when input behavior is initialized.
protected virtual bool DefaultShowItemToolTips { get; }
The base implementation returns true.
Gets or sets whether Key Map (Office 2007 like accelerator keys map) is used for this specific control. Currently this option is implemented for the RadRibbonBar control only.
[Browsable(true)]
public bool EnableKeyMap { get; set; }
Gets or sets the currently focused RadElement within the component tree.
[Browsable(false)]
public RadElement FocusedElement { get; set; }
The RadElement that currently has input focus, or null if no element is focused.
Setting this property to a specific element will give focus to that element and remove focus from any previously focused element. Setting it to
nullwill remove focus from the currently focused element. This property coordinates with the focus management system to ensure proper focus state handling throughout the element tree.
Gets whether this instance of RadControl is on a active form
protected bool IsParentFormActive { get; }
Determines whether the mouse over the owning IComponentTreeHandler instance.
public bool MouseOver { get; }
Gets the component-tree handler whose behavior is managed by this instance.
protected IComponentTreeHandler Owner { get; }
Gets the Windows Forms control that hosts the Telerik element tree.
[Browsable(false)]
protected Control OwnerControl { get; }
Gets the current selected element (hovered by the mouse).
[Browsable(false)]
public RadElement SelectedElement { get; }
Gets or sets a value indicating whether ToolTips are shown for the RadItem objects contained in the RadControl.
public bool ShowItemToolTips { get; set; }
Gets or sets value indicating whether the control should show all screen tips under the control client rectangle, as required for the RibbonBar control, for example
public bool ShowScreenTipsBellowControl { get; set; }
Gets the ToolTip instance used to display element tooltips within the component.
public ToolTip ToolTip { get; }
A ToolTip instance that handles tooltip display for elements within the component tree. The property creates a RadToolTip instance on first access if one doesn't already exist.
The tooltip is lazily created when first accessed. If the component has a valid element tree with a root element, a RadToolTip is created with that root element as context. Otherwise, a default RadToolTip instance is created.
This tooltip is used throughout the component to display contextual help text for elements that have their ToolTipText property set.
Gets or sets the value of how much the tooltip will be moved on the X coordinate
public int ToolTipOffsetX { get; set; }
Gets or sets the value of how much the tooltip will be moved on the Y coordinate
public int ToolTipOffsetY { get; set; }
Methods
Releases all resources used by the ComponentBehavior instance.
public void Dispose()
Implements:
This method cleans up managed resources including element references, keyboard mappings, tooltips, screen tip presenters, and shortcut collections. It follows the standard .NET disposal pattern and suppresses finalization.
Releases managed resources and references owned by this behavior.
Removes and disposes the adorner layer used for key-tip overlays.
protected virtual void DisposeAdornerLayer()
Clears all resources reserved for the KeyTips functionality
protected virtual void DisposeKeyTips()
Finds the first eligible item with the specified mnemonic in a control's element tree.
Checks whether an element is an enabled, visible item whose text contains the specified mnemonic.
protected RadItem GetActivatedItem(RadElement element, char charCode)
The element to check.
charCodecharThe mnemonic character to match.
Returns:The matching item, or null if the element does not meet the criteria.
Gets the items available at the next key-tip level below the specified item.
public virtual List<RadItem> GetCurrentKeyMap(RadItem currentKeyMapItem)
The item whose children form the next key-tip level.
Returns:List<RadItem>
The items available at that level. Derived behaviors must provide a non-null list when key-tip processing uses it.
Provides the child items available for key-tip navigation beneath the specified item.
protected virtual List<RadItem> GetKeyFocusChildren(RadItem currentKeyMapItem)
The current item in the key-tip path.
Returns:List<RadItem>
The child items for this key-tip level. The base implementation returns null; derived behaviors that use key-tip processing must return a non-null list.
Adds themed child controls that can process mnemonics to the search list.
Hides the screen tip currently displayed by this behavior.
public void HideScreenTip()
Creates or raises the adorner layer used to display key-tip overlays.
protected virtual void InitializeAdornerLayer()
Enters key-tip mode, saving the current cursor and focus before clearing the active key-tip path.
protected virtual void InitializeKeyMap()
Determines whether an item's explicit or automatic key tip exactly matches the supplied fragment.
Checks is a given element or any of its descendants contain the focus.
public bool IsFocusWithin(RadElement element)
The element.
Returns:[true] if the element or any of its children contain focus, [false] otherwise.
Finds a key-tip fragment in an item's explicit or automatically assigned key tip.
Extends the current key-tip path when the input matches a child key tip, selecting an item on an exact match.
Called when EnableKeyTips changes so derived behaviors can update key-tip resources.
protected virtual void OnEnableKeyTipsChanged()
The base implementation does not create or dispose the adorner layer.
Handles the event that occurs when the control receives focus, restoring focus to the last focused element.
public virtual bool OnGotFocus(EventArgs e)
An EventArgs that contains the event data.
Returns:true if the event is handled; otherwise, false.
This method is called when the owner control gains focus. It attempts to restore focus to the element that was previously focused before the control lost focus, maintaining focus continuity for improved user experience.
If a last focused element exists and is not disposed, it becomes the current focused element and receives input focus. The last focused element reference is then cleared.
Handles the event that occurs when the control loses focus, preserving the focus state for later restoration.
public virtual bool OnLostFocus(EventArgs e)
An EventArgs that contains the event data.
Returns:true if the event is handled; otherwise, false.
This method is called when the owner control loses focus. It removes focus from the currently focused element and stores a reference to it for later restoration when the control regains focus.
Additionally, if keyboard mapping (key tips) is active, this method resets the key map state to ensure proper cleanup when focus is lost.
Assigns sequential numeric key tips to child items that have neither an explicit nor an automatic key tip.
Exits key-tip mode, clears its active path, and restores the cursor and previously focused window.
protected virtual void ResetKeyMap()
Clears key-tip mode and its active path without restoring the previously focused window.
protected virtual void ResetKeyMapInternal()
Sets a RadProperty value on the control thread, posting the update when called from another thread.
public void SetElementValue(RadElement element, RadProperty dependencyProperty, object value)
The element whose property is updated.
dependencyPropertyRadPropertyThe property to set.
valueobjectThe new property value.