Provides a data binding source that manages strongly-typed data item collections with full support for Windows Forms data binding, list manipulation, and change notifications.
RadListSource serves as a comprehensive data binding intermediary that bridges the gap between various data sources and RadControls. It implements multiple Windows Forms data binding interfaces including IList, ITypedList, ICancelAddNew, and change notification interfaces to provide seamless integration with the .NET data binding infrastructure.
The class manages a collection view that provides advanced data manipulation capabilities such as filtering, sorting, grouping, and paging. It maintains currency management for current item tracking and supports transactional operations for add/edit scenarios.
RadListSource can bind to various data sources including collections, DataTables, business objects, and other data sources through the IDataItemSource interface. It automatically handles data source changes, property descriptor management, and related data source relationships.
Definition
Namespace:Telerik.WinControls.Data
Assembly:Telerik.WinControls.dll
Type Parameters:
TDataItem
The type of data items in the list, which must implement IDataItem.
Syntax:
public class RadListSource<TDataItem> : IList, ICollection, IEnumerable, ITypedList, ICancelAddNew, INotifyCollectionChanged, INotifyPropertyChanged, ICurrencyManagerProvider, IDisposable where TDataItem : IDataItem
Inheritance: objectRadListSource<TDataItem>
Derived Classes:
Implements:
Constructors
Initializes an unbound list source with its default data view.
public RadListSource()
Initializes the list source with a data-item provider and an optional collection view.
public RadListSource(IDataItemSource source, RadCollectionView<TDataItem> collectionView)
The provider used to create items and supply a binding context, or null for an initially unbound source.
collectionViewRadCollectionView<TDataItem>The view that exposes the items; when null, an empty view is used.
Initializes the list source with a data-item provider and its default RadDataView<TDataItem>.
public RadListSource(IDataItemSource source)
The provider used to create items and supply a binding context, or null for an initially unbound source.
Properties
Gets the property descriptors currently used to read and write the bound items.
public PropertyDescriptorCollection BoundProperties { get; }
CollectionView
RadCollectionView<TDataItem>
Gets the collection view.
public RadCollectionView<TDataItem> CollectionView { get; }
The collection view.
Gets the number of item wrappers in the backing list, before collection-view filtering or sorting.
public int Count { get; }
Implements:
Gets or sets a value indicating whether each value setting should be encapsulaed in its own BeginEdit EndEditTransaction.
public bool CreateATransactionForEveryValueSetting { get; set; }
Current
TDataItem
Gets the current.
public TDataItem Current { get; }
The current.
Gets or sets the name of the list or table in the data source for which the RadListSource<TDataItem> is bound.
[Browsable(true)]
public string DataMember { get; set; }
Gets or sets the data source of the RadListSource<TDataItem>.
public object DataSource { get; set; }
Gets a value indicating whether this instance is data bound.
public bool IsDataBound { get; }
true if this instance is data bound; otherwise, false.
Gets a value indicating whether the ICollection<T> is read-only.
public bool IsReadOnly { get; }
Implements:
Determines whether this instance is in a Begin/End update block.
public bool IsUpdating { get; }
Items
List<TDataItem>
Gets or sets the backing list of item wrappers used by this source.
protected List<TDataItem> Items { get; set; }
Gets or sets the position.
public int Position { get; set; }
The position.
this[int]
TDataItem
Gets or sets the item at the specified index.
Gets or sets whether bound property-descriptor lookups use case-sensitive field names.
public bool UseCaseSensitiveFieldNames { get; set; }
Methods
Adds an item to the ICollection<T>.
public void Add(TDataItem item)
The object to add to the ICollection<T>.
Exceptions: NotSupportedExceptionThe ICollection<T> is read-only.
Adds the new.
public virtual TDataItem AddNew()
TDataItem
Adds the created item to ListSource.
public virtual TDataItem AddNew(TDataItem item)
TDataItem
Begins the update.
public void BeginUpdate()
Synchronizes a wrapper with its bound row and publishes an item-changed notification.
Removes all items from the ICollection<T>.
Empties the source and publishes property and collection reset notifications.
protected virtual void ClearItems()
Clears the backing item list without raising notifications.
protected virtual void ClearItemsCore()
Determines whether the ICollection<T> contains a specific value.
public bool Contains(TDataItem item)
The object to locate in the ICollection<T>.
Returns:true if item is found in the ICollection<T>; otherwise, false.
public void CopyTo(TDataItem[] array, int arrayIndex)
The one-dimensional Array that is the destination of the elements copied from ICollection<T>. The Array must have zero-based indexing.
arrayIndexintThe zero-based index in array at which copying begins.
array is null.
arrayIndex is less than 0.
array is multidimensional.
-or-
arrayIndex is equal to or greater than the length of array.
-or-
The number of elements in the source ICollection<T> is greater than the available space from arrayIndex to the end of the destination array.
-or-
Type T cannot be cast automatically to the type of the destination array.
Creates the collection view used by the constructor that accepts only an item source.
protected virtual RadCollectionView<TDataItem> CreateDefaultCollectionView()
RadCollectionView<TDataItem>
A RadDataView<TDataItem> over this list source.
Detaches currency-manager notifications and releases the manager reference.
public void Dispose()
Implements:
Ends the update.
public void EndUpdate()
Ends the update.
public void EndUpdate(bool notifyUpdates)
if set to true [notify updates].
Reads a bound property through the current property descriptors.
public object GetBoundValue(object dataBoundItem, string propertyName)
The underlying bound object.
propertyNamestringThe property name to read.
Returns:The property value, with enum-valued properties returned as their enum type; null when the source is not data-bound.
Exceptions: ArgumentExceptionNo property descriptor matches propertyName.
Returns an enumerator that iterates through the collection.
public IEnumerator<TDataItem> GetEnumerator()
IEnumerator<TDataItem>
A IEnumerator<T> that can be used to iterate through the collection.
Returns the PropertyDescriptorCollection that represents the properties on each item used to bind data.
public PropertyDescriptorCollection GetItemProperties(PropertyDescriptor[] listAccessors)
An array of PropertyDescriptor objects to find in the collection as bindable. This can be null.
Returns:The PropertyDescriptorCollection that represents the properties on each item used to bind data.
Implements:
Returns the name of the list.
public string GetListName(PropertyDescriptor[] listAccessors)
An array of PropertyDescriptor objects, for which the list name is returned. This can be null.
Returns:The name of the list.
Implements:
Determines the index of a specific item in the IList<T>.
public int IndexOf(TDataItem item)
The object to locate in the IList<T>.
Returns:The index of item if found in the list; otherwise, -1.
Associates an item wrapper with its underlying row from the bound list.
protected virtual void InitializeBoundRow(TDataItem item, object dataBoundItem)
The item wrapper to initialize.
dataBoundItemobjectThe row object represented by the wrapper.
Inserts an item to the IList<T> at the specified index.
public void Insert(int index, TDataItem item)
The zero-based index at which item should be inserted.
The object to insert into the IList<T>.
Exceptions: ArgumentOutOfRangeExceptionindex is not a valid index in the IList<T>.
The IList<T> is read-only.
Raises a CollectionChanged notification with action ItemChanged. Must be paired with the NotifyItemChanging method.
public void NotifyItemChanged(TDataItem item, string propertyName)
Raises a CollectionChanged notification with action ItemChanged. Must be paired with the NotifyItemChanging method.
public void NotifyItemChanged(TDataItem item)
Raises a CollectionChanged notification with action ItemChanging. Must be paired with the NotifyItemChanged method.
public void NotifyItemChanging(TDataItem item, string propertyName)
Raises a CollectionChanged notification with action ItemChanging. Must be paired with the NotifyItemChanged method.
public void NotifyItemChanging(TDataItem item)
Raises a collection notification unless a list-source update is in progress.
protected virtual void OnCollectionChanged(NotifyCollectionChangedEventArgs e)
The collection change to publish.
Raises the NotifyPropertyChanged event
protected virtual void OnNotifyPropertyChanged(PropertyChangedEventArgs e)
Raises the PropertyChanged event
protected virtual void OnNotifyPropertyChanged(string propertyName)
The name of the property
Maps a currency-manager list change to the corresponding item update or metadata refresh.
protected virtual void ProcessCurrencyManagerListChanged(object sender, ListChangedEventArgs e)
The currency manager that raised the notification.
eListChangedEventArgsThe list change and any associated property descriptor.
Refreshes this instance.
public virtual void Refresh()
Removes the first occurrence of a specific object from the ICollection<T>.
public bool Remove(TDataItem item)
The object to remove from the ICollection<T>.
Returns:true if item was successfully removed from the ICollection<T>; otherwise, false. This method also returns false if item is not found in the original ICollection<T>.
The ICollection<T> is read-only.
Removes the IList<T> item at the specified index.
public void RemoveAt(int index)
The zero-based index of the item to remove.
Exceptions: ArgumentOutOfRangeExceptionindex is not a valid index in the IList<T>.
The IList<T> is read-only.
Implements:
Removes an item wrapper at an index and publishes a remove notification.
Resets this instance.
public virtual void Reset()
Sets a bound property or a nested property reached through a path, using the property name in notifications.
public bool SetBoundValue(IDataItem dataItem, string propertyName, object value, string path)
The item whose bound object is updated.
propertyNamestringThe bound property to set when path is empty.
The value to assign.
pathstringA dotted path to a nested property, or null or empty to set propertyName directly.
true if the source is data-bound and the assignment completes; otherwise, false.
Sets a bound property and uses its name as the collection-change property name.
public bool SetBoundValue(IDataItem dataItem, string propertyName, object value)
The item whose bound object is updated.
propertyNamestringThe bound property to set.
valueobjectThe value to assign.
Returns:true if the source is data-bound and the assignment completes; otherwise, false.
Sets a bound property while allowing the property used for assignment to differ from the name reported in notifications.
public bool SetBoundValue(IDataItem dataItem, string propertyName, string columnName, object value, string path)
The item whose bound object is updated.
propertyNamestringThe descriptor name used for direct assignment.
columnNamestringThe property name published with item-change notifications.
valueobjectThe value to assign.
pathstringA dotted path to a nested property, or null or empty to use propertyName.
true if the source is data-bound and the assignment completes; otherwise, false.
When enabled, each direct assignment to an IEditableObject is wrapped in a separate edit transaction.
Replaces the item wrapper at an index and publishes a replace notification.
protected virtual void SetItem(int index, TDataItem item)
The index to update.
itemTDataItemThe replacement wrapper.
Removes the currency-manager and source-collection subscriptions added by WireEvents().
protected virtual void UnWireEvents()
Subscribes to currency-manager and supported source-collection notifications.
protected virtual void WireEvents()
Events
Occurs when items in the list source are added, removed, moved, replaced, or changed.
public event NotifyCollectionChangedEventHandler CollectionChanged
Implements:
Occurs when the bound currency manager changes its current position, before the collection view is synchronized.
public event EventHandler PositionChanged
Occurs when a property value changes.
public event PropertyChangedEventHandler PropertyChanged
Implements: