BindingSource

Wisej.Web.BindingSource

Namespace: Wisej.Web

Assembly: Wisej.Framework (2.5.0.0)

Encapsulates the data source for a data-bound component.

C#

public class BindingSource : BindingSource, ICurrencyManagerProvider

VB.NET

Constructors

BindingSource()

Initializes a new instance of the BindingSource class to the default property values.

BindingSource(container)

Initializes a new instance of the BindingSource class and adds the BindingSource to the specified container.

Name	Type	Description
container	IContainer	The IContainer to add the current BindingSource to.

BindingSource(dataSource, dataMember)

Initializes a new instance of the BindingSource class with the specified data source and data member.

Name	Type	Description
dataSource	Object	The data source for the BindingSource.
dataMember	String	The specific column or list name within the data source to bind to.

Properties

AllowEdit

Boolean: Returns whether items in the underlying list can be edited.

AllowNew

Boolean: Returns or sets whether the AddNew method can be used to add items to the list.

Throws:

• InvalidOperationException This property is set to true when the underlying list represented by the List property has a fixed size or is read-only.

• MissingMethodException The property is set to true and the AddingNew event is not handled when the underlying list type does not have a default constructor.

AllowRemove

Boolean: Returns whether the items can be removed from the underlying list.

Count

Int32: Returns the total number of items in the underlying list, filtered using the current Filter value.

CurrencyManager

CurrencyManager: Returns the currency manager associated with this BindingSource.

Current

Object: Returns the current item in the list.

Use the Current property to access the current item, but use the List property to get the entire list. To determine the type of the current object, use the GetType, or ToString methods. To change the current item, set the Position property to a new integral value, or use one of the navigation methods such as MoveNext.

DataMember

String: Returns or sets the list in the data source to which the connector currently binds to.

If the DataSource contains multiple lists (or tables) of data, you should set the DataMember property to the name of one of the sources. Setting this property raises the DataMemberChanged event

DataSource

Object: Returns or sets the data source that the connector binds to.

The DataSource property can be set to a number of data sources, including types, objects, and lists of types. The resulting data source will be exposed as a list. The following table shows some of the common data sources and the resulting list evaluation.

| DataSource | List Result | | :--- | | null | An empty IBindingList of objects. Adding an item sets the list to the type of the added item. | | null with DataMember set | Not supported, raises ArgumentException. | | Non-list type or object of type "T" | Empty IBindingList of type "T". | | Array instance | IBindingList containing the array elements. | | IEnumerable instance | An IBindingList containing the IEnumerable items. | | List instance containing type "T" | IBindingList instance containing type "T". |

In addition, DataSource can be set to other list types such as IListSource and ITypedList and the BindingSource will handle them appropriately. In this case, the type contained in the list should have a parameterless constructor. When setting a data source, if the supplied reference contains more than one list or table, you must set the DataMember property to a string that specifies the list to bind to. Setting this property raises the DataSourceChanged event.

Filter

String: Returns or sets the expression used to filter the items in the underlying List.

Typically used in complex data-binding scenarios, the Filter property allows you to view a subset of the DataSource. Only underlying lists that implement the IBindingListView interface support filtering. When Filter is not null, the BindingSource passes this property to the underlying list. If you set this property during object initialization, the call will be deferred until after initialization is complete. To form a filter value, specify the name of a column followed by an operator and a value to filter on. The accepted filter syntax depends on the underlying data source. If the underlying data source is a DataSet, DataTable, or DataView, you can specify Boolean expressions using the syntax documented for the DataColumn.Expression property. The value of the Filter property affects the value of the Count property. Additionally, the Filter value will persist when the data source changes. To stop filtering the DataSource, call the RemoveFilter method.

IsBindingSuspended

Boolean: Returns whether data binding is suspended.

IsFixedSize

Boolean: Returns whether the underlying List has a fixed size.

IsReadOnly

Boolean: Return whether the underlying List is read-only.

IsSorted

Boolean: Returns whether the items in the underlying List are sorted.

IsSynchronized

Boolean: Returns whether access to the collection is synchronized (thread safe).

Item(index)

Object: Returns or sets the list element at the specified index in the underlying List.

Throws:

• ArgumentOutOfRangeException index is less than zero or is equal to or greater than Count.

List

IList: Returns the underlying data list.

The BindingSource class uniformly handles different data sources. Ideally the List property should be set to a general IList. However, sometimes it may be necessary to cast this property to a more specific type. The following table shows the underlying list type, which depends on the type or value of the data source.

| DataSource Type | Underlying List Description | | :--- | | DataSource and DataMember are null | An empty ArrayList. | | DataSource is null, but DataMember is not null | None; an attempt to get the List will throw an ArgumentException. | | An Array instance | An Array. | | An IListSource instance | The return value from a call to the GetList() method of this IListSource instance. | | An IBindingList instance | An IBindingList. | | An IList instance | An IList. | | A non-IList instance of type "T" | A BindingList with one element. | | An ICustomTypeDescriptor instance | An ArrayList with one element. | | An IEnumerable | An ArrayList with the elements copied over. | | The Array type with DataMember of item type "T" | A BindingList. | | A Type that represents an IListSource or ITypedList | An instance created by a call to the CreateInstance(Type) method of the Activator class. A NotSupportedException may be thrown. | | The IList type with DataMember of item type "T" or a non-IList type | A BindingList | | The ICustomTypeDescriptor type | None; an attempt to get the List will throw an NotSupportedException. |

