New to Telerik UI for WinForms? Start a free 30-day trial

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:

C#
public class ComponentBehavior : IDisposable

Inheritance: objectComponentBehavior

Derived Classes: ComponentInputBehavior

Implements: IDisposable

Constructors

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

C#
public ComponentBehavior(IComponentTreeHandler owner)
Parameters:ownerIComponentTreeHandler

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.

C#
protected bool ItemCaptureState

Properties

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

C#
public virtual bool AllowShowFocusCues { get; set; }

Gets the fill repository used to cache bitmaps shared by the component's drawing primitives.

C#
public FillRepository BitmapRepository { get; }

Gets the input bindings used to associate keyboard gestures with commands.

C#
[TypeConverter(typeof(ExpandableObjectConverter))]
public InputBindingsCollection CommandBindings { get; }

Gets the default tooltip visibility used when input behavior is initialized.

C#
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.

C#
[Browsable(true)]
public bool EnableKeyMap { get; set; }

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

C#
[Browsable(false)]
public RadElement FocusedElement { get; set; }
Property Value:

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

Gets whether this instance of RadControl is on a active form

C#
protected bool IsParentFormActive { get; }

Determines whether the mouse over the owning IComponentTreeHandler instance.

C#
public bool MouseOver { get; }

Gets the component-tree handler whose behavior is managed by this instance.

C#
protected IComponentTreeHandler Owner { get; }

Gets the Windows Forms control that hosts the Telerik element tree.

C#
[Browsable(false)]
protected Control OwnerControl { get; }

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

C#
[Browsable(false)]
public RadElement SelectedElement { get; }

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

C#
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

C#
public bool ShowScreenTipsBellowControl { get; set; }

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

C#
public ToolTip ToolTip { get; }
Property Value:

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

C#
public int ToolTipOffsetX { get; set; }

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

C#
public int ToolTipOffsetY { get; set; }

Methods

Performs the action associated with a completed key tip.

C#
protected virtual bool ActivateSelectedItem(RadItem currentKeyMapItem)
Parameters:currentKeyMapItemRadItem

The item activated by its key tip.

Returns:

bool

The base implementation returns true without performing an action.

Releases all resources used by the ComponentBehavior instance.

C#
public void Dispose()

Implements: IDisposable.Dispose()

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.

C#
protected virtual void Dispose(bool disposing)
Parameters:disposingbool

true to release managed resources; otherwise, release only unmanaged resources.

Override this method to release resources owned by a derived behavior, and call the base implementation.

Removes and disposes the adorner layer used for key-tip overlays.

C#
protected virtual void DisposeAdornerLayer()

Clears all resources reserved for the KeyTips functionality

C#
protected virtual void DisposeKeyTips()

Finds the first eligible item with the specified mnemonic in a control's element tree.

C#
protected RadItem GetActivatedItem(Control control, char charCode)
Parameters:controlControl

The control whose element tree is searched.

charCodechar

The mnemonic character to match.

Returns:

RadItem

The first enabled, visible item whose text contains the mnemonic, or null if none is found.

Checks whether an element is an enabled, visible item whose text contains the specified mnemonic.

C#
protected RadItem GetActivatedItem(RadElement element, char charCode)
Parameters:elementRadElement

The element to check.

charCodechar

The mnemonic character to match.

Returns:

RadItem

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.

C#
public virtual List<RadItem> GetCurrentKeyMap(RadItem currentKeyMapItem)
Parameters:currentKeyMapItemRadItem

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.

C#
protected virtual List<RadItem> GetKeyFocusChildren(RadItem currentKeyMapItem)
Parameters:currentKeyMapItemRadItem

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.

Saves the native window that currently has focus for later restoration after key-tip navigation.

C#
protected bool GetKeyMapFocus()
Returns:

bool

The base implementation returns true after saving the focus handle.

Converts a virtual key into its uppercase, unshifted character representation.

C#
protected virtual string GetKeyStringRepresentation(Keys input)
Parameters:inputKeys

The key to convert.

Returns:

string

The character representation, or null when the key does not map to a character.

Formats a mnemonic found in text as an Alt-key hint.

C#
protected virtual string GetMnemonicText(string text)
Parameters:textstring

The text from which to extract a mnemonic.

Returns:

string

A string such as Alt+F, or null if the text has no mnemonic.

