ClassRadListElement
Represents the main element that provides list functionality with virtualized scrolling and data binding capabilities.
Definition
Namespace:Telerik.WinControls.UI
Assembly:Telerik.WinControls.UI.dll
Syntax:
public class RadListElement : VirtualizedScrollPanel<RadListDataItem, RadListVisualItem>, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IBindableComponent, IComponent, IDisposable, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode, IPrimitiveElement, IShapedElement, IFillElement, IBorderElement, IBoxStyle, IBoxElement, IDrawFillElement, IImageElement, ITextPrimitive, ITextProviderInheritance: objectDisposableObjectRadObjectRadElementVisualElementRadComponentElementRadItemUIItemBaseLightVisualElementScrollViewElement<VirtualizedStackContainer<RadListDataItem>>VirtualizedScrollPanel<RadListDataItem, RadListVisualItem>RadListElement
Derived Classes:
Implements:
Inherited Members
Constructors
RadListElement()
Creates a new instance of the RadListElement class.
Declaration
public RadListElement()Fields
AlternatingItemColorProperty
Identifies the AlternatingItemColor dependency property that specifies the background color for alternating items.
Declaration
public static RadProperty AlternatingItemColorPropertyField Value
CaseSensitiveSortProperty
Identifies the CaseSensitiveSort dependency property that controls whether sorting operations consider text case.
Declaration
public static readonly RadProperty CaseSensitiveSortPropertyField Value
EnableAlternatingItemColorProperty
Identifies the EnableAlternatingItemColor dependency property that controls whether alternating item colors are applied.
Declaration
public static RadProperty EnableAlternatingItemColorPropertyField Value
Properties
ActiveItem
Gets or sets the active item. This property is meaningful only when SelectionMode is MultiSimple or MultiExtended with the Control key pressed.
Declaration
[Browsable(false)]
public RadListDataItem ActiveItem { get; set; }Property Value
AllowDragDrop
Gets or sets value indicating if the user can reorder items via drag and drop. Always false when kinetic scrolling is enabled.
Declaration
[Browsable(true)]
public bool AllowDragDrop { get; set; }Property Value
AlternatingItemColor
Gets or sets a value indidcating the alternating item color for odd items.
Declaration
public virtual Color AlternatingItemColor { get; set; }Property Value
CaseSensitiveSort
Gets or sets a value that indicates whether text case will be taken into account when sorting.
DataLayer
Gets the data layer that manages the list's data operations and binding functionality.
DataMember
Gets or sets the name of the list or table in the data source for which the RadListElement is displaying data.
DataSource
Gets or sets the data source that provides items to be displayed in the list element.
DescriptionTextMember
Gets or sets a string which will be used to get a description text string for each visual item. This property can not be set to null. Setting it to null will cause it to contain an empty string.
Declaration
public string DescriptionTextMember { get; set; }Property Value
DisplayMember
Gets or sets a string which will be used to get a text string for each visual item. This property can not be set to null. Setting it to null will cause it to contain an empty string.
DragDropService
Declaration
public ListControlDragDropService DragDropService { get; set; }Property Value
EnableAlternatingItemColor
Gets or sets a value indicating whether alternating item color is enabled.
Declaration
[Browsable(true)]
public virtual bool EnableAlternatingItemColor { get; set; }Property Value
EnableKineticScrolling
Gets or sets a value indicating whether kinetic scrolling is enabled.
Declaration
[Browsable(true)]
public bool EnableKineticScrolling { get; set; }Property Value
Filter
Gets or sets a Predicate that will be called for every data item in order to determine if the item will be visible.
Declaration
public Predicate<RadListDataItem> Filter { get; set; }Property Value
FilterExpression
Gets or sets a filter expression that determines which items will be visible.
FindStringComparer
Gets or sets an object that implements IFindStringComparer. The value of this property is used in the FindString() method when searching for an item.
Declaration
[Browsable(false)]
public IFindStringComparer FindStringComparer { get; set; }Property Value
FitItemsToSize
Gets or sets a value indicating whether items fit to size.
Declaration
public override bool FitItemsToSize { get; set; }Property Value
true if [fit items to size]; otherwise, false.
Overrides
FormatInfo
Gets or sets an object that implements the IFormatProvider interface. This object is used when formatting items. The default object is CultureInfo.CurrentCulture.
Declaration
[Browsable(false)]
public IFormatProvider FormatInfo { get; set; }Property Value
FormatString
Gets or sets a format string that will be used for visual item formatting if FormattingEnabled is set to true.
FormattingEnabled
Gets or sets a value that determines whether text formatting is enabled for the visual items.
HasSelectedValueChanged
Gets a value indicating whether the SelectedValue property is different after the selection last changed.
IsDescriptionText
Declaration
protected virtual bool IsDescriptionText { get; set; }Property Value
IsFilterActive
Gets a boolean value that indicates whether the is a filter currently set either with the Filter or FilterExpression properties.
IsUpdating
Gets a value indicating whether the element is currently in an updating state (between BeginUpdate and EndUpdate calls).
ItemHeight
Gets or sets the item height for the items. This property is disregarded when AutoSizeItems is set to true.
ItemTextComparisonMode
Gets or sets a value that determines whether the FindString() method searches via the text property set by the user or by the text provided by the data binding logic, that is, by DisplayMember.
Declaration
public ItemTextComparisonMode ItemTextComparisonMode { get; set; }Property Value
ItemsSortComparer
Gets or sets an object that implements IComparer and sorts the items according to its logic.
Declaration
[Browsable(false)]
public IComparer<RadListDataItem> ItemsSortComparer { get; set; }Property Value
IComparer<RadListDataItem>
KeyboardSearchEnabled
Gets or sets a value that determines whether the user can search for an item by typing characters when RadListElement is focused.
KeyboardSearchResetInterval
Gets or sets a value that specifies how long the user must wait before searching with the keyboard is reset. The default value of this property is 300 ms.
Declaration
public int KeyboardSearchResetInterval { get; set; }Property Value
ReadOnly
Gets or sets a value indicating whether the drop down list is read only.
Declaration
public bool ReadOnly { get; set; }Property Value
true if the drop down list is read only; otherwise, false.
ScrollBehavior
Gets the ScrollServiceBehavior that is responsible for the kinetic scrolling option.
Declaration
public ScrollServiceBehavior ScrollBehavior { get; }Property Value
ScrollMode
Gets or sets the scrolling mode.
Declaration
[Browsable(false)]
public ItemScrollerScrollModes ScrollMode { get; set; }Property Value
SelectedIndex
Gets or sets the position of the selection. Setting this property will cause the SelectedIndexChanging and SelectedIndexChanged events to fire.
Declaration
[Browsable(false)]
public int SelectedIndex { get; set; }Property Value
SelectedItem
Gets or sets the selected logical list item. Setting this property will cause the selection events to fire.
Declaration
[Browsable(false)]
public RadListDataItem SelectedItem { get; set; }Property Value
SelectedItems
Provides a readonly interface to the currently selected items.
Declaration
public IReadOnlyCollection<RadListDataItem> SelectedItems { get; }Property Value
SelectedValue
Gets or sets the currently selected value. Setting the SelectedValue to a value that is shared between many items causes the first item to be selected. This property triggers the selection events.
Declaration
[Browsable(false)]
public object SelectedValue { get; set; }Property Value
SelectionMode
Gets or sets the SelectionMode which determines selection behavior of RadListElement.
Declaration
[Browsable(false)]
public SelectionMode SelectionMode { get; set; }Property Value
SortStyle
Gets or sets the sort style. It can be Ascending, Descending or None. Sorting is performed according to the property specified by DisplayMember.
SuspendItemsChangeEvents
Gets or sets a value that indicates if this RadListElement will stop firing the ItemsChanging and ItemsChanged events.
Declaration
public bool SuspendItemsChangeEvents { get; set; }Property Value
SuspendSelectionEvents
Gets or sets a value that determines whether to stop the selection events from firing. These are SelectedIndexChanged, SelectedIndexChanging and SelectedValueChanged.
Declaration
[Browsable(false)]
public bool SuspendSelectionEvents { get; set; }Property Value
ValueMember
Gets or sets the string through which the SelectedValue property will be determined. This property can not be set to null. Setting it to null will cause it to contain an empty string.
Methods
BeginUpdate()
Suspends internal notifications and processing in order to improve performance. This method is cumulative, that is, if BeginUpdate is called N times, EndUpdate must also be called N times.
Declaration
public void BeginUpdate()ClearSelected()
Declaration
public void ClearSelected()CreateDataLayer()
Creates an instance of the data layer responsible for managing items in both bound and unbound modes.
Declaration
protected virtual ListDataLayer CreateDataLayer()Returns
A new ListDataLayer instance.
CreateElementProvider()
Creates an instance of the element provider responsible for mapping between logical and visual items and determining when visual items need updates.
Declaration
protected override IVirtualizedElementProvider<RadListDataItem> CreateElementProvider()Returns
IVirtualizedElementProvider<RadListDataItem>
A new IVirtualizedElementProvider<T> instance.
Overrides
CreateStringComparer()
Declaration
protected virtual IFindStringComparer CreateStringComparer()Returns
CreateViewElement()
Creates an instance of the visual container element responsible for arranging and displaying visual items in the list layout.
Declaration
protected override VirtualizedStackContainer<RadListDataItem> CreateViewElement()Returns
VirtualizedStackContainer<RadListDataItem>
A new VirtualizedStackContainer<T> instance.
Overrides
DataViewGroupPredicate(RadListDataItem, int)
Declaration
protected object DataViewGroupPredicate(RadListDataItem item, int level)Parameters
item
level
Returns
DataView_PropertyChanged(object, PropertyChangedEventArgs)
Declaration
protected void DataView_PropertyChanged(object sender, PropertyChangedEventArgs e)Parameters
sender
e
DeferRefresh()
Defers the refresh.
DisposeManagedResources()
Disposes of managed resources including cached images and SVG images when the element is being disposed.
Declaration
protected override void DisposeManagedResources()Overrides
DpiScaleChanged(SizeF)
Called when the DPI scale factor changes. Updates the scale factor and notifies child elements.
Declaration
public override void DpiScaleChanged(SizeF scaleFactor)Parameters
scaleFactor
The new DPI scale factor.
Overrides
EndUpdate()
Resumes the internal notifications and processing previously suspended by BeginUpdate.
Declaration
public void EndUpdate()FindItemExact(string, bool)
Finds the first item in the RadList control that matches the specified string.
Declaration
public RadListDataItem FindItemExact(string text, bool caseSensitive)Parameters
text
The string to search for.
caseSensitive
Determines whether the search is case sensitive or not.
Returns
The zero-based index of the first item found; returns null if no match is found.
FindParentListVisualItem(RadElement)
Declaration
protected RadListVisualItem FindParentListVisualItem(RadElement child)Parameters
child
Returns
FindString(string)
Searches for an item related to the specified string. The relation is described by the object assigned to FindStringComparer property. By default this relation is the System.String.StartsWith(). This method starts searching from the beginning of the items.
FindString(string, int)
Searches for an item related to the specified string. The relation is described by the object assigned to FindStringComparer property. By default FindStringComparer uses the System.String.StartsWith() method. This method starts searching from the specified index. If the algorithm reaches the end of the Items collection it wraps to the beginning and continues until one before the provided index.
FindStringExact(string)
Searches for an item in the same manner as FindString() but matches an item only if its text is exactly equal to the provided string.
FindStringExact(string, int)
Searches for an item in the same manner as FindString() but matches an item only if its text is exactly equal to the provided string.
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.
FindStringNonWrapping(string, int)
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.
GetFirstVisibleItemIndex()
Gets the index of the first visible item.
GetIndex(RadListDataItem)
Returns the index of the provided list data item. This index determines the items position in the data view.
Declaration
protected int GetIndex(RadListDataItem item)Parameters
item
The index for which to return an index.
Returns
Returns the index of the provided item.
GetLastVisibleItemIndex()
Gets the index of the last visible item.
GetMiddleVisibleItemIndex()
Gets the index of the middle visible item.
HandleItemsAdded(NotifyCollectionChangedEventArgs)
Declaration
protected virtual void HandleItemsAdded(NotifyCollectionChangedEventArgs args)Parameters
args
HandleItemsRemoved(NotifyCollectionChangedEventArgs)
Declaration
protected virtual void HandleItemsRemoved(NotifyCollectionChangedEventArgs args)Parameters
args
HandleItemsReplaced(NotifyCollectionChangedEventArgs)
Declaration
protected virtual void HandleItemsReplaced(NotifyCollectionChangedEventArgs args)Parameters
args
HandleItemsReset(NotifyCollectionChangedEventArgs)
Declaration
protected virtual void HandleItemsReset(NotifyCollectionChangedEventArgs args)Parameters
args
InitializeFields()
Initializes the fields and components required for the list element functionality.
Declaration
protected override void InitializeFields()Overrides
InitializeItemScroller(ItemScroller<RadListDataItem>)
Initializes the item scroller with appropriate settings for the list control.
Declaration
protected override void InitializeItemScroller(ItemScroller<RadListDataItem> scroller)Parameters
scroller
The ItemScroller<T> to initialize.
Overrides
IsIndexValid(int)
Determines whether the provided index is in the range [0, Items.Count)
IsItemPartiallyVisible(RadListVisualItem)
Determines if the provided visual item intersects the view but is not contained in it.
Declaration
protected bool IsItemPartiallyVisible(RadListVisualItem item)Parameters
item
Returns
ItemFullyVisible(RadListDataItem)
This method returns true if the ActiveItem is fully visible.
Declaration
protected bool ItemFullyVisible(RadListDataItem item)Parameters
item
Returns
OnActiveItemAdded(RadListDataItem)
Declaration
protected virtual void OnActiveItemAdded(RadListDataItem newItem)Parameters
newItem
OnBoundsChanged(RadPropertyChangedEventArgs)
Handles the bounds changed event by updating the fill primitive implementation and invoking the base class handler.
Declaration
protected override void OnBoundsChanged(RadPropertyChangedEventArgs e)Parameters
e
Event arguments containing information about the property change, including the old bounds value.
Overrides
OnBubbleEvent(RadElement, RoutedEventArgs)
Called when the bubble phase of a routed event occurs.
Declaration
protected override void OnBubbleEvent(RadElement sender, RoutedEventArgs args)Parameters
sender
The element that originally raised the event.
args
The routed event arguments.
Overrides
OnControlMouseDown(MouseEventArgs)
Declaration
public virtual bool OnControlMouseDown(MouseEventArgs e)Parameters
e
Returns
OnControlMouseMove(MouseEventArgs)
Declaration
public virtual bool OnControlMouseMove(MouseEventArgs e)Parameters
e
Returns
OnControlMouseUp(MouseEventArgs)
Declaration
public virtual bool OnControlMouseUp(MouseEventArgs e)Parameters
e
Returns
OnCreatingVisualListItem(RadListDataItem, RadListVisualItem)
Fires the CreatingVisualItem event.
Declaration
protected virtual RadListVisualItem OnCreatingVisualListItem(RadListDataItem dataItem, RadListVisualItem item)Parameters
dataItem
item
Returns
OnCreatingVisualListItem(RadListVisualItem)
Fires the CreatingVisualItem event.
Declaration
protected virtual RadListVisualItem OnCreatingVisualListItem(RadListVisualItem item)Parameters
item
Returns
OnDataBindingComplete(object, ListBindingCompleteEventArgs)
Raises the DataBindingComplete event.
Declaration
protected virtual void OnDataBindingComplete(object sender, ListBindingCompleteEventArgs e)Parameters
sender
e
An ListBindingCompleteEventArgs instance that contains the event data.
OnDataItemPropertyChanged(object, RadPropertyChangedEventArgs)
Raises the DataItemPropertyChanged
Declaration
protected virtual void OnDataItemPropertyChanged(object sender, RadPropertyChangedEventArgs args)Parameters
sender
args
OnItemsChanged(NotifyCollectionChangedEventArgs)
Raises the ItemsChanged event with the provided arguments.
Declaration
protected virtual void OnItemsChanged(NotifyCollectionChangedEventArgs args)Parameters
args
NotifyCollectionChangedEventArgs
The arguments that contain the data relevant to the items change.
OnItemsChanging(NotifyCollectionChangingEventArgs)
Raises the ItemsChanging event with the provided arguments.
Declaration
protected virtual void OnItemsChanging(NotifyCollectionChangingEventArgs args)Parameters
args
NotifyCollectionChangingEventArgs
The arguments that contain the data relevant to the pending items change.
OnListItemDataBinding()
Fires the ItemDataBinding event.
Declaration
protected virtual RadListDataItem OnListItemDataBinding()Returns
OnListItemDataBound(RadListDataItem)
Fires the ItemDataBound event.
Declaration
protected virtual void OnListItemDataBound(RadListDataItem newItem)Parameters
newItem
OnLoaded()
Called when the element has been successfully loaded. That includes loading of all its children as well.
Declaration
protected override void OnLoaded()Overrides
OnMouseDown(MouseEventArgs)
Called when a mouse button is pressed down over the item.
Declaration
protected override void OnMouseDown(MouseEventArgs e)Parameters
e
The mouse event arguments.
Overrides
OnMouseWheel(int)
Performs scrolling logic depending on the delta from the mouse wheel.
OnPanGesture(PanGestureEventArgs)
Fires the PanGesture event.
Declaration
protected override void OnPanGesture(PanGestureEventArgs args)Parameters
args
The arguments for the PanGesture event.
Overrides
OnPropertyChanged(RadPropertyChangedEventArgs)
Handles property change events by invalidating the fill cache and invoking the base class property change handler.
Declaration
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)Parameters
e
Event arguments containing information about the property that changed.
Overrides
OnSelectedIndexChanged(int)
Fires the SelectedIndexChanged event.
Declaration
protected virtual void OnSelectedIndexChanged(int newIndex)Parameters
newIndex
OnSelectedIndexChanging(int)
Fires the SelectedIndexChanging event.
OnSelectedItemAdded(RadListDataItem)
Declaration
protected virtual void OnSelectedItemAdded(RadListDataItem newItem)Parameters
newItem
OnSelectedValueChanged(int)
Fires the SelectedValueChanged event if SelectedValue has actually changed since many items can have the same value.
Declaration
protected virtual void OnSelectedValueChanged(int newIndex)Parameters
newIndex
OnSortStyleChanged(SortStyle)
Fires the SortStyleChanged event.
Declaration
protected virtual void OnSortStyleChanged(SortStyle sortStyle)Parameters
sortStyle
OnVisualItemFormatting(RadListVisualItem)
Fires the VisualItemFormattingeEvent with the provided visual item.
Declaration
protected virtual void OnVisualItemFormatting(RadListVisualItem item)Parameters
item
ProcessKeyboardSearch(char)
Finds an item with the text provided by an internal search buffer after the character argument is appended to the buffer. The search buffer is reset after a user defined time since the last character was typed. By default this is 300 ms. Users can set the KeyboardSearchResetInterval property to a custom interval.
Declaration
protected virtual void ProcessKeyboardSearch(char character)Parameters
character
A character that will be appended to the search buffer.
Rebind()
Forces re-evaluation of the current data source (if any).
Declaration
public void Rebind()ScrollToActiveItem()
Scrolls to the active item if it is not null and if it is not fully visible.
Declaration
public void ScrollToActiveItem()ScrollToItem(RadListDataItem)
Scrolls to the provided item so that the item will appear at the top of the view if it is before the currently visible items and at the bottom of the view if it is after the currently visible items.
Declaration
public void ScrollToItem(RadListDataItem item)Parameters
item
The item to scroll to.
SelectAll()
Selects all items if the SelectionMode allows it.
Declaration
public void SelectAll()Exceptions
Selecting all items is not a valid operation in the current selection mode. SelectionMode = + this.selectionMode.ToString() + .
SelectRange(int, int)
Clears the currently selected items and selects all items in the closed range [startIndex, endIndex].
SetSelectedIndex(int)
Sets the selected index to the specified value if it is different than the current value and fires the selection events. This method triggers selection events.
Declaration
protected virtual void SetSelectedIndex(int value)Parameters
value
SetSelectedItem(RadListDataItem)
Sets the selected data item to the specified item. If the item is different than the current one the selection events will be fired. This method triggers selection events.
Declaration
protected void SetSelectedItem(RadListDataItem value)Parameters
value
SetSelectedItemCore(RadListDataItem)
Declaration
protected virtual void SetSelectedItemCore(RadListDataItem item)Parameters
item
SetSelectedValue(object)
Sets the SelectedItem and thus SelectedIndex to the logical item with the specified value. If there are many items with the same value the first item found will be selected. This method triggers selection events.
Declaration
protected virtual void SetSelectedValue(object value)Parameters
value
The value for which to find an item.
SynchronizeVisualItems()
Syncronizes the properties of all visual elements with their data items.
Declaration
protected virtual void SynchronizeVisualItems()UnwireEvents()
Performs events unsubscription from internal objects. The base implementation must always be called.
Declaration
protected override void UnwireEvents()Overrides
UpdateActiveItem(RadListDataItem, bool)
This method sets the provided item as active and the previous one to inactive. There can be only active item at a time.
Declaration
protected virtual void UpdateActiveItem(RadListDataItem item, bool active)Parameters
item
The item to set to an active state.
active
The value to which the Active property of item will be set.
UpdateItemTraverser()
Creates a new item traverser and updates the current. If group refresh is suspended this method has no effect.
Declaration
protected void UpdateItemTraverser()WireEvents()
Performs events subscription to internal objects. The base implementation must always be called.
Declaration
protected override void WireEvents()Overrides
Events
CreatingVisualItem
This event fires while creating visual items. This happens on during initial layout and during resizing if the new size is larger and thus allowing more items to be visualized. The event provides a means to create a custom visual item.
Declaration
public event CreatingVisualListItemEventHandler CreatingVisualItemEvent Value
DataBindingComplete
Fires after data binding operation has finished.
Declaration
[Browsable(true)]
public event ListBindingCompleteEventHandler DataBindingCompleteEvent Value
DataItemPropertyChanged
This event fires whenever a RadProperty of a data item changes. This event is most often used to listen changes in Selected and Active properties of the data items.
Declaration
public event RadPropertyChangedEventHandler DataItemPropertyChangedEvent Value
ItemDataBinding
This item fires for data item that is being created during data binding and fires before the ItemDataBound event. The event provides a means for changing the instance of the data item to a custom data item.
Declaration
public event ListItemDataBindingEventHandler ItemDataBindingEvent Value
ItemDataBound
This event fires after a data item has been created and bound.
Declaration
public event ListItemDataBoundEventHandler ItemDataBoundEvent Value
ItemsChanged
This event fires whenever an item is added, removed, set or if the whole items collection was modified.
Declaration
public event NotifyCollectionChangedEventHandler ItemsChangedEvent Value
ItemsChanging
This event fires right before adding, removing or setting an item. This event will not fire if an item is added to a data source directly because there is no way for RadListElement to be notified before the change.
Declaration
public event NotifyCollectionChangingEventHandler ItemsChangingEvent Value
SelectedIndexChanged
This event fires when selected index changes. This always happens when the SelectedItem changes.
Declaration
public event PositionChangedEventHandler SelectedIndexChangedEvent Value
SelectedIndexChanging
This event fires before SelectedIndexChanged and provides a means for cancelling the whole selection operation. Someties this event will not fire since cancelling the change is not possible, for example when the DataSource is set to null.
Declaration
public event PositionChangingEventHandler SelectedIndexChangingEvent Value
SelectedItemsChanged
Declaration
public event NotifyCollectionChangedEventHandler SelectedItemsChangedEvent Value
SelectedItemsChanging
Declaration
public event NotifyCollectionChangingEventHandler SelectedItemsChangingEvent Value
SelectedValueChanged
This event fires when the SelectedValue changes. This is will not always fire when the SelectedItem or SelectedIndex changes because the new item may have the same value.
Declaration
public event EventHandler SelectedValueChangedEvent Value
SortStyleChanged
This event fires after the sorting style changes.
Declaration
public event SortStyleChangedEventHandler SortStyleChangedEvent Value
VisualItemFormatting
The visual item formatting fires whenever the state of a visible logical item changes and when scrolling.
Declaration
public event VisualListItemFormattingEventHandler VisualItemFormattingEvent Value