If the type retrieved is the IList interface, the underlying collection may be more complex, such as an ArrayList or DataView class.

Position

Int32: Returns or sets the index of the current item in the underlying List.

When setting the Position property, out-of-range values are treated in the following manner:

• Negative values are treated as 0.

• Values greater than or equal to Count are treated as Count minus 1.

Changing the Position property will adjust the Current property.

RaiseListChangedEvents

Boolean: Returns or sets a value indicating whether ListChanged events should be raised.

When the RaiseListChangedEvents property is false, it suspends the raising of the ListChanged events. This event indicates that the bound list has been modified in some way, including adding, deleting, inserting, or modifying items.

RefreshValueOnChange

Boolean: Enables the automatic refresh of the source property after a data-bound value has been updated in the data source.

This option fixes a long standing "feature" of the default BindingSource where the property that is the source of a value change is not refreshed automatically after it updates the bound data source. In a scenario where the data source "transforms" the value received from a data-bound control, the source property is not updated while all other bound properties are.

Sort

String: Returns or sets the column names used for sorting, and the sort order for viewing the rows in the data source.

The Sort property is a case-sensitive string that specifies the column names used to sort the rows, along with the SortDirection. Columns are sorted ascending by default. Multiple columns can be separated by commas, such as "State, ZipCode DESC". To support sorting, the underlying List must implement the IBindingList or IBindingListView interfaces. This capability can be queried through the SupportsSorting property. Multicolumn sorting is available when the SupportsAdvancedSorting property is true. Setting the Sort property will change the internal list depending on its type:

• If the list is of type IBindingList, the SortProperty and SortDirection properties are set in the internal list.

• If the list is of type IBindingListView, the SortDescriptions property is set.

The internal list's sort properties are only changed when the sort string is not null. The get accessor for this property will not retrieve the sort value of the internal list; instead, it will return the set accessor value. The value of the Sort property will persist when the data source changes.

SortDescriptions

ListSortDescriptionCollection: Returns the collection of sort descriptions applied to the data source.

If the data source is not an IBindingListView, the SortDescriptions property always returns null.

SortDirection

ListSortDirection: Returns the direction the items in the underlying List are sorted.

If the data source is not an IBindingList, the SortDirection property always returns Ascending.

SortProperty

PropertyDescriptor: Returns the PropertyDescriptor that is being used for sorting the underlying List.

If the data source is not an IBindingList, the SortProperty property always returns null.

SupportsAdvancedSorting

Boolean: Returns whether the data source supports multi-column sorting.

If the data source is not an IBindingListView, the SupportsAdvancedSorting property always returns false.

SupportsChangeNotification

Boolean: Return whether the data source supports change notification.

SupportsFiltering

Boolean: Returns whether the data source supports filtering.

If the data source is not an IBindingList, the SupportsFiltering property always returns false.

SupportsSearching

Boolean: Returns whether the data source supports searching with the Find method.

If the data source is not an IBindingList, the SupportsSearching property always returns false.

SupportsSorting

Boolean: Returns whether the data source supports sorting.

If the data source is not an IBindingList, the SupportsSorting property always returns false.

SyncRoot

Object: Returns an object used to synchronize access to the underlying List.

Methods

Add(item)

Adds an existing item to the underlying List.

Parameter	Type	Description
item	Object	Item to add the underlying List.

Returns: Int32. The index at which the item was added to the underlying List.

AddNew()

Adds a new item to the underlying List.

Returns: Object. The object that was created and added to the underlying List.

ApplySort(property, sort)

Sorts the data source using the specified property descriptor and sort direction.

Parameter	Type	Description
property	PropertyDescriptor	A PropertyDescriptor that describes the property by which to sort the data source.
sort	ListSortDirection	A ListSortDescription indicating how the list should be sorted.

The IBindingList implements single column sorting using a PropertyDescriptor to indicate a property to sort by and a ListSortDirection indicating whether the property contents should be sorted in ascending or descending order. Throws:

• NotSupportedException The data source is not an IBindingList.

ApplySort(sorts)

Sorts the data source with the specified sort descriptions.

Parameter	Type	Description
sorts	ListSortDescriptionCollection	A ListSortDescriptionCollection containing the sort descriptions to apply to the data source.

IBindingListView implements multi-column sorting as a set of property descriptor-direction pairs. Throws:

• NotSupportedException The data source is not an IBindingListView.

CancelEdit()

Cancels the current edit operation.

Clear()

Removes all elements from the list.

Contains(item)

Determines whether the item is present in he underlying List.

Parameter	Type	Description
item	Object	Item to locate in the underlying List.

Returns: Boolean. true if the item is found in the List.