Provides the top-level items shown when key-tip navigation begins.

C#
protected virtual List<RadItem> GetRootItems()
Returns:

List<RadItem>

The base implementation returns null; derived behaviors can supply the root items.

Adds themed child controls that can process mnemonics to the search list.

C#
protected virtual void GetThemedChildControlsList(Control control, List<Control> mnemonicList)
Parameters:controlControl

The control whose child controls are inspected.

mnemonicListList<Control>

The list to receive eligible child controls.

C#
protected virtual Control GetValidChildControlByMnemonic(List<Control> mnemonicList, char charCode)
Parameters:mnemonicListList<Control>charCodecharReturns:

Control

Hides the screen tip currently displayed by this behavior.

C#
public void HideScreenTip()

Creates or raises the adorner layer used to display key-tip overlays.

C#
protected virtual void InitializeAdornerLayer()

Enters key-tip mode, saving the current cursor and focus before clearing the active key-tip path.

C#
protected virtual void InitializeKeyMap()

Determines whether an item's explicit or automatic key tip exactly matches the supplied fragment.

C#
protected virtual bool IsExactMatch(RadItem item, string keyTipFragment)
Parameters:itemRadItem

The item whose key tip is checked.

keyTipFragmentstring

The fragment to compare.

Returns:

bool

true when the key tip and fragment match; otherwise, false.

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

C#
public bool IsFocusWithin(RadElement element)
Parameters:elementRadElement

The element.

Returns:

bool

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

C#
protected virtual int IsIndexOfItemKeyTip(RadItem item, string keyTipFragment)
Parameters:itemRadItem

The item whose key tip is checked.

keyTipFragmentstring

The fragment to find.

Returns:

int

The fragment's last index in the key tip, or -1 when it is not found.

Extends the current key-tip path when the input matches a child key tip, selecting an item on an exact match.

C#
protected virtual bool IsPartOfKeyTip(Keys input, string representation)
Parameters:inputKeys

The key pressed by the user.

representationstring

The character representation of the key.

Returns:

bool

true when the input is a valid prefix or completes a key tip.

Called when EnableKeyTips changes so derived behaviors can update key-tip resources.

C#
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.

C#
public virtual bool OnGotFocus(EventArgs e)
Parameters:eEventArgs

An EventArgs that contains the event data.

Returns:

bool

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.

C#
public virtual bool OnLostFocus(EventArgs e)
Parameters:eEventArgs

An EventArgs that contains the event data.

Returns:

bool

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.

Processes an Alt-mnemonic by focusing the first matching item in the themed child controls.

C#
protected bool ProcessMnemonic(char charCode)
Parameters:charCodechar

The mnemonic character to process.

Returns:

bool

true if the matching item's mnemonic handler accepts the character; otherwise, false.

C#
protected virtual bool ProcessMnemonicChar(char charCode)
Parameters:charCodecharReturns:

bool

Assigns sequential numeric key tips to child items that have neither an explicit nor an automatic key tip.

C#
protected virtual int ProcessUnmappedItems(List<RadItem> childrenToBeMapped)
Parameters:childrenToBeMappedList<RadItem>

The child items participating in the current key-tip level.

Returns:

int

The next automatic key-tip number after the assignments.

Exits key-tip mode, clears its active path, and restores the cursor and previously focused window.

C#
protected virtual void ResetKeyMap()

Clears key-tip mode and its active path without restoring the previously focused window.

C#
protected virtual void ResetKeyMapInternal()

Restores focus to the native window saved before key-tip navigation, when a handle was saved.

C#
protected bool ReturnKeyMapFocus()
Returns:

bool

The base implementation returns true.

Sets a RadProperty value on the control thread, posting the update when called from another thread.

C#
public void SetElementValue(RadElement element, RadProperty dependencyProperty, object value)
Parameters:elementRadElement

The element whose property is updated.

dependencyPropertyRadProperty

The property to set.

valueobject

The new property value.

Allows a derived behavior to move focus to an internal control while key-tip mode is active.

C#
protected virtual bool SetInternalKeyMapFocus()
Returns:

bool

The base implementation returns true without changing focus.

Enters key-tip mode, or exits it if key-tip mode is already active.

C#
public virtual bool SetKeyMap()
Returns:

bool

The base implementation returns true after toggling the mode.