Class RadListControl

Represents a list control that displays data in a list layout similar to the standard ListBox control, providing advanced features such as data binding, virtualization, and custom item rendering.

Inheritance
System.Object
RadControl
RadListControl
ColorListBox
Inherited Members
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.UI.dll

Syntax

[TelerikToolboxCategory("Data Controls")]
[ClassInterface(ClassInterfaceType.AutoDispatch)]
[ComVisible(true)]
public class RadListControl : RadControl, INotifyPropertyChanged, ISupportInitializeNotification, ISupportInitialize, IComponentTreeHandler, ILayoutHandler, IPCHost, IAnalyticsProvider, ISupportRootUIAutomation

Constructors

RadListControl()

Initializes a new instance of the RadListControl class with default settings.

Declaration
public RadListControl()

Fields

CreatingVisualListItemEventKey

Declaration
public static readonly object CreatingVisualListItemEventKey
Field Value
System.Object

ListItemDataBindingEventKey

Declaration
public static readonly object ListItemDataBindingEventKey
Field Value
System.Object

ListItemDataBoundEventKey

Declaration
public static readonly object ListItemDataBoundEventKey
Field Value
System.Object

SelectedIndexChangedEventKey

Declaration
public static readonly object SelectedIndexChangedEventKey
Field Value
System.Object

SelectedIndexChangingEventKey

Declaration
public static readonly object SelectedIndexChangingEventKey
Field Value
System.Object

SelectedValueChangedEventKey

Declaration
public static readonly object SelectedValueChangedEventKey
Field Value
System.Object

SortStyleChangedEventKey

Declaration
public static readonly object SortStyleChangedEventKey
Field Value
System.Object

VisualItemFormattingEventKey

Declaration
public static readonly object VisualItemFormattingEventKey
Field Value
System.Object

Properties

ActiveItem

Gets or sets the active item that receives focus for keyboard navigation in multi-selection modes.

Declaration
public RadListDataItem ActiveItem { get; set; }
Property Value
RadListDataItem

AllowDragDrop

Gets or sets a value indicating whether users can reorder items using drag and drop operations.

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

AutoSizeItems

Gets or sets a value that indicates whether items will be sized according to their content. If this property is true the user can set the Height property of each individual RadListDataItem in the Items collection in order to override the automatic sizing.

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

BackColor

RadListControl consists of multiple visual elements and separate settings are provided to customize their appearance. Current BackColor property might be ignored.

Declaration
public override Color BackColor { get; set; }
Property Value
System.Drawing.Color

Overrides

CaseSensitiveSort

Gets or sets a value indicating whether text case sensitivity is considered during sorting operations.

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

DataMember

Gets or sets the name of the data member to bind to when the DataSource contains multiple tables or lists.

Declaration
public string DataMember { get; set; }
Property Value
System.String

DataSource

Gets or sets the data source that provides the items to be displayed in the RadListControl.

Declaration
public object DataSource { get; set; }
Property Value
System.Object

DefaultSize

Declaration
protected override Size DefaultSize { get; }
Property Value
System.Drawing.Size

DescriptionTextMember

Gets or sets the property name used to extract description text from data items for additional item information display.

Declaration
public string DescriptionTextMember { get; set; }
Property Value
System.String

DisplayMember

Gets or sets the property name used to extract display text from data items for visual representation in the list.

Declaration
public string DisplayMember { get; set; }
Property Value
System.String

EnableAlternatingItemColor

Gets or sets a value indicating whether alternating background colors are applied to list items for improved readability.

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

EnableKineticScrolling

Gets or sets a value indicating whether kinetic scrolling is enabled for smooth touch-based scrolling interactions.

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

EnableUIAutomation

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

Overrides
Implements

Filter

Gets or sets a predicate which filters which items can be visible.

Declaration
public Predicate<RadListDataItem> Filter { get; set; }
Property Value
System.Predicate<RadListDataItem>

FilterExpression

Gets or sets a filter expression string that determines which items are visible in the list based on the specified criteria.

Declaration
public string FilterExpression { get; set; }
Property Value
System.String

FindStringComparer

