TCnBindingSource Class

Encapsulates the data source for a form.

Namespace: CNClrLib.Component.BindingSource

TComponent
CNClrLib.Control.Base.TClrBaseComponent
CNClrLib.Component.BindingSource.TCnBindingSource

type
 TCnBindingSource = class(TClrBaseComponent)
 end;

The TCnBindingSource type exposes the following members.

Constructors

	Name	Description
	Create(TComponent)	Creates and initializes a TCnBindingSource instance. (Overrides TClrBaseComponent.Create(TComponent).)
	Destroy	Frees the resources allocated with a TCnBindingSource instance. (Overrides TClrBaseComponent.Destroy.)

Top

Properties

	Name	Description
	AllowEdit	Gets a value indicating whether items in the underlying list can be edited.
	AllowNew	Gets or sets a value indicating whether the AddNew() method can be used to add items to the list.
	AllowRemove	Gets a value indicating whether items can be removed from the underlying list.
	BindingDataSet	Gets or sets the dataset that the connector binds to.
	BindingSource	Get the interface of the .Net BindingSource object.
	Count	Gets the total number of items in the underlying list, taking the current Filter value into consideration.
	CurrencyManager	Gets the currency manager associated with this CnBindingSource.
	Current	Gets the current item in the list.
	DataMember	Gets or sets the specific list in the data source to which the connector currently binds to.
	DataSource	Gets or sets the data source that the connector binds to.
	DefaultClrObject	Get the common language runtime object interface for this component. (Inherited from TClrBaseComponent.)
	Filter	Gets or sets the expression used to filter which rows are viewed.
	IsBindingSuspended	Gets a value indicating whether the list binding is suspended.
	IsFixedSize	Gets a value indicating whether the underlying list has a fixed size.
	IsReadOnly	Gets a value indicating whether the underlying list is read-only.
	IsSorted	Gets a value indicating whether the items in the underlying list are sorted.
	IsSynchronized	Gets a value indicating whether access to the collection is synchronized (thread safe).
	Item[Integer]	Gets or sets the list element at the specified index.
	List	Gets the list that the connector is bound to.
	Position	Gets or sets the index of the current item in the underlying list.
	RaiseListChangedEvents	Gets or sets a value indicating whether ListChanged events should be raised.
	Sort	Gets or sets the column names used for sorting, and the sort order for viewing the rows in the data source.
	SortDescriptions	Gets the collection of sort descriptions applied to the data source.
	SortDirection	Gets the direction the items in the list are sorted.
	SortProperty	Gets the PropertyDescriptor that is being used for sorting the list.
	SupportsAdvancedSorting	Gets a value indicating whether the data source supports multi-column sorting.
	SupportsChangeNotification	Gets a value indicating whether the data source supports change notification.
	SupportsFiltering	Gets a value indicating whether the data source supports filtering.
	SupportsSearching	Gets a value indicating whether the data source supports searching with the Find(PropertyDescriptor, OleVariant) method.
	SupportsSorting	Gets a value indicating whether the data source supports sorting.
	SyncRoot	Gets a value indicating whether the data source supports sorting.

Top

Methods

	Name	Description
	Add(Olevariant)	Adds an existing item to the internal list.
	AddNew	Adds a new item to the underlying list.
	ApplySort(_ListSortDescriptionCollection)	Overloaded. Sorts the data source with the specified sort descriptions.
	ApplySort(_PropertyDescriptor,TListSortDirection)	Overloaded. Sorts the data source using the specified property descriptor and sort direction.
	CancelEdit	Cancels the current edit operation.
	Clear	Removes all elements from the list.
	Contains(Olevariant)	Determines whether an object is an item in the list.
	CopyTo(_Array,Integer)	Copies the contents of the List to the specified array, starting at the specified index value.
	Dispose	Releases the resources used by the Component. (Inherited from TClrBaseComponent.)
	DoBindingDataSetInitialize(TObject)	Represents method `DoBindingDataSetInitialize(TObject)`.
	DoGetDefaultClrObject	Represents method `DoGetDefaultClrObject`. (Inherited from TClrBaseComponent.)
	DoGetDotNetBaseComponent	Represents method `DoGetDotNetBaseComponent`. (Overrides TClrBaseComponent.DoGetDotNetBaseComponent.)
	EndEdit	Applies pending changes to the underlying data source.
	Find(String,Olevariant)	Overloaded. Returns the index of the item in the list with the specified property name and value.
	Find(_PropertyDescriptor,Olevariant)	Overloaded. Searches for the index of the item that has the given property descriptor.
	GetClrObject	Represents method `GetClrObject`. (Inherited from TClrBaseComponent.)
	GetEnumerator	Retrieves an enumerator for the List.
	GetItemProperties(_PropertyDescriptorArray)
	GetListName(_PropertyDescriptorArray)
	GetRelatedCurrencyManager(String)	Gets the related currency manager for the specified data member.
	IndexOf(Olevariant)	Searches for the specified object and returns the index of the first occurrence within the entire list.
	Insert(Integer,Olevariant)	Inserts an item into the list at the specified index.
	MoveFirst	Moves to the first item in the list.
	MoveLast	Moves to the last item in the list.
	MoveNext	Moves to the next item in the list.
	MovePrevious	Moves to the previous item in the list.
	Notification(TComponent,TOperation)	Responds to notifications that objects are about to be inserted or removed.
	RegisterEventCallBack(ClrWString,Pointer)	Add an event to the instance using the specified event name and function pointer which is the event handler. The RegisterEventCallBack method does not directly add the event handler to the event. A hooking mechanism is used such that if the event is fired, the hook event is also fired which in turn calls the function pointer. (Inherited from TClrBaseComponent.)
	RegisterEventSource	Register the Delphi object which will raise the .Net event handler. (Inherited from TClrBaseComponent.)
	Remove(Olevariant)	Removes the specified item from the list.
	RemoveAt(Integer)	Removes the item at the specified index in the list.
	RemoveCurrent	Removes the current item from the list.
	RemoveFilter	Removes the filter associated with the BindingSource.
	RemoveSort	Removes the sort associated with the BindingSource.
	ResetAllowNew	Reinitializes the AllowNew property.
	ResetBindings(Boolean)	Causes a control bound to the BindingSource to reread all the items in the list and refresh their displayed values.
	ResetCurrentItem	Causes a control bound to the BindingSource to reread the currently selected item and refresh its displayed value.
	ResetItem(Integer)	Causes a control bound to the BindingSource to reread the item at the specified index, and refresh its displayed value.
	ResumeBinding	Resumes data binding.
	SuspendBinding	Suspends data binding to prevent changes from updating the bound data source.
	UnRegisterEventCallBack(ClrWString,Pointer)	Remove an event from the instance using the specified event name and function pointer which is the event handler. (Inherited from TClrBaseComponent.)
	UnRegisterEventSource	Unregister the Delphi object which raised the .Net event handler. (Inherited from TClrBaseComponent.)

