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

Provides an abstract base class for RadControls that manage collections of RadItem objects, offering item selection, event handling, and collection management capabilities.

RadItemsControl serves as the foundation for controls that work with collections of interactive items such as list boxes, combo boxes, menus, toolbars, and tree views. It provides a unified programming model for item-based controls through the IItemsControl interface.

The class manages item selection state through ItemSelected and ItemDeselected events, coordinates with implementation objects for specialized behavior, and provides infrastructure for item collection management. It delegates specific functionality to implementation classes while maintaining a consistent public interface.

Derived classes include RadListControl, RadComboBox, RadMenu, and other controls that need to manage collections of selectable or interactive items with consistent behavior patterns and event handling throughout the Telerik WinControls framework.

Definition

Namespace:Telerik.WinControls

Assembly:Telerik.WinControls.dll

Syntax:

C#
public abstract class RadItemsControl : RadControl, IDropTarget, ISynchronizeInvoke, IWin32Window, IBindableComponent, IComponent, IDisposable, INotifyPropertyChanged, ISupportInitializeNotification, ISupportInitialize, IComponentTreeHandler, ILayoutHandler, IAnalyticsProvider, IItemsControl

Inheritance: objectMarshalByRefObjectComponentControlScrollableControlRadControlRadItemsControl...

Derived Classes: RadMenu

Implements: IAnalyticsProviderIBindableComponentIComponentIComponentTreeHandlerIDisposableIDropTargetIItemsControlILayoutHandlerINotifyPropertyChangedISupportInitializeISupportInitializeNotificationISynchronizeInvokeIWin32Window...

