Virtual Mode in the DataRepeater Control (Visual Studio)

Artículo
11/24/2013

When you want to display large quantities of tabular data in a DataRepeater control, you can improve performance by setting the VirtualMode property to True and explicitly managing the control's interaction with its data source. The DataRepeater control provides several events that you can handle to interact with your data source and display the data as needed at run time.

How Virtual Mode Works

The most common scenario for the DataRepeater control is to bind the child controls of the ItemTemplate to a data source at design time and allow the BindingSource to pass data back and forth as needed. When you use virtual mode, the controls are not bound to a data source, and data is passed back and forth to the underlying data source at run time.

When the VirtualMode property is set to True, you create the user interface by adding controls from the Toolbox instead of adding bound controls from the Data Sources window.

Events are raised on a control-by-control basis, and you must add code to handle the display of data. When a new DataRepeaterItem is scrolled into view, the ItemValueNeeded event is raised one time for each control and you must supply the values for each control in the ItemValueNeeded event handler.

If data in one of the controls is changed by the user, the ItemValuePushed event is raised and you must validate the data and save it to your data source.

If the user adds a new item, the NewItemNeeded event is raised. Use this event's handler to create a new record in your data source. To prevent unintended changes, you must also monitor the KeyDown event for each control and call CancelEdit if the user presses the ESC key.

If your data source changes, you can refresh the DataRepeater control by calling the BeginResetTemplateItem and EndResetTemplateItem methods. Both methods must be called in order.

Finally, you must implement event handlers for the ItemsRemoved event, which occurs when an item is deleted, and optionally for the UserDeletingItems and UserDeletedItems events, which occur whenever a user deletes an item by pressing the DELETE key.

Implementing Virtual Mode

Following are the steps that are required to implement virtual mode.

To implement virtual mode

Drag a DataRepeater control from the Visual Basic PowerPacks tab in the Toolbox to a form or container control. Set the VirtualMode property to True.
Drag controls from the Toolbox onto the item template region (the upper region) of the DataRepeater control. You will need one control for each field in your data source that you want to display.

Implement a handler for the ItemValueNeeded event to provide values for each control. This event is raised when a new DataRepeaterItem is scrolled into view. The code will resemble the following example, which is for a data source named Employees.

Private Sub DataRepeater1_ItemValueNeeded(
    ByVal sender As Object, 
    ByVal e As Microsoft.VisualBasic.PowerPacks.DataRepeaterItemValueEventArgs
  ) Handles DataRepeater1.ItemValueNeeded
    If e.ItemIndex < Employees.Count Then 
        Select Case e.Control.Name
            Case "txtFirstName"
                e.Value = Employees.Item(e.ItemIndex + 1).firstName
            Case "txtLastName"
                e.Value = Employees.Item(e.ItemIndex + 1).lastName
        End Select 
    End If 
End Sub

private void dataRepeater1_ItemValueNeeded(object sender, Microsoft.VisualBasic.PowerPacks.DataRepeaterItemValueEventArgs e)
{
    if (e.ItemIndex < Employees.Count)
    {
        switch (e.Control.Name)
        {
            case "txtFirstName":
                e.Value = Employees[e.ItemIndex + 1].firstName;
                break;
            case "txtLastName":
                e.Value = Employees[e.ItemIndex + 1].lastName;
                break;
        }
    }
}

Implement a handler for the ItemValuePushed event to store the data. This event is raised when the user commits changes to a child control of the DataRepeaterItem. The code will resemble the following example, which is for a data source named Employees.

Private Sub DataRepeater1_ItemValuePushed(
    ByVal sender As Object, 
    ByVal e As Microsoft.VisualBasic.PowerPacks.DataRepeaterItemValueEventArgs
  ) Handles DataRepeater1.ItemValuePushed

    Dim emp As Employee = Employees.Item(e.ItemIndex)
    Select Case e.Control.Name
        Case "txtFirstName"
            emp.firstName = e.Control.Text
        Case "txtLastName"
            emp.lastName = e.Control.Text
        Case Else
            MsgBox("Error during ItemValuePushed unexpected control: " & 
                e.Control.Name)
    End Select 
End Sub

private void dataRepeater1_ItemValuePushed(object sender, Microsoft.VisualBasic.PowerPacks.DataRepeaterItemValueEventArgs e)
{
    Employee emp = Employees[e.ItemIndex];
    switch (e.Control.Name)
    {
        case "txtFirstName":
            emp.firstName = e.Control.Text;
            break;
        case "txtLastName":
            emp.lastName = e.Control.Text;
            break;
        default:
            MessageBox.Show("Error during ItemValuePushed unexpected control: " + e.Control.Name);
            break;
    }
}

Implement a handler for each child control's KeyDown event and monitor the ESC key. Call the CancelEdit method to prevent the ItemValuePushed event from being raised. The code will resemble the following example.

Private Sub Child_KeyDown(
    ByVal sender As Object, 
    ByVal e As System.Windows.Forms.KeyEventArgs
  ) Handles txtFirstName.KeyDown, txtLastName.KeyDown

    If e.KeyCode = Keys.Escape Then
        Datarepeater1.CancelEdit()
    End If 
End Sub

private void child_KeyDown(object sender, System.Windows.Forms.KeyEventArgs e)
{
    if (e.KeyCode == Keys.Escape)
    {
        this.dataRepeater1.CancelEdit();
    }
}

Implement a handler for the NewItemNeeded event. This event is raised when the user adds a new item to the DataRepeater control. The code will resemble the following example, which is for a data source named Employees.

Private Sub DataRepeater1_NewItemNeeded(
  ) Handles DataRepeater1.NewItemNeeded

    Dim newEmployee As New Employee
    Employees.Add(newEmployee)
    blnNewItemNeedEventFired = True 
End Sub

private void dataRepeater1_NewItemNeeded(object sender, System.EventArgs e)
{
    Employee newEmployee = new Employee();
    Employees.Add(newEmployee);
    blnNewItemNeedEventFired = true;
}

Implement a handler for the ItemsRemoved event. This event occurs when a user deletes an existing item. The code will resemble the following example, which is for a data source named Employees.

Private Sub DataRepeater1_ItemsRemoved(
    ByVal sender As Object, 
    ByVal e As Microsoft.VisualBasic.PowerPacks.DataRepeaterAddRemoveItemsEventArgs
  ) Handles DataRepeater1.ItemsRemoved

    Employees.RemoveAt(e.ItemIndex)
End Sub

private void dataRepeater1_ItemsRemoved(object sender, Microsoft.VisualBasic.PowerPacks.DataRepeaterAddRemoveItemsEventArgs e)
{
    Employees.RemoveAt(e.ItemIndex);
}

For control-level validation, optionally implement handlers for the Validating events of the child controls. The code will resemble the following example.

Private Sub Text_Validating(
    ByVal sender As Object, 
    ByVal e As System.ComponentModel.CancelEventArgs
  ) Handles txtFirstName.Validating, txtLastName.Validating

    If txtFirstName.Text = "" Then
        MsgBox("Please enter a name.")
        e.Cancel = True 
    End If 
End Sub

private void Text_Validating(object sender, System.ComponentModel.CancelEventArgs e)
{
    if (txtFirstName.Text == "")
    {
        MessageBox.Show("Please enter a name.");
        e.Cancel = true;
    }
}

Compartir a través de

Virtual Mode in the DataRepeater Control (Visual Studio)

How Virtual Mode Works

Implementing Virtual Mode

To implement virtual mode

See Also

Reference

Concepts

Recursos adicionales