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.
Definition
Namespace:Telerik.WinControls.UI
Assembly:Telerik.WinControls.UI.dll
Syntax:
[TelerikToolboxCategory("Data Controls")]
[ComplexBindingProperties("DataSource", "ValueMember")]
[LookupBindingProperties("DataSource", "DisplayMember", "ValueMember", "SelectedValue")]
[ClassInterface(ClassInterfaceType.AutoDispatch)]
[ComVisible(true)]
public class RadListControl : RadControl, IDropTarget, ISynchronizeInvoke, IWin32Window, IBindableComponent, IComponent, IDisposable, INotifyPropertyChanged, ISupportInitializeNotification, ISupportInitialize, IComponentTreeHandler, ILayoutHandler, IAnalyticsProvider, ISupportRootUIAutomation
Inheritance: objectMarshalByRefObjectComponentControlScrollableControlRadControlRadListControl...
Implements:
Inherited Members
Constructors
Initializes a new instance of the RadListControl class with default settings.
public RadListControl()
Fields
Identifies handlers registered for the CreatingVisualListItem event.
public static readonly object CreatingVisualListItemEventKey
Identifies handlers registered for the ListItemDataBinding event.
public static readonly object ListItemDataBindingEventKey
Identifies handlers registered for the ListItemDataBound event.
public static readonly object ListItemDataBoundEventKey
Identifies handlers registered for the SelectedIndexChanged event in the control's event list.
public static readonly object SelectedIndexChangedEventKey
Identifies handlers registered for the cancelable SelectedIndexChanging event.
public static readonly object SelectedIndexChangingEventKey
Identifies handlers registered for the SelectedValueChanged event.
public static readonly object SelectedValueChangedEventKey
Identifies handlers registered for the SortStyleChanged event.
public static readonly object SortStyleChangedEventKey
Identifies handlers registered for the VisualItemFormatting event.
public static readonly object VisualItemFormattingEventKey
Properties
Gets or sets the active item that receives focus for keyboard navigation in multi-selection modes.
[Browsable(false)]
public RadListDataItem ActiveItem { get; set; }
Gets or sets a value indicating whether users can reorder items using drag and drop operations.
[Browsable(true)]
public bool AllowDragDrop { get; set; }
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.
[Browsable(true)]
public bool AutoSizeItems { get; set; }
Gets or sets a value indicating whether text case sensitivity is considered during sorting operations.
[Browsable(true)]
public bool CaseSensitiveSort { get; set; }
Gets or sets the name of the data member to bind to when the DataSource contains multiple tables or lists.
[Browsable(true)]
public string DataMember { get; set; }
Gets or sets the data source that provides the items to be displayed in the RadListControl.
[Browsable(true)]
public object DataSource { get; set; }
Gets the default control size used when no size has been specified.
protected override Size DefaultSize { get; }
A size of 120 by 95 pixels.
Overrides:
Gets or sets the property name used to extract description text from data items for additional item information display.
[Browsable(true)]
public string DescriptionTextMember { get; set; }
Gets or sets the property name used to extract display text from data items for visual representation in the list.
[TypeConverter("System.Windows.Forms.Design.DataMemberFieldConverter, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")]
[Browsable(true)]
public string DisplayMember { get; set; }
Gets or sets a value indicating whether alternating background colors are applied to list items for improved readability.
[Browsable(true)]
public virtual bool EnableAlternatingItemColor { get; set; }
Gets or sets a value indicating whether kinetic scrolling is enabled for smooth touch-based scrolling interactions.
[Browsable(true)]
public bool EnableKineticScrolling { get; set; }
Gets or sets whether UI Automation is enabled for the control. Changing the value notifies the UI Automation manager.
public override bool EnableUIAutomation { get; set; }
Overrides:
Implements:
Gets or sets a predicate which filters which items can be visible.
[Browsable(false)]
public Predicate<RadListDataItem> Filter { get; set; }
Gets or sets a filter expression string that determines which items are visible in the list based on the specified criteria.
[Browsable(true)]
public string FilterExpression { get; set; }
Gets or sets an implementation of IFindStringComparer used for customizing string comparison behavior in the FindString method.
[Browsable(false)]
public IFindStringComparer FindStringComparer { get; set; }
Gets or sets a value indicating whether items are automatically resized to fit the control's width.
public bool FitItemsToSize { get; set; }
Gets or sets a format string which will be used for visual formatting of the items text.
[Browsable(true)]
public string FormatString { get; set; }
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.
[Browsable(true)]
public bool FormattingEnabled { get; set; }
Gets a value indicating whether any filtering is currently active, either through a Filter delegate or FilterExpression.
[Browsable(false)]
public bool IsFilterActive { get; }
Gets or sets the height of individual list items in pixels.
[Browsable(true)]
public int ItemHeight { get; set; }
Gets the collection of data items contained in the RadListControl. Items cannot be modified in data bound mode.
[Browsable(true)]
public RadListDataItemCollection Items { get; }
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.
[Browsable(false)]
public ItemTextComparisonMode ItemTextComparisonMode { get; set; }
Gets or sets a value indicating whether users can search for items by typing characters while the RadListControl has focus.
[Browsable(true)]
public bool KeyboardSearchEnabled { get; set; }
Gets or sets the time interval in milliseconds that the user must wait before the keyboard search functionality is reset.
[Browsable(true)]
public int KeyboardSearchResetInterval { get; set; }
Gets the main element that provides the list functionality and serves as the core component of the RadListControl.
[Browsable(false)]
public RadListElement ListElement { get; set; }
Gets or set the scroll mode.
[Browsable(true)]
public ItemScrollerScrollModes ScrollMode { get; set; }
Gets or sets the currently selected index.
[Browsable(false)]
public int SelectedIndex { get; set; }
Gets or sets the currently selected item.
[Browsable(false)]
[Bindable(true)]
public RadListDataItem SelectedItem { get; set; }
Gets a read-only collection of the currently selected items in the RadListControl.
[Browsable(false)]
public IReadOnlyCollection<RadListDataItem> SelectedItems { get; }
Gets or sets the value of the currently selected item based on the ValueMember property.
[Browsable(false)]
[Bindable(true)]
public object SelectedValue { get; set; }
Gets or sets the selection mode that determines how items can be selected in the RadListControl.
[Browsable(true)]
public SelectionMode SelectionMode { get; set; }
Gets or sets the sorting behavior applied to the list items.
[Browsable(true)]
public SortStyle SortStyle { get; set; }
Gets or sets a value indicating whether the ItemsChanging and ItemsChanged events are temporarily suspended from firing.
[Browsable(false)]
public bool SuspendItemsChangeEvents { get; set; }
Gets or sets a value that determines whether to stop the selection events from firing. These are SelectedIndexChanged, SelectedIndexChanging and SelectedValueChanged.
[Browsable(false)]
public bool SuspendSelectionEvents { get; set; }
Gets or sets the property name used to extract values from data items, which will be accessible through the Value property of each RadListDataItem.
[Browsable(true)]
public string ValueMember { get; set; }
Methods
Suspends internal notifications and processing to improve performance during bulk operations. This method is cumulative, requiring matching calls to EndUpdate().
public void BeginUpdate()
Prevents list visual items from being edited directly in the designer.
protected override bool CanEditElementAtDesignTime(RadElement element)
The element the designer is attempting to edit.
Returns:false for a RadListVisualItem; otherwise, the base implementation's result.
Overrides:
Clears cached measured sizes so list items are measured again during layout.
protected virtual void ClearMeasuredSize()
Creates the list's accessible object when Rad accessibility is enabled, otherwise uses the base implementation.
protected override AccessibleObject CreateAccessibilityInstance()
The accessible object for this control.
Overrides:
Creates the child elements for the RadListControl.
protected override void CreateChildItems(RadElement parent)
The parent element that will contain the child elements.
Overrides:
Creates and returns a new instance of the RadListElement that provides the core list functionality.
Creates a disposable object that defers refresh operations until disposed, allowing multiple changes to be batched together.
public virtual IDisposable DeferRefresh()
An IDisposable object that resumes refresh operations when disposed.
Releases the UI Automation provider and disconnects from the list element before disposing the control.
protected override void Dispose(bool disposing)
true to release managed and unmanaged resources; false to release only unmanaged resources.
Overrides:
Completes initialization and synchronizes items already marked selected with the list element's selection collection.
public override void EndInit()
Overrides:
Resumes internal notifications and processing previously suspended by BeginUpdate().
public void EndUpdate()
Searches for an item that matches the specified string using the configured FindStringComparer, starting from the specified index.
Searches for an item that matches the specified string using the configured FindStringComparer, starting from the beginning of the list.
Searches for an item with text that exactly matches the specified string, starting from the specified index.
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.
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.
Selects the last item in the current item sequence.
protected virtual void HandleEndKey()
Selects the first item in the current item sequence.
protected virtual void HandleHomeKey()
Scrolls the list down by one page.
protected virtual void HandlePageDownKey()
Scrolls the list up by one page.
protected virtual void HandlePageUpKey()
Treats letters and digits as input characters so they do not activate mnemonics.
Raises the event that allows handlers to replace the visual item created for a data item.
protected virtual void OnCreatingVisualItem(object sender, CreatingVisualListItemEventArgs args)
The list element creating the visual item.
argsCreatingVisualListItemEventArgsThe event data containing the data item and replaceable visual item.
Raises the DataBindingComplete event.
protected virtual void OnDataBindingComplete(object sender, ListBindingCompleteEventArgs e)
An ListBindingCompleteEventArgs instance that contains the event data.
Notifies the UI Automation provider when the control's enabled state changes.
protected override void OnEnabledChanged(EventArgs e)
The event data.
Overrides:
Focuses the list element and raises a UI Automation focus event when UI Automation requests are enabled.
protected override void OnGotFocus(EventArgs e)
The focus event data.
Overrides:
Raises the event that lets handlers supply a custom data item before a bound row is initialized.
protected virtual void OnItemDataBinding(object sender, ListItemDataBindingEventArgs args)
The list element processing the bound row.
argsListItemDataBindingEventArgsThe event data, including the optional replacement item.
Raises the event after a data item has been associated with a bound data record.
protected virtual void OnItemDataBound(object sender, ListItemDataBoundEventArgs args)
The list element that completed binding the row.
argsListItemDataBoundEventArgsThe event data containing the bound item.
Routes Page Up, Page Down, Home, and End keys to the list's navigation handlers.
protected override void OnKeyDown(KeyEventArgs e)
The key event data.
Overrides:
Enables pan gestures after the control has loaded.
protected override void OnLoad(Size desiredSize)
The size requested for the loaded control.
Overrides:
Gives the list element first opportunity to process a mouse-down event before calling the base implementation.
protected override void OnMouseDown(MouseEventArgs e)
The mouse event data.
Overrides:
Gives the list element first opportunity to process a mouse-move event before calling the base implementation.
protected override void OnMouseMove(MouseEventArgs e)
The mouse event data.
Overrides:
Gives the list element first opportunity to process a mouse-up event before calling the base implementation.
protected override void OnMouseUp(MouseEventArgs e)
The mouse event data.
Overrides:
Forwards the wheel delta to the list element and marks handled mouse events as handled.
protected override void OnMouseWheel(MouseEventArgs e)
The mouse-wheel event data.
Overrides:
Raises the cancelable selection-changing event and reports whether the change was canceled.
Raises the selected-value event with the new index and old and new values.
protected virtual void OnSelectedValueChanged(object sender, int newIndex, object newValue, object oldValue)
The element that initiated the value change.
newIndexintThe selected index associated with the new value.
newValueobjectThe new selected value.
oldValueobjectThe previous selected value.
Raises the event after the list's sort style changes.
protected virtual void OnSortStyleChanged(object sender, SortStyleChangedEventArgs args)
The list element whose sort style changed.
argsSortStyleChangedEventArgsThe event data containing the new sort style.
Raises the event that lets handlers customize a realized visual list item.
protected virtual void OnVisualItemFormatting(object sender, VisualItemFormattingEventArgs args)
The list element that owns the visual item.
argsVisualItemFormattingEventArgsThe event data containing the visual item to customize.
Handles coded UI property requests for item count, selection, multiple-selection mode, and data source.
protected override void ProcessCodedUIMessage(ref IPCMessage request)
The coded UI message to process or pass to the base implementation.
Overrides:
Forces re-evaluation of the current data source (if any).
public void Rebind()
Scrolls the view by the specified number of pages.
public void ScrollByPage(int pageCount)
The number of pages to scroll. Positive values scroll down, negative values scroll up.
Scrolls the view to make the specified item visible, positioning it appropriately within the visible area.
public void ScrollToItem(RadListDataItem item)
The RadListDataItem to scroll to.
Selects all items in the list if the current SelectionMode allows multiple selection.
public void SelectAll()
Thrown when SelectionMode is One or None.
Unsubscribes from the relevant events of the underlying RadListElement.
protected virtual void UnwireEvents()
Subscribes to the relevant events of the underlying RadListElement.
protected virtual void WireEvents()
Handles UI Automation provider requests and releases the provider when the control is destroyed.
protected override void WndProc(ref Message m)
The Windows message to process.
Overrides:
Events
Occurs when custom visual items need to be created, allowing users to provide custom visual representations for list items.
public event CreatingVisualListItemEventHandler CreatingVisualListItem
Fires after data binding operation has finished.
[Browsable(true)]
public event ListBindingCompleteEventHandler DataBindingComplete
Occurs before a RadListDataItem is data bound, allowing customization of the data binding process and providing custom item instances.
public event ListItemDataBindingEventHandler ItemDataBinding
Occurs after a RadListDataItem has been data bound, providing an opportunity to modify the bound item.
public event ListItemDataBoundEventHandler ItemDataBound
This event fires when the selected index property changes.
public event PositionChangedEventHandler SelectedIndexChanged
This event fires before SelectedIndex changes. This event allows the operation to be cancelled.
public event PositionChangingEventHandler SelectedIndexChanging
Occurs when the SelectedItems collection changes due to selection modifications.
public event NotifyCollectionChangedEventHandler SelectedItemsChanged
This event fires before the SelectedItems collection changes.
public event NotifyCollectionChangingEventHandler SelectedItemsChanging
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.
public event EventHandler SelectedValueChanged
Occurs when the SortStyle property value changes.
public event SortStyleChangedEventHandler SortStyleChanged
Occurs when visual item formatting is needed, allowing customization of the appearance of visible list items.
public event VisualListItemFormattingEventHandler VisualItemFormatting