Inherited Members RadControl.isResizing2RadControl.isDisposing2RadControl.invalidResizeRectRadControl.isAccessibilityRequestedRadControl.Dispose(bool)RadControl.Construct()RadControl.CreateBehavior()RadControl.CreateRootElement()RadControl.CreateChildItems(RadElement)RadControl.InitializeRootElement(RootRadElement)RadControl.LoadElementTree()RadControl.LoadElementTree(Size)RadControl.SetBackColorThemeOverrides()RadControl.ResetBackColorThemeOverrides()RadControl.SetForeColorThemeOverrides()RadControl.ResetForeColorThemeOverrides()RadControl.OnKeyDown(KeyEventArgs)RadControl.OnKeyUp(KeyEventArgs)RadControl.OnPreviewKeyDown(PreviewKeyDownEventArgs)RadControl.OnKeyPress(KeyPressEventArgs)RadControl.OnClick(EventArgs)RadControl.OnDoubleClick(EventArgs)RadControl.OnMouseDown(MouseEventArgs)RadControl.OnMouseUp(MouseEventArgs)RadControl.OnMouseEnter(EventArgs)RadControl.OnMouseLeave(EventArgs)RadControl.OnMouseMove(MouseEventArgs)RadControl.OnMouseHover(EventArgs)RadControl.OnMouseWheel(MouseEventArgs)RadControl.OnMouseCaptureChanged(EventArgs)RadControl.OnLostFocus(EventArgs)RadControl.OnCreateControl()RadControl.OnHandleDestroyed(EventArgs)RadControl.OnParentChanged(EventArgs)RadControl.OnVisibleChanged(EventArgs)RadControl.OnFontChanged(EventArgs)RadControl.OnForeColorChanged(EventArgs)RadControl.OnBackColorChanged(EventArgs)RadControl.OnEnabledChanged(EventArgs)RadControl.OnBindingContextChanged(EventArgs)RadControl.OnLocationChanged(EventArgs)RadControl.OnPaddingChanged(EventArgs)RadControl.OnRightToLeftChanged(EventArgs)RadControl.OnPaint(PaintEventArgs)RadControl.OnLayout(LayoutEventArgs)RadControl.OnAutoSizeChanged(EventArgs)RadControl.WndProc(ref Message)RadControl.OnInvalidated(RadElement)RadControl.OnLoad(Size)RadControl.OnCaptureLosing()RadControl.OnThemeChanged()RadControl.OnToolTipTextNeeded(object, ToolTipTextNeededEventArgs)RadControl.OnScreenTipNeeded(object, ScreenTipNeededEventArgs)RadControl.OnThemeNameChanged(ThemeNameChangedEventArgs)RadControl.ProcessMnemonic(char)RadControl.ProcessFocusRequested(RadElement)RadControl.ProcessCaptureChangeRequested(RadElement, bool)RadControl.ProcessAutoSizeChanged(bool)RadControl.IsInputKey(Keys)RadControl.BeginInit()RadControl.EndInit()RadControl.OnNotifyPropertyChanged(string)RadControl.OnNotifyPropertyChanged(PropertyChangedEventArgs)RadControl.GetPreferredSize(Size)RadControl.SetBoundsCore(int, int, int, int, BoundsSpecified)RadControl.GetRootElementDesiredSize(int, int, int, int)RadControl.OnZoomGesture(ZoomGestureEventArgs)RadControl.OnRotateGesture(RotateGestureEventArgs)RadControl.OnPanGesture(PanGestureEventArgs)RadControl.OnTwoFingerTapGesture(GestureEventArgs)RadControl.OnPressAndTapGesture(PressAndTapGestureEventArgs)RadControl.OnGesture(GestureEventArgs)RadControl.ProcessGesture(Message)RadControl.EnableGesture(GestureType)RadControl.DisableGesture(GestureType)RadControl.Refresh()RadControl.SuspendUpdate()RadControl.ResumeUpdate()RadControl.ResumeUpdate(bool)RadControl.InvokeLayoutCallback(LayoutCallback)RadControl.RegisterHostedControl(RadHostItem)RadControl.UnregisterHostedControl(RadHostItem, bool)RadControl.ResolveStyleGroupForElement(StyleGroup, RadObject)RadControl.GetPlainText()RadControl.ShouldSerializeProperty(RadProperty)RadControl.ShouldSerializeProperty(RadProperty, RadObject)RadControl.ResetProperty(RadProperty, RadObject)RadControl.CanEditElementAtDesignTime(RadElement)RadControl.ProcessCodedUIMessage(ref IPCMessage)RadControl.FindPropertyInChildren(RadControl, IPCMessage)RadControl.ScaleControl(SizeF, BoundsSpecified)RadControl.PerformRadAutoScale(BoundsSpecified?)RadControl.GetMonitorDpiScaleFactor(Control)RadControl.SetRadAutoScale(bool)RadControl.EnableDpiScalingRadControl.EnableRadAutoScaleRadControl.EnableRadFormInitialDpiScalingRadControl.EnableImageDpiScalingRadControl.EnableSvgImagesRadControl.IsLoadedRadControl.ElementTreeRadControl.UseCompatibleTextRenderingDefaultValueRadControl.BehaviorRadControl.RootElementRadControl.PaddingRadControl.ThemeNameRadControl.TextRadControl.EnableThemingRadControl.ThemeClassNameRadControl.ImageListRadControl.ImageScalingSizeRadControl.UseCompatibleTextRenderingRadControl.AutoSizeRadControl.MaximumSizeRadControl.MinimumSizeRadControl.FocusableRadControl.SiteRadControl.CausesValidationRadControl.IsInitializingRadControl.SmallImageListRadControl.SmallImageScalingSizeRadControl.IsDesignModeRadControl.IsDisplayedRadControl.FocusedElementRadControl.AllowShowFocusCuesRadControl.ShowItemToolTipsRadControl.CommandBindingsRadControl.EnableKeyMapRadControl.BackColorRadControl.ForeColorRadControl.FontRadControl.ValidationCancelRadControl.EnableAnalyticsRadControl.AnalyticsNameRadControl.EnableRadAccessibilityObjectsRadControl.EnableCodedUITestsRadControl.EnableCodedUITestsDefaultValueRadControl.EnableUIAutomationRadControl.EnableUIAutomationDefaultValueRadControl.ElementInvalidatedRadControl.ToolTipTextNeededRadControl.ScreenTipNeededRadControl.ThemeNameChangedRadControl.InitializedRadControl.PropertyChangedRadControl.ZoomGestureRadControl.RotateGestureRadControl.PanGestureRadControl.TwoFingerTapGestureRadControl.PressAndTapGesture...

Constructors

Initializes a new instance of the RadItemsControl class.

C#
public RadItemsControl()

The constructor establishes the implementation pattern by creating an items control implementation object and wiring up the necessary event handlers for item selection and deselection events.

Properties

Gets the items considered by the control's selection and navigation implementation. The default implementation uses the same collection as Items.

C#
public virtual RadItemOwnerCollection ActiveItems { get; }

