Virtual Mode in the DataRepeater Control (Visual Studio)

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 BeginResetItemTemplate and EndResetItemTemplate 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

  1. 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.

  2. 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.

  3. 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;
            }
        }
    }
    
  4. 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;
        }
    }
    
  5. 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();
        }
    }
    
  6. 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;
    }
    
  7. 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);
    }
    
  8. 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;
        }
    }
    

See Also

ItemValuePushed
NewItemNeeded
ItemValueNeeded
Introduction to the DataRepeater Control