Gets or sets an implementation of IFindStringComparer used for customizing string comparison behavior in the FindString method.

Declaration
public IFindStringComparer FindStringComparer { get; set; }
Property Value
IFindStringComparer

FitItemsToSize

Gets or sets a value indicating whether items are automatically resized to fit the control's width.

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

ForeColor

RadListControl consists of multiple visual elements and separate settings are provided to customize their appearance. Current ForeColor property might be ignored.

Declaration
public override Color ForeColor { get; set; }
Property Value
System.Drawing.Color

Overrides

FormatString

Gets or sets a format string which will be used for visual formatting of the items text.

Declaration
public string FormatString { get; set; }
Property Value
System.String

FormattingEnabled

Gets or sets a value that indicates whether the FormatString and FormatInfo properties will be used to format the items text. Setting this property to false may improve performance.

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

IsFilterActive

Gets a value indicating whether any filtering is currently active, either through a Filter delegate or FilterExpression.

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

ItemHeight

Gets or sets the height of individual list items in pixels.

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

Items

Gets the collection of data items contained in the RadListControl. Items cannot be modified in data bound mode.

Declaration
public RadListDataItemCollection Items { get; }
Property Value
RadListDataItemCollection

ItemTextComparisonMode

Gets or sets the text comparison mode that determines whether the FindString method searches using user-specified text or data-bound text from the DisplayMember.

Declaration
public ItemTextComparisonMode ItemTextComparisonMode { get; set; }
Property Value
ItemTextComparisonMode

KeyboardSearchEnabled

Gets or sets a value indicating whether users can search for items by typing characters while the RadListControl has focus.

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

KeyboardSearchResetInterval

Gets or sets the time interval in milliseconds that the user must wait before the keyboard search functionality is reset.

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

ListElement

Gets the main element that provides the list functionality and serves as the core component of the RadListControl.

Declaration
public RadListElement ListElement { get; set; }
Property Value
RadListElement

ScrollMode

Gets or set the scroll mode.

Declaration
public ItemScrollerScrollModes ScrollMode { get; set; }
Property Value
ItemScrollerScrollModes

SelectedIndex

Gets or sets the currently selected index.

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

SelectedItem

Gets or sets the currently selected item.

Declaration
public RadListDataItem SelectedItem { get; set; }
Property Value
RadListDataItem

SelectedItems

Gets a read-only collection of the currently selected items in the RadListControl.

Declaration
public IReadOnlyCollection<RadListDataItem> SelectedItems { get; }
Property Value
IReadOnlyCollection<RadListDataItem>

SelectedValue

Gets or sets the value of the currently selected item based on the ValueMember property.

Declaration
public object SelectedValue { get; set; }
Property Value
System.Object

SelectionMode

Gets or sets the selection mode that determines how items can be selected in the RadListControl.

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

SortStyle

Gets or sets the sorting behavior applied to the list items.

Declaration
public SortStyle SortStyle { get; set; }
Property Value
SortStyle

SuspendItemsChangeEvents

Gets or sets a value indicating whether the ItemsChanging and ItemsChanged events are temporarily suspended from firing.

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

SuspendSelectionEvents

Gets or sets a value that determines whether to stop the selection events from firing. These are SelectedIndexChanged, SelectedIndexChanging and SelectedValueChanged.

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

Text

This property is not relevant for this class.

Declaration
public override string Text { get; set; }
Property Value
System.String

Overrides

ValueMember

Gets or sets the property name used to extract values from data items, which will be accessible through the Value property of each RadListDataItem.

Declaration
public string ValueMember { get; set; }
Property Value
System.String

Methods

BeginUpdate()

Suspends internal notifications and processing to improve performance during bulk operations. This method is cumulative, requiring matching calls to EndUpdate().

Declaration
public void BeginUpdate()

CanEditElementAtDesignTime(RadElement)

Declaration
protected override bool CanEditElementAtDesignTime(RadElement element)
Parameters
RadElement element

Returns
System.Boolean

Overrides

ClearMeasuredSize()

Declaration
protected virtual void ClearMeasuredSize()

CreateAccessibilityInstance()

