Class ComponentBehavior

Manages behavioral aspects of RadControl components including input handling, element selection, keyboard navigation, tooltips, and visual feedback mechanisms.

Inheritance
System.Object
ComponentBehavior
ComponentInputBehavior
Inherited Members
System.Object.ToString()
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 ComponentBehavior : IDisposable
Remarks

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.

Constructors

ComponentBehavior(IComponentTreeHandler)

Initializes a new instance of the ComponentBehavior class for the specified component tree handler.

Declaration
public ComponentBehavior(IComponentTreeHandler owner)
Parameters
IComponentTreeHandler owner

The IComponentTreeHandler that owns this behavior instance.
Remarks

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

ItemCaptureState

Declaration
protected bool ItemCaptureState
Field Value
System.Boolean

Properties

ActiveKeyMapItem

Declaration
public RadItem ActiveKeyMapItem { get; set; }
Property Value
RadItem

AllowShowFocusCues

Indicates focus cues display, when available, based on the corresponding control type and the current UI state.

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

BitmapRepository

Declaration
public FillRepository BitmapRepository { get; }
Property Value
FillRepository

CommandBindings

Declaration
public InputBindingsCollection CommandBindings { get; }
Property Value
InputBindingsCollection

CurrentFocusedElement

Gets the RadElement that currently has focus within the component. This property is used internally.

Declaration
public RadElement CurrentFocusedElement { get; }
Property Value
RadElement

The RadElement that currently has input focus within the component tree.
Remarks

This property provides direct access to the internally tracked focused element. It is used internally by the focus management system and should not be modified directly by application code. Use the FocusedElement property for programmatic focus management.

DefaultShowItemToolTips

Declaration
protected virtual bool DefaultShowItemToolTips { get; }
Property Value
System.Boolean

EnableKeyMap

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.

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

EnableKeyTips

Gets or sets whether Key Tips (Office 2007 like accelerator keys map) are used for this specific control.

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

FocusedElement

Gets or sets the currently focused RadElement within the component tree.

Declaration
public RadElement FocusedElement { get; set; }
Property Value
RadElement

The RadElement that currently has input focus, or null if no element is focused.
Remarks

Setting this property to a specific element will give focus to that element and remove focus from any previously focused element. Setting it to null will 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.

IsKeyMapActive

This property is used internally!

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

IsParentFormActive

Gets whether this instance of RadControl is on a active form

Declaration
protected bool IsParentFormActive { get; }
Property Value
System.Boolean

ItemCapture

Only RadItem should manipulate this property

Declaration
public RadElement ItemCapture { get; set; }
Property Value
RadElement

LastFocusedElement

Gets the RadElement that last had focus before the control lost focus. This property is used internally.

Declaration
public RadElement LastFocusedElement { get; }
Property Value
RadElement

The RadElement that was focused when the control lost focus, used for focus restoration.
Remarks

This property is used internally by the focus management system to restore focus to the appropriate element when the control regains focus. It should not be used directly by application code.

MouseOver

Determines whether the mouse over the owning IComponentTreeHandler instance.

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

Owner

Declaration
protected IComponentTreeHandler Owner { get; }
Property Value
IComponentTreeHandler

OwnerControl

Declaration
protected Control OwnerControl { get; }
Property Value
System.Windows.Forms.Control

SelectedElement

Gets the current selected element (hovered by the mouse).

Declaration
public RadElement SelectedElement { get; }
Property Value
RadElement

Shortcuts

Gets the shortcust collection.

Declaration
public Shortcuts Shortcuts { get; }
Property Value
Shortcuts

ShowItemToolTips

Gets or sets a value indicating whether ToolTips are shown for the RadItem objects contained in the RadControl.

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

ShowScreenTipsBellowControl

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

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

ToolTip

Gets the ToolTip instance used to display element tooltips within the component.

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

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.
Remarks

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.

ToolTipOffsetX

Gets or sets the value of how much the tooltip will be moved on the X coordinate

Declaration
public int ToolTipOffsetX { get; set; }
Property Value
System.Int32

ToolTipOffsetY

Gets or sets the value of how much the tooltip will be moved on the Y coordinate

Declaration
public int ToolTipOffsetY { get; set; }
Property Value
System.Int32

Methods

ActivateKeyTipItem(Keys, String)

Declaration
public void ActivateKeyTipItem(Keys input, string inputString)
Parameters
System.Windows.Forms.Keys input

System.String inputString

ActivateSelectedItem(RadItem)

Declaration
protected virtual bool ActivateSelectedItem(RadItem currentKeyMapItem)
Parameters
RadItem currentKeyMapItem

Returns
System.Boolean

Dispose()

Releases all resources used by the ComponentBehavior instance.

Declaration
public void Dispose()
Implements
System.IDisposable.Dispose()
Remarks

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.

Dispose(Boolean)

Declaration
protected virtual void Dispose(bool disposing)
Parameters
System.Boolean disposing

DisposeAdornerLayer()

Declaration
protected virtual void DisposeAdornerLayer()

DisposeKeyTips()

Clears all resources reserved for the KeyTips functionality

Declaration
protected virtual void DisposeKeyTips()

FindFormInternal(Control)

This method is used internally.

Declaration
public Form FindFormInternal(Control control)
Parameters
System.Windows.Forms.Control control

Returns
System.Windows.Forms.Form

GetActivatedItem(Control, Char)

