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.
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(ByVal sender As Object, _ ByVal e As System.EventArgs) 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; } }
See Also
Concepts
Introduction to the DataRepeater Control (Visual Studio)
Reference
Change History
Date |
History |
Reason |
---|---|---|
July 2008 |
Added topic. |
SP1 feature change. |