Declaration
protected override AccessibleObject CreateAccessibilityInstance()
Returns
System.Windows.Forms.AccessibleObject

CreateChildItems(RadElement)

Creates the child elements for the RadListControl.

Declaration
protected override void CreateChildItems(RadElement parent)
Parameters
RadElement parent

The parent element that will contain the child elements.
Overrides

CreateListElement()

Creates and returns a new instance of the RadListElement that provides the core list functionality.

Declaration
protected virtual RadListElement CreateListElement()
Returns
RadListElement

A new RadListElement instance.

DeferRefresh()

Creates a disposable object that defers refresh operations until disposed, allowing multiple changes to be batched together.

Declaration
public virtual IDisposable DeferRefresh()
Returns
System.IDisposable

An System.IDisposable object that resumes refresh operations when disposed.

Dispose(Boolean)

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

Overrides

EndInit()

Declaration
public override void EndInit()
Overrides

EndUpdate()

Resumes internal notifications and processing previously suspended by BeginUpdate().

Declaration
public void EndUpdate()

FindItemExact(String, Boolean)

Declaration
public RadListDataItem FindItemExact(string text, bool caseSensitive)
Parameters
System.String text

System.Boolean caseSensitive

Returns
RadListDataItem

FindString(String)

Searches for an item that matches the specified string using the configured FindStringComparer, starting from the beginning of the list.

Declaration
public int FindString(string s)
Parameters
System.String s

The string to search for.
Returns
System.Int32

The index of the first matching item, or -1 if no match is found.

FindString(String, Int32)

Searches for an item that matches the specified string using the configured FindStringComparer, starting from the specified index.

Declaration
public int FindString(string s, int startIndex)
Parameters
System.String s

The string to search for.
System.Int32 startIndex

The index to start searching from.
Returns
System.Int32

The index of the first matching item, or -1 if no match is found.

FindStringExact(String)

Searches for an item with text that exactly matches the specified string, starting from the beginning of the list.

Declaration
public int FindStringExact(string s)
Parameters
System.String s

The string to match exactly.
Returns
System.Int32

The index of the matching item, or -1 if no exact match is found.

FindStringExact(String, Int32)

Searches for an item with text that exactly matches the specified string, starting from the specified index.

Declaration
public int FindStringExact(string s, int startIndex)
Parameters
System.String s

The string to match exactly.
System.Int32 startIndex

The index to start searching from.
Returns
System.Int32

The index of the matching item, or -1 if no exact match is found.

FindStringNonWrapping(String)

Searches for an item in the same manner as FindString() but does not start from the beginning when the end of the Items collection is reached.

Declaration
public int FindStringNonWrapping(string s)
Parameters
System.String s

The string that will be used to search for an item.
Returns
System.Int32

The index of the found item or -1 if no item is found.

FindStringNonWrapping(String, Int32)

Searches for an item in the same manner as FindString() but does not start from the beginning when the end of the Items collection is reached.

Declaration
public int FindStringNonWrapping(string s, int startIndex)
Parameters
System.String s

The string that will be used to search for an item.
System.Int32 startIndex

The index from which to start searching.
Returns
System.Int32

The index of the found item or -1 if no item is found.

HandleEndKey()

Declaration
protected virtual void HandleEndKey()

HandleHomeKey()

Declaration
protected virtual void HandleHomeKey()

HandlePageDownKey()

Declaration
protected virtual void HandlePageDownKey()

HandlePageUpKey()

Declaration
protected virtual void HandlePageUpKey()

IsInputChar(Char)

Declaration
protected override bool IsInputChar(char charCode)
Parameters
System.Char charCode

Returns
System.Boolean

IsInputKey(Keys)

Declaration
protected override bool IsInputKey(Keys keyData)
Parameters
System.Windows.Forms.Keys keyData

Returns
System.Boolean

Overrides

OnCreatingVisualItem(Object, CreatingVisualListItemEventArgs)

Declaration
protected virtual void OnCreatingVisualItem(object sender, CreatingVisualListItemEventArgs args)
Parameters
System.Object sender

CreatingVisualListItemEventArgs args