Declaration
protected RadItem GetActivatedItem(Control control, char charCode)
Parameters
System.Windows.Forms.Control control

System.Char charCode

Returns
RadItem

GetActivatedItem(RadElement, Char)

Declaration
protected RadItem GetActivatedItem(RadElement element, char charCode)
Parameters
RadElement element

System.Char charCode

Returns
RadItem

GetCurrentKeyMap(RadItem)

Declaration
public virtual List<RadItem> GetCurrentKeyMap(RadItem currentKeyMapItem)
Parameters
RadItem currentKeyMapItem

Returns
System.Collections.Generic.List<RadItem>

GetKeyFocusChildren(RadItem)

Declaration
protected virtual List<RadItem> GetKeyFocusChildren(RadItem currentKeyMapItem)
Parameters
RadItem currentKeyMapItem

Returns
System.Collections.Generic.List<RadItem>

GetKeyMapFocus()

Declaration
protected bool GetKeyMapFocus()
Returns
System.Boolean

GetKeyStringRepresentation(Keys)

Declaration
protected virtual string GetKeyStringRepresentation(Keys input)
Parameters
System.Windows.Forms.Keys input

Returns
System.String

GetMnemonicText(String)

Declaration
protected virtual string GetMnemonicText(string text)
Parameters
System.String text

Returns
System.String

GetRootItems()

Declaration
protected virtual List<RadItem> GetRootItems()
Returns
System.Collections.Generic.List<RadItem>

GetThemedChildControlsList(Control, List<Control>)

Declaration
protected virtual void GetThemedChildControlsList(Control control, List<Control> mnemonicList)
Parameters
System.Windows.Forms.Control control

System.Collections.Generic.List<System.Windows.Forms.Control> mnemonicList

GetValidChildControlByMnemonic(List<Control>, Char)

Declaration
protected virtual Control GetValidChildControlByMnemonic(List<Control> mnemonicList, char charCode)
Parameters
System.Collections.Generic.List<System.Windows.Forms.Control> mnemonicList

System.Char charCode

Returns
System.Windows.Forms.Control

HideScreenTip()

Declaration
public void HideScreenTip()

InitializeAdornerLayer()

Declaration
protected virtual void InitializeAdornerLayer()

InitializeKeyMap()

Declaration
protected virtual void InitializeKeyMap()

IsExactMatch(RadItem, String)

Declaration
protected virtual bool IsExactMatch(RadItem item, string keyTipFragment)
Parameters
RadItem item

System.String keyTipFragment

Returns
System.Boolean

IsFocusWithin(RadElement)

Checks is a given element or any of its descendants contain the focus.

Declaration
public bool IsFocusWithin(RadElement element)
Parameters
RadElement element

The element.
Returns
System.Boolean

[true] if the element or any of its children contain focus, [false] otherwise.

IsIndexOfItemKeyTip(RadItem, String)

Declaration
protected virtual int IsIndexOfItemKeyTip(RadItem item, string keyTipFragment)
Parameters
RadItem item

System.String keyTipFragment

Returns
System.Int32

IsPartOfKeyTip(Keys, String)

Declaration
protected virtual bool IsPartOfKeyTip(Keys input, string representation)
Parameters
System.Windows.Forms.Keys input

System.String representation

Returns
System.Boolean

OnEnableKeyTipsChanged()

Declaration
protected virtual void OnEnableKeyTipsChanged()

OnGotFocus(EventArgs)

Handles the event that occurs when the control receives focus, restoring focus to the last focused element.

Declaration
public virtual bool OnGotFocus(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.
Returns
System.Boolean

true if the event is handled; otherwise, false.
Remarks

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.

OnLostFocus(EventArgs)

Handles the event that occurs when the control loses focus, preserving the focus state for later restoration.

Declaration
public virtual bool OnLostFocus(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.
Returns
System.Boolean

true if the event is handled; otherwise, false.
Remarks

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.

ProccessKeyMap(Keys)

This method is used internally.

Declaration
public virtual bool ProccessKeyMap(Keys input)
Parameters
System.Windows.Forms.Keys input

Returns
System.Boolean

ProcessMnemonic(Char)

Declaration
protected bool ProcessMnemonic(char charCode)
Parameters
System.Char charCode

Returns
System.Boolean

ProcessMnemonicChar(Char)

Declaration
protected virtual bool ProcessMnemonicChar(char charCode)
Parameters
System.Char charCode

Returns
System.Boolean

ProcessUnmappedItems(List<RadItem>)

Declaration
protected virtual int ProcessUnmappedItems(List<RadItem> childrenToBeMapped)
Parameters
System.Collections.Generic.List<RadItem> childrenToBeMapped

Returns
System.Int32

ResetKeyMap()

Declaration
protected virtual void ResetKeyMap()

ResetKeyMapInternal()

Declaration
protected virtual void ResetKeyMapInternal()

ReturnKeyMapFocus()

Declaration
protected bool ReturnKeyMapFocus()
Returns
System.Boolean

SetElementValue(RadElement, RadProperty, Object)

Declaration
public void SetElementValue(RadElement element, RadProperty dependencyProperty, object value)
Parameters
RadElement element

RadProperty dependencyProperty

System.Object value

SetInternalKeyMapFocus()

Declaration
protected virtual bool SetInternalKeyMapFocus()
Returns
System.Boolean

SetKeyMap()

Declaration
public virtual bool SetKeyMap()
Returns
System.Boolean

Extension Methods