Xceed Toolkit Plus for WPF v4.6 Documentation
Inserting Data
Welcome to Xceed Toolkit Plus for WPF v4.6 > DataGrid, ListBox, Chart, AvalonDock, and PropertyGrid > Datagrid control > Fundamentals > Manipulating Data > Providing, Inserting, and Removing Data > Inserting Data

The DataGridCollectionView and DataGridCollectionViewSource classes expose events (see Table 1) that are triggered during key stages of inserting a new item into an underlying data source. These events provide full control over the insertion process and make it possible to insert items into a source that does not implement the IBindingList interface.

Table 1: Insertion events

Event Description
CreatingNewItem Raised when the AddNew method has been called to signal that a new item is about to be created.
InitializingNewItem Raised after the CreatingNewItem event to allow the new item to be initialized.
NewItemCreated Raised after the CreatingNewItem and InitializingNewItem events to signal that a new item has been created.
CommittingNewItem Raised when the CommitNew method has been called to signal that a new item is about to be committed to the underlying data source.
NewItemCommitted Raised after the CommittingNewItem event to signal that a new item has been committed to the underlying data source.
CancelingNewItem Raised when the CancelNew method has been called to signal that the insertion process of a new item is about to be canceled.
NewItemCanceled Raised after the CancelingNewItem event to signal that the insertion process of a new item has been canceled.

The CreatingNewItem and InitializingNewItem events are raised sequentially by the AddNew method to signal that a new item is about to be created and may need to be initialized. In the CreatingNewItem event, if the insertion of new items is to be handled manually, a new item must be provided and the Handled property set to true to indicate that the process will be handled manually. If a new item is provided but the Handled property was not set or was set to false, the item will be ignored and an attempt will be made by the DataGridCollectionView to create a new item.

If a new item is provided in the CreatingNewItem event, its values can be initialized either there or in the InitializingNewItem event. If the item was automatically created by the DataGridCollectionView, its values can only be initialized in the InitializingNewItem event.

An InvalidOperationException will be thrown if the Handled property is set to true but a new item is not provided.

Once the item has been created and initialized, the NewItemCreated event will be raised to signal that the new item has been created. If the creation of the new item is canceled (e.g., the ESC key is pressed or CancelNew is called), the CancelingNewItem event will be raised followed by the NewItemCanceled event. 

When manually handling the item-insertion process, the ComittingNewItem will be raised by the CommitNew method to signal that the new item is about to be committed to the underlying data source. In this event—not the CreatingNewItem event—the new item can be added to the underlying data source using custom-defined logic. Once the new item is successfully committed to the underlying data source, the Index and NewCount properties received as event parameters must be set to the required values. Regardless, the Handled property must be set to true to indicate that the process was handled (see Example 1).

Manually handling the insertion of new items requires that the CreatingNewItem, CommitingNewItem, and CancelingNewItem events must all be handled; otherwise, an InvalidOperationException will be throw

Examples

All examples in this topic assume that the grid is bound to the Orders table of the Northwind database or a collection of Person objects, unless stated otherwise.

Example 1: Manually handling the insertion process

The following example demonstrates how to manually handle the insertion process of a new item into a collection.

XAML
Copy Code
<Grid xmlns:xcdg="http://schemas.xceed.com/wpf/xaml/datagrid"
     xmlns:local="clr-namespace:Xceed.Wpf.Documentation">
  <Grid.Resources>
    <xcdg:DataGridCollectionViewSource x:Key="cvs_persons"
                                       Source="{Binding Source={x:Static Application.Current},
                                                        Path=PersonList}"
                                       CreatingNewItem="CollectionView_CreatingNewItem"
                                       CommittingNewItem="CollectionView_CommittingNewItem"
                                       CancelingNewItem="CollectionView_CancelingNewItem"/>
  </Grid.Resources>
  <xcdg:DataGridControl x:Name="PersonsGrid"
                        ItemsSource="{Binding Source={StaticResource cvs_persons}}">
     <xcdg:DataGridControl.View>
        <xcdg:TableView>
           <xcdg:TableView.FixedHeaders>
              <DataTemplate>
                 <xcdg:InsertionRow/>
              </DataTemplate>
           </xcdg:TableView.FixedHeaders>
        </xcdg:TableView>
     </xcdg:DataGridControl.View>
  </xcdg:DataGridControl>
</Grid>

The following code provides the implementation of the CreatingNewItem, CommittingNewItem, and CancelingNewItem events.

VB.NET
Copy Code
Private Sub CollectionView_CreatingNewItem( ByVal sender As Object, _
                                            ByVal e As DataGridCreatingNewItemEventArgs )
  e.NewItem = New Person( Person.AutoIncrementID, String.Empty, String.Empty, -1 )
  e.Handled = True
End Sub
Private Sub CollectionView_CommittingNewItem( ByVal sender As Object, _
                                              ByVal e As DataGridCommittingNewItemEventArgs )
  Dim source As List( Of Person ) = CType( e.CollectionView.SourceCollection, List( Of Person ) )
  source.Add( CType( e.Item, Person ) )
  Person.AutoIncrementID = Person.AutoIncrementID + 1
  ' the new item is always added at the end of the list.
  e.Index = source.Count - 1
  e.NewCount = source.Count
  e.Handled = True
End Sub
Private Sub CollectionView_CancelingNewItem( ByVal sender As Object, _
                                             ByVal e As DataGridItemHandledEventArgs )
  ' Manually handling the insertion of new items requires that the CreatingNewItem,
  ' CommitingNewItem, and CancelingNewItem events must all be handled even if nothing
  ' is done in the event.
  e.Handled = True
End Sub
C#
Copy Code
private void CollectionView_CreatingNewItem( object sender, DataGridCreatingNewItemEventArgs e )
{
 e.NewItem = new Person( Person.AutoIncrementID, string.Empty, string.Empty, -1 );
 e.Handled = true;
}
private void CollectionView_CommittingNewItem( object sender, DataGridCommittingNewItemEventArgs e )
{
 List<Person> source = e.CollectionView.SourceCollection as List<Person>;
 source.Add( ( Person )e.Item );
 Person.AutoIncrementID = Person.AutoIncrementID + 1;
 // the new item is always added at the end of the list.    
 e.Index = source.Count - 1;
 e.NewCount = source.Count;
 e.Handled = true;
}
private void CollectionView_CancelingNewItem( object sender, DataGridItemHandledEventArgs e )
{
 // Manually handling the insertion of new items requires that the CreatingNewItem,
 // CommitingNewItem, and CancelingNewItem events must all be handled even if nothing
 // is done in the event.
 e.Handled = true;
}