OnDataBindingComplete(Object, ListBindingCompleteEventArgs)

Raises the DataBindingComplete event.

Declaration
protected virtual void OnDataBindingComplete(object sender, ListBindingCompleteEventArgs e)
Parameters
System.Object sender

ListBindingCompleteEventArgs e

An ListBindingCompleteEventArgs instance that contains the event data.
See Also

OnEnabledChanged(EventArgs)

Declaration
protected override void OnEnabledChanged(EventArgs e)
Parameters
System.EventArgs e

Overrides

OnGotFocus(EventArgs)

Declaration
protected override void OnGotFocus(EventArgs e)
Parameters
System.EventArgs e

Overrides

OnItemDataBinding(Object, ListItemDataBindingEventArgs)

Declaration
protected virtual void OnItemDataBinding(object sender, ListItemDataBindingEventArgs args)
Parameters
System.Object sender

ListItemDataBindingEventArgs args

OnItemDataBound(Object, ListItemDataBoundEventArgs)

Declaration
protected virtual void OnItemDataBound(object sender, ListItemDataBoundEventArgs args)
Parameters
System.Object sender

ListItemDataBoundEventArgs args

OnKeyDown(KeyEventArgs)

Declaration
protected override void OnKeyDown(KeyEventArgs e)
Parameters
System.Windows.Forms.KeyEventArgs e

Overrides

OnLoad(Size)

Declaration
protected override void OnLoad(Size desiredSize)
Parameters
System.Drawing.Size desiredSize

Overrides

OnMouseDown(MouseEventArgs)