Top

Events

	Name	Description
	OnAddingNew	Occurs before an item is added to the underlying list.
	OnBindingComplete	Occurs when all the clients have been bound to this BindingSource.
	OnCurrentChanged	Get or set the BindingSource CurrentChanged event handler.
	OnCurrentItemChanged	Get or set the BindingSource CurrentItemChanged event handler.
	OnDataError	Occurs when a currency-related exception is silently handled by the BindingSource.
	OnDataMemberChanged	Get or set the BindingSource DataMemberChanged event handler.
	OnDataSourceChanged	Get or set the BindingSource DataSourceChanged event handler.
	OnListChanged	Occurs when the underlying list changes or an item in the list changes.
	OnPositionChanged	Get or set the BindingSource PositionChanged event handler.

Top

Remarks

The CnBindingSource component serves many purposes. First, it simplifies binding .Net controls on a VCL form to data by providing currency management, change notification, and other services between .Net Windows Forms controls and data sources. This is accomplished by attaching the CnBindingSource component to your data source using the DataSource property. For complex binding scenarios you can optionally set the DataMember property to a specific column or list in the data source. You then bind controls to the BindingSource. All further interaction with the data is accomplished with calls to the BindingSource component. Navigation and updating of the data source is accomplished through methods such as MoveNext, MoveLast, and Remove. Operations such as sorting and filtering are handled through the Sort and Filter properties.

In addition, the CnBindingSource component can act as a strongly typed data source. Typically the type of the underlying data source is fixed through one of the following mechanisms:

Use the Add method to add an item to the BindingSource component.
Set the DataSource property to a .Net list, single .Net object, or .Net type.

Both of these mechanisms create a strongly-typed list. For more information on how to use the BindingSource to bind to a type, see How to: Bind a Windows Forms Control to a Type. You can also use the BindingSource to bind your controls to a factory object. For more information on how to do this, see How to: Bind a Windows Forms Control to a Factory Object.

Note
Because a CnBindingSource handles both simple and complex data sources, terminology is problematic. Within this class documentation, the term list refers to a data collection within the hosted data source, and item denotes a single element. When discussing functionality associated with complex data sources, the equivalent terms table and row are used.

CnBindingSource provides members for accessing the underlying data. The current item can be retrieved through the Current property, and the entire list can be retrieved through the List property. Editing operations are supported on the current item through Current and the RemoveCurrent, EndEdit, CancelEdit and Add and AddNew methods. Although currency management is handled automatically for all underlying data source types, this class exposes a number of events, such as OnCurrentItemChanged and OnDataSourceChanged, that allow for customization.

Data sources that are bound to a BindingSource component can also be navigated and managed with the CnBindingSource class, which provides a VCR-like user interface (UI) for navigating items within a list. Although BindingNavigator can be bound to any data source, it was designed to integrate with a BindingSource component through its BindingNavigator.BindingSource property.

The default property for the BindingSource class is DataSource. The default event is OnCurrentChanged.

Caution
Many of the members of the BindingSource class operate on the underlying list represented by the List property and simply refer their operation to the underlying list. Therefore, when the BindingSource is bound to a custom implementation of IList, the exact behavior of these members may differ from the behavior described in the class documentation. For example, the RemoveAt method calls IList.RemoveAt. The BindingSource documentation describes the RemoveAt method with the understanding that the RemoveAt method for he underlying IList is correctly implemented.

Caution

Many of the members of the BindingSource class operate on the underlying list represented by the List property and simply refer their operation to the underlying list. Therefore, when the BindingSource is bound to a custom implementation of IList, the exact behavior of these members may differ from the behavior described in the class documentation. For example, the RemoveAt method calls IList.RemoveAt. The BindingSource documentation describes the RemoveAt method with the understanding that the RemoveAt method for he underlying IList is correctly implemented.

Examples

See C:\Users\Public\Documents\CrystalNet Technologies\.Net VCL for Delphi Demo Folder after installation for examples of how to use this component.

TCnBindingSource Class

Reference