Implements: IItemsControl.ActiveItems

Gets whether this control or one of its child controls currently has focus.

C#
public virtual bool HasKeyboardInput { get; }

Gets the collection of items supplied by the derived control.

C#
public abstract RadItemOwnerCollection Items { get; }

Implements: IItemsControl.Items

Gets or sets whether the RadItemsControl processes the keyboard.

C#
[Browsable(false)]
public virtual bool ProcessKeyboard { get; set; }

Implements: IItemsControl.ProcessKeyboard

Gets or sets whether the rollover items functionality of the RadItemsControl will be allowed.

C#
[Browsable(false)]
public virtual bool RollOverItemSelection { get; set; }

Implements: IItemsControl.RollOverItemSelection

Methods

Calls the base control's dialog-key processing implementation.

C#
protected virtual bool CallBaseProcessDialogKey(Keys keyData)
Parameters:keyDataKeys

The key combination to process.

Returns:

bool

true if the base implementation handles the key.

Invokes the virtual hook for an item-deselection notification.

C#
public void CallOnItemDeselected(ItemSelectedEventArgs args)
Parameters:argsItemSelectedEventArgs

The item that was deselected.

Determines whether the configured item implementation supports navigation with the specified key. The default implementation reports that it does not.

C#
public virtual bool CanNavigate(Keys keyData)
Parameters:keyDataKeys

The key to check.

Returns:

bool

true if the implementation supports navigation with the key; otherwise, false.

Implements: IItemsControl.CanNavigate(Keys)

Determines whether the configured item implementation can handle the specified mnemonic. The default implementation reports that it cannot.

C#
public virtual bool CanProcessMnemonic(char keyData)
Parameters:keyDatachar

The mnemonic character to check.

Returns:

bool

true if the implementation can process the mnemonic; otherwise, false.

Implements: IItemsControl.CanProcessMnemonic(char)

Moves focus to a hosted control when the next item is a RadHostItem; otherwise, focuses this control if focus is within it.

C#
protected virtual void ChangeSelection(RadItem nextItem)
Parameters:nextItemRadItem

The item being selected.

Adds the mnemonic character from each active item's text to the supplied list.

C#
protected virtual void GetChildMnemonicList(ArrayList mnemonicList)
Parameters:mnemonicListArrayList

The list to receive mnemonic characters.

Gets the first active item that is both selectable and visible.

C#
public virtual RadItem GetFirstVisibleItem()
Returns:

RadItem

The first eligible item, or null if none exists.

Implements: IItemsControl.GetFirstVisibleItem()

Returns the selected item as the current input element.

C#
protected override RadElement GetInputElement()
Returns:

RadElement

The selected item, or null when there is no selection.

Overrides: RadControl.GetInputElement()

When overridden in a derived class, creates and returns the implementation object that provides the specific behavior for this items control.

C#
protected virtual IItemsControl GetItemsControlImpl()
Returns:

IItemsControl

An IItemsControl implementation that handles the specific behavior for this control type.

This factory method allows derived classes to specify their own implementation objects while maintaining the common RadItemsControl interface and event handling patterns. The default implementation returns a RadItemsControlImpl instance.

Gets the last active item that is both selectable and visible.

C#
public virtual RadItem GetLastVisibleItem()
Returns:

RadItem

The last eligible item, or null if none exists.

Implements: IItemsControl.GetLastVisibleItem()

Gets the next visible, selectable item in the active collection.

C#
public virtual RadItem GetNextItem(RadItem item, bool forward)
Parameters:itemRadItem

The item to navigate from, or null to start from the first item.

forwardbool

true to search forward; otherwise, search backward.

Returns:

RadItem

The next eligible item, or null if none is found.

Implements: IItemsControl.GetNextItem(RadItem, bool)

When RollOverItemSelection is enabled, navigation wraps at the ends of the collection.

Gets the item currently tracked as selected by the configured item implementation.

C#
public virtual RadItem GetSelectedItem()
Returns:

RadItem

The selected item, or null if there is no selection.

Implements: IItemsControl.GetSelectedItem()

Moves focus to the selected item when the control receives focus.

C#
protected override void OnGotFocus(EventArgs e)
Parameters:eEventArgs

Event data.

Overrides: RadControl.OnGotFocus(EventArgs)

Allows a derived control to handle a key-down message before normal dialog-key processing.