Declaration
protected override void OnMouseDown(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

Overrides

OnMouseMove(MouseEventArgs)

Declaration
protected override void OnMouseMove(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

Overrides

OnMouseUp(MouseEventArgs)

Declaration
protected override void OnMouseUp(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

Overrides

OnMouseWheel(MouseEventArgs)

Declaration
protected override void OnMouseWheel(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

Overrides

OnSelectedIndexChanged(Object, Int32)

Declaration
protected virtual void OnSelectedIndexChanged(object sender, int newIndex)
Parameters
System.Object sender

System.Int32 newIndex

OnSelectedIndexChanging(Object, Int32)

Declaration
protected virtual bool OnSelectedIndexChanging(object sender, int newIndex)
Parameters
System.Object sender

System.Int32 newIndex

Returns
System.Boolean

OnSelectedValueChanged(Object, Int32, Object, Object)

Declaration
protected virtual void OnSelectedValueChanged(object sender, int newIndex, object newValue, object oldValue)
Parameters
System.Object sender

System.Int32 newIndex

System.Object newValue

System.Object oldValue

OnSortStyleChanged(Object, SortStyleChangedEventArgs)

Declaration
protected virtual void OnSortStyleChanged(object sender, SortStyleChangedEventArgs args)
Parameters
System.Object sender

SortStyleChangedEventArgs args

OnVisualItemFormatting(Object, VisualItemFormattingEventArgs)

Declaration
protected virtual void OnVisualItemFormatting(object sender, VisualItemFormattingEventArgs args)
Parameters
System.Object sender

VisualItemFormattingEventArgs args

ProcessCodedUIMessage(ref IPCMessage)

Declaration
protected override void ProcessCodedUIMessage(ref IPCMessage request)
Parameters
IPCMessage request

Overrides

Rebind()

Forces re-evaluation of the current data source (if any).

Declaration
public void Rebind()

ScrollByPage(Int32)

Scrolls the view by the specified number of pages.

Declaration
public void ScrollByPage(int pageCount)
Parameters
System.Int32 pageCount

The number of pages to scroll. Positive values scroll down, negative values scroll up.

ScrollToItem(RadListDataItem)

Scrolls the view to make the specified item visible, positioning it appropriately within the visible area.

Declaration
public void ScrollToItem(RadListDataItem item)
Parameters
RadListDataItem item

The RadListDataItem to scroll to.

SelectAll()

Selects all items in the list if the current SelectionMode allows multiple selection.

Declaration
public void SelectAll()
Exceptions
System.InvalidOperationException

Thrown when SelectionMode is One or None.

SelectRange(Int32, Int32)

Clears current selection and selects all items within the specified index range.

Declaration
public void SelectRange(int startIndex, int endIndex)
Parameters
System.Int32 startIndex

The starting index of the range to select.
System.Int32 endIndex

The ending index of the range to select (inclusive).

UnwireEvents()

Unsubscribes from the relevant events of the underlying RadListElement.

Declaration
protected virtual void UnwireEvents()

WireEvents()

Subscribes to the relevant events of the underlying RadListElement.

Declaration
protected virtual void WireEvents()

WndProc(ref Message)

Declaration
protected override void WndProc(ref Message m)
Parameters
System.Windows.Forms.Message m

Overrides

Events

CreatingVisualListItem

Occurs when custom visual items need to be created, allowing users to provide custom visual representations for list items.

Declaration
public event CreatingVisualListItemEventHandler CreatingVisualListItem
Event Type
CreatingVisualListItemEventHandler

DataBindingComplete

Fires after data binding operation has finished.

Declaration
public event ListBindingCompleteEventHandler DataBindingComplete
Event Type
ListBindingCompleteEventHandler

See Also

ItemDataBinding

Occurs before a RadListDataItem is data bound, allowing customization of the data binding process and providing custom item instances.

Declaration
public event ListItemDataBindingEventHandler ItemDataBinding
Event Type
ListItemDataBindingEventHandler

ItemDataBound

Occurs after a RadListDataItem has been data bound, providing an opportunity to modify the bound item.

Declaration
public event ListItemDataBoundEventHandler ItemDataBound
Event Type
ListItemDataBoundEventHandler

SelectedIndexChanged

This event fires when the selected index property changes.

Declaration
public event PositionChangedEventHandler SelectedIndexChanged
Event Type
PositionChangedEventHandler

SelectedIndexChanging

This event fires before SelectedIndex changes. This event allows the operation to be cancelled.

Declaration
public event PositionChangingEventHandler SelectedIndexChanging
Event Type
PositionChangingEventHandler

SelectedItemsChanged

Occurs when the SelectedItems collection changes due to selection modifications.

Declaration
public event NotifyCollectionChangedEventHandler SelectedItemsChanged
Event Type
NotifyCollectionChangedEventHandler

SelectedItemsChanging

This event fires before the SelectedItems collection changes.

Declaration
public event NotifyCollectionChangingEventHandler SelectedItemsChanging
Event Type
NotifyCollectionChangingEventHandler

SelectedValueChanged

This event fires only if the SelectedValue has really changed. For example it will not fire if the previously selected item has the same value as the newly selected item.

Declaration
public event EventHandler SelectedValueChanged
Event Type
System.EventHandler

SortStyleChanged

Occurs when the SortStyle property value changes.

Declaration
public event SortStyleChangedEventHandler SortStyleChanged
Event Type
SortStyleChangedEventHandler

VisualItemFormatting

Occurs when visual item formatting is needed, allowing customization of the appearance of visible list items.

Declaration
public event VisualListItemFormattingEventHandler VisualItemFormatting
Event Type
VisualListItemFormattingEventHandler

Explicit Interface Implementations

ISupportRootUIAutomation.DisposeUIAutomationProvider()

Creates the UI Automation provider for this control.

Declaration
void ISupportRootUIAutomation.DisposeUIAutomationProvider()
Implements

ISupportRootUIAutomation.InitializeUIAutomationProvider()

Clears the UI Automation provider for this control.

Declaration
void ISupportRootUIAutomation.InitializeUIAutomationProvider()
Implements

ISupportRootUIAutomation.RootUIAutomationManager

Gets the UI Automation Manager.

Declaration
IRootUIAutomationManager ISupportRootUIAutomation.RootUIAutomationManager { get; }
Returns
IRootUIAutomationManager

Implements

ISupportRootUIAutomation.UIAutomationProvider

Gets the UI Automation Provider.

Declaration
IRadRawElementProviderFragmentRoot ISupportRootUIAutomation.UIAutomationProvider { get; }
Returns
IRadRawElementProviderFragmentRoot

Implements

Extension Methods