CopyTo(array, index)

Copies the contents of the List to the specified array , starting at the specified index value.

Parameter	Type	Description
array	Array	The destination array.
index	Int32	The index in the destination array at which to start the copy.

EndEdit()

Applies pending changes to the underlying data source.

When the EndEdit method is called, all pending changes are applied to the underlying data source. This method has no effect unless the objects contained by the data source implement the IEditableObject interface. If the objects do not implement the IEditableObject interface, changes to the data are copied to the underlying data source immediately after each change. This method raises the ListChanged event.

Find(propertyName, value)

Returns the index of the item in the list with the specified propertyName and value .

Parameter	Type	Description
propertyName	String	The name of the property to search.
value	Object	The value of the item with the specified propertyName to find.

Returns: Int32. The zero-based index of the item with the specified propertyName and value .

Throws:

• InvalidOperationException The underlying list is not a IBindingList with searching functionality implemented.

• ArgumentException propertyName does not match a property in the list.

Find(property, value)

Searches for the index of the that has the given value in the specified property .

Parameter	Type	Description
property	PropertyDescriptor	The PropertyDescriptor to search.
value	Object	The value of the property to match.

Returns: Int32. The index of the item that has the given value .

Throws:

• ArgumentException propertyName does not match a property in the list.

GetEnumerator()

Retrieves an enumerator for the underlying List.

Returns: IEnumerator. An IEnumerator for the List.

GetItemProperties(listAccessors)

Retrieves an array of PropertyDescriptor objects representing the bindable properties of the data source list type.

Parameter	Type	Description
listAccessors	PropertyDescriptor[]	An array of PropertyDescriptor objects to find in the List type.

Returns: PropertyDescriptorCollection. An array of PropertyDescriptor objects that represents the properties on this list type used to bind data.

GetListName(listAccessors)

Returns the name of the list supplying data for the binding operations.

Parameter	Type	Description
listAccessors	PropertyDescriptor[]	An array of PropertyDescriptor objects to find in the list as bindable.

Returns: String. The name of the list supplying the data for binding operations.

GetRelatedCurrencyManager(dataMember)

Returns the related CurrencyManager for the specified data member.

Parameter	Type	Description
dataMember	String	The name of column or list, within the data source to retrieve the currency manager for.

Returns: CurrencyManager. The related CurrencyManager for the specified data member.

IndexOf(item)

Returns the index of the specified item in the underlying List.

Parameter	Type	Description
item	Object	item to locate.

Returns: Int32. The index of the first occurrence of item in the List.

Insert(index, item)

Inserts an item into the List at the specified index .

Parameter	Type	Description
index	Int32	Index at which to insert the item.
item	Object	Item to insert, it can be null.

Throws:

• ArgumentOutOfRangeException index is less than zero or greater than Count.

• NotSupportedException The list is read-only or has a fixed size.

MoveFirst()

Moves the current position to the first item in the List.

MoveLast()

Moves the current position to the last item in the List.

MoveNext()

Moves the current position to the next item in the List.

MovePrevious()

Moves the current position to the previous item in the List.

Remove(item)

Removes the specified item from the List.

Parameter	Type	Description
item	Object	Item to remove.

RemoveAt(index)

Removes the item at the specified index from the List.

Parameter	Type	Description
index	Int32	Index of the item to remove.

RemoveCurrent()

Removes the current item from the List.

RemoveFilter()

Removes the filter associated with this BindingSource

RemoveSort()

Removes the sort information associated with this BindingSource.

Throws:

• NotSupportedException The underlying data source does not support sorting.

ResetBindings(metadataChanged)

Causes a control bound to this BindingSource to re-read all the items and refresh their displayed value.

Parameter	Type	Description
metadataChanged	Boolean	true if the schema has changed; false if only the data has changed.

ResetCurrentItem()

Causes a control bound to this BindingSource to re-read the current item and refresh the displayed value.

ResetItem(itemIndex)

Causes a control bound to this BindingSource to read the item at the specified itemIndex and refresh the displayed value.

Parameter	Type	Description
itemIndex	Int32	The index of the item that has changed.

ResumeBinding()

Resumes data binding.

SuspendBinding()

Suspends data binding to prevent changes from updating the data-bound data source.

Events

AddingNew

AddingNewEventHandler Fired before an item is added to the underlying List.

BindingComplete

BindingCompleteEventHandler Fired when all the clients have been bound to this BindingSource.

CurrentChanged

EventHandler Occurs when the currently bound item changes.

CurrentItemChanged

EventHandler Occurs when a property value of the Current property has changed.

DataError

BindingManagerDataErrorEventHandler Fired when a currency-related exception is silently handled by the BindingSource.

DataMemberChanged

EventHandler Fired when the DataMember property value has changed.

DataSourceChanged

EventHandler Fired when the DataSource property value has changed.

ListChanged

ListChangedEventHandler Fired when the underlying List changes or an item in the list changes.

PositionChanged

EventHandler Fired after the value of the Position property has changed.

Implements

Name	Description
ICurrencyManagerProvider	Provides custom binding management for components.