C#
protected virtual bool OnHandleKeyDown(Message m)
Parameters:mMessage

The key-down message.

Returns:

bool

The base implementation returns false.

Provides a subclass hook after the ItemDeselected event is raised.

C#
protected virtual void OnItemDeselected(ItemSelectedEventArgs args)
Parameters:argsItemSelectedEventArgs

The item that was deselected.

Provides a subclass hook after the ItemSelected event is raised.

C#
protected virtual void OnItemSelected(ItemSelectedEventArgs args)
Parameters:argsItemSelectedEventArgs

The item that was selected.

Routes an arrow key to the corresponding directional item-navigation hook.

C#
protected virtual bool ProcessArrowKey(Keys keyCode)
Parameters:keyCodeKeys

The arrow key to process.

Returns:

bool

true if an arrow key was processed; otherwise, false.

Offers command keys to the selected item, then to other active items, before the base control processes them.

C#
protected override bool ProcessCmdKey(ref Message m, Keys keyData)
Parameters:mMessage

The message to process.

keyDataKeys

The key combination associated with the message.

Returns:

bool

true if an item or the base control handles the key.

Overrides: Control.ProcessCmdKey(ref Message, Keys)

Routes dialog keys to the selected item and, when enabled, handles item navigation and tab traversal.

C#
protected override bool ProcessDialogKey(Keys keyData)
Parameters:keyDataKeys

The key combination to process.

Returns:

bool

true if the key was handled; otherwise, delegates to the base control.

Overrides: Control.ProcessDialogKey(Keys)

Selects the next or previous item in collection order for a left or right arrow key.

C#
protected virtual bool ProcessLeftRightArrowKey(bool right)
Parameters:rightbool

true to move forward; otherwise, move backward.

Returns:

bool

The base implementation returns true after attempting the selection.

Allows a derived control to handle tab traversal between its items.

C#
protected virtual bool ProcessTabKey(bool forward)
Parameters:forwardbool

true to traverse forward; otherwise, traverse backward.

Returns:

bool

The base implementation returns false so normal dialog-key processing can continue.

Selects the next or previous item in collection order for an up or down arrow key.

C#
protected virtual bool ProcessUpDownArrowKey(bool down)
Parameters:downbool

true to move forward; otherwise, move backward.

Returns:

bool

The base implementation returns true after attempting the selection.

Handles directed focus traversal through the items when keyboard processing is enabled.

C#
protected override void Select(bool directed, bool forward)
Parameters:directedbool

Whether selection was directed to this control.

forwardbool

true to move forward; otherwise, move backward.

Overrides: Control.Select(bool, bool)

Selects and focuses the first active item that is both selectable and visible.

C#
public virtual RadItem SelectFirstVisibleItem()
Returns:

RadItem

The selected item, or null if none exists.

Implements: IItemsControl.SelectFirstVisibleItem()

Selects an item through the configured implementation.

C#
public virtual void SelectItem(RadItem item)
Parameters:itemRadItem

The item to select, or null to clear the selection.

Implements: IItemsControl.SelectItem(RadItem)

The default implementation raises ItemDeselected for a different previous item before raising ItemSelected for a non-null item.

Selects and focuses the last active item that is both selectable and visible.

C#
public virtual RadItem SelectLastVisibleItem()
Returns:

RadItem

The selected item, or null if none exists.

Implements: IItemsControl.SelectLastVisibleItem()

Selects the next visible, selectable item in the specified direction.

C#
public virtual RadItem SelectNextItem(RadItem item, bool forward)
Parameters:itemRadItem

The item to navigate from.

forwardbool

true to search forward; otherwise, search backward.

Returns:

RadItem

The newly selected item, or null if no eligible item is found.

Implements: IItemsControl.SelectNextItem(RadItem, bool)

This changes the selection but does not itself move keyboard focus to the item.

Events

Occurs when an item becomes deselected in the control.

C#
public event ItemSelectedEventHandler ItemDeselected

Implements: IItemsControl.ItemDeselected

This event is raised whenever an item transitions from a selected to an unselected state, providing notification of deselection changes to enable cleanup operations and user interface state management.

Occurs when an item becomes selected in the control.

C#
public event ItemSelectedEventHandler ItemSelected

Implements: IItemsControl.ItemSelected

This event is raised whenever an item transitions from an unselected to a selected state, providing notification of selection changes to enable responsive user interface updates and business logic execution.