Walkthrough: Displaying Data in a DataRepeater Control (Visual Studio)

[アーティクル]
11/24/2013

This walkthrough provides a basic start-to-finish scenario for displaying bound data in a DataRepeater control.

Prerequisite

This walkthrough requires the Northwind sample database.

If you do not have this database on your development computer, you can download it from the Microsoft Download Center. For instructions, see Downloading Sample Databases.

Overview

The first part of this walkthrough consists of four main tasks:

Creating a solution.
Adding a DataRepeater control.
Adding a data source.
Adding data-bound controls.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Customizing Development Settings.

Creating a DataRepeater Solution

In the first step, you create a project and solution.

To create a DataRepeater solution

On the Visual Studio File menu, click New Project.
In the Project types pane in the New Project dialog box, expand Visual Basic, and then click Windows.
In the Templates pane, click Windows Forms Application.
In the Name box, type DataRepeaterApp.
Click OK.

The Windows Forms Designer opens.
Select the form in the Windows Forms Designer. In the Properties window, set the Size property to 800, 700.

Adding a DataRepeater Control

In this step, you add a DataRepeater control to the form.

To add a DataRepeater control

On the View menu, click Toolbox.

The Toolbox opens.
Select the Visual Basic PowerPacks tab.
Drag a DataRepeater control onto Form1.
In the Properties window, set the Location property to 0, 25.
Set the Size property to 460, 600.

Adding a Data Source

In this step, you add a data source for the DataRepeater control.

To add a data source

On the Data menu, click Show Data Sources.
In the Data Sources window, click Add New Data Source.
Select Database on the Choose a Data Source Type page, and then click Next.
On the Choose Your Data Connection page, perform one of the following steps:
- If a data connection to the Northwind sample database is available in the drop-down list, click it.
  
  -or-
- Click New Connection to configure a new data connection. For more information, see How to: Create Connections to SQL Server Databases.
If the database requires a password, select the option to include sensitive data, and then click Next.

Note

If a dialog box appears, click Yes to save the file to your project.
Click Next on the Save Connection String to the Application Configuration file page.
Expand the Tables node on the Choose Your Database Objects page.
Select the check boxes next to the Customers and Orders tables, and then click Finish.

NorthwindDataSet is added to your project and the Customers and Orders tables appear in the Data Sources window.

Adding Data-Bound Controls

In this step, you add data-bound controls to the DataRepeater.

To add data-bound controls

In the Data Sources window, select the top-level node for the Customers table.
Change the drop type of the table to Details by clicking Details in the drop-down list on the table node.
Select the Customers table node and drag it onto the item template region (the upper region) of the DataRepeater control.

A BindingNavigator control is added to the form, and the NorthwindDataSet, CustomersBindingSource, CustomersTableAdapter, TableAdapterManager, and CustomersBindingNavigator components are added to the Component Tray.
Select all of the fields and their associated labels and position them near the left edge of the item template region.
Select the last five fields (Region, Postal Code, Country, Phone, and Fax) and their associated labels and move them up and to the right of the first six fields.
Select the item template (the upper region of the control).
In the Properties window, set the Size property to 427, 170.

At this point, you have a working application that will display a repeating list of customers. You can press F5 to run the application, change the data, and add or delete customer records.

In the next optional steps, you will learn how to customize the DataRepeater control.

Next Steps (Optional)

This part of the walkthrough consists of four optional tasks:

Changing the appearance of the DataRepeater control.
Preventing users from adding or deleting records.
Adding search capability to the DataRepeater control.
Adding a master and detail table to the DataRepeater control.

Changing the Appearance of the DataRepeater Control

In this optional step, you change the BackColor of the DataRepeater control at design time. You also add code to display rows in alternating colors and to change a label's ForeColor conditionally.

To change the appearance of the control

In the Windows Forms Designer, select the main (lower) region of the DataRepeater control.
In the Properties window, set the BackColor property to white.
Double-click the DataRepeater to open the Code Editor.
In the Code Editor, in the Event drop-down list, click DrawItem.

In the DrawItem event handler, add the following code to alternate the BackColor:

' Alternate the back color. 
If (e.DataRepeaterItem.ItemIndex Mod 2) <> 0 Then 
    ' Apply the secondary back color.
    e.DataRepeaterItem.BackColor = Color.AliceBlue
Else 
    ' Apply the default back color.
    e.DataRepeaterItem.BackColor = DataRepeater1.BackColor
End If

// Alternate the back color. 
if ((e.DataRepeaterItem.ItemIndex % 2) != 0)
// Apply the secondary back color.
{
    e.DataRepeaterItem.BackColor = Color.AliceBlue;
}
else
{
    // Apply the default back color.
    e.DataRepeaterItem.BackColor = dataRepeater1.BackColor;
}

In the DrawItem event handler, add the following code to change the ForeColor of a label depending on a condition:

If e.DataRepeaterItem.Controls(RegionTextBox.Name).Text = "" Then
    e.DataRepeaterItem.Controls("RegionLabel").
     ForeColor = Color.Red
Else
    e.DataRepeaterItem.Controls("RegionLabel").
     ForeColor = Color.Black
End If

if (e.DataRepeaterItem.Controls[regionTextBox.Name].Text == "")
{
    e.DataRepeaterItem.Controls["regionLabel"].ForeColor = Color.Red;
}
else
{
    e.DataRepeaterItem.Controls["regionLabel"].ForeColor = Color.Black;
}

Press F5 to run the application and see the customizations.

Preventing Users from Adding or Deleting Records

In this optional step, you add code that prevents users from adding or deleting records in the DataRepeater control.

To prevent users from adding and deleting records

In the Windows Forms Designer, double-click the form to open the Code Editor.

Add the following code to the Form_Load event:

DataRepeater1.AllowUserToAddItems = False
DataRepeater1.AllowUserToDeleteItems = False
BindingNavigatorAddNewItem.Enabled = False
CustomersBindingSource.AllowNew = False
BindingNavigatorDeleteItem.Enabled = False

dataRepeater1.AllowUserToAddItems = false;
dataRepeater1.AllowUserToDeleteItems = false;
bindingNavigatorAddNewItem.Enabled = false;
customersBindingSource.AllowNew = false;
bindingNavigatorDeleteItem.Enabled = false;

In the Class Name drop-down list, click BindingNavigatorDeleteItem. In the Method Name drop-down list, click EnabledChanged.
Add the following code to the BindingNavigatorDeleteItem_EnabledChanged event handler:
```
If BindingNavigatorDeleteItem.Enabled = True Then
    BindingNavigatorDeleteItem.Enabled = False 
End If
```
```
if (bindingNavigatorDeleteItem.Enabled == true)
{
    bindingNavigatorDeleteItem.Enabled = false;
}
```
Note

This step is necessary because the BindingSource will enable the DeleteItem button every time that the current record changes.
Press F5 to run the application. Notice that the DeleteItem button is disabled and that you cannot delete items by pressing the DELETE key.

Adding Search Capability to the DataRepeater Control

In this optional step, you implement the capability to search for a value in the DataRepeater control. If the search string is found, the control selects the item that contains the value and scrolls the item into view.

To add search capability

Drag a TextBox control from the Toolbox onto the form that contains the DataRepeater control.

Position it under the DataRepeater control.
In the Properties window, change the Name property to SearchTextBox.
Drag a Button control from the Toolbox onto the form that contains the DataRepeater control. Position it under the DataRepeater control.
In the Properties window, change the Name property to SearchButton. Change the Text property to Search.

Double-click the Button control to open the Code Editor, and add the following code to the SearchButton_Click event handler.

Dim foundIndex As Integer 
Dim searchString As String
searchString = SearchTextBox.Text
' Search for the string in the CustomerID field.
foundIndex = CustomersBindingSource.Find("CustomerID",
 searchString)
If foundIndex > -1 Then
    DataRepeater1.CurrentItemIndex = foundIndex
Else
    MsgBox("Item " & searchString & " not found.")
End If

int foundIndex;
string searchString;
searchString = searchTextBox.Text;
// Search for the string in the CustomerID field.
foundIndex = customersBindingSource.Find("CustomerID", searchString);
if (foundIndex > -1)
{
    dataRepeater1.CurrentItemIndex = foundIndex;
}
else
{
    MessageBox.Show("Item " + searchString + " not found.");
}

Press F5 to run the application. Type a customer ID in SearchTextBox and click the Search button.

Adding a Master and Detail Table to the DataRepeater

In this optional step, you add a second DataRepeater control to display related orders for each customer.

To add a master and detail table

Drag a second DataRepeater control from the Visual Basic PowerPacks tab in the Toolbox onto the form.
In the Properties window, set the Location property to 465, 25.
Set the Size property to 315, 600.
In the Data Sources window, expand the Customers table node and select the detail node for the Orders table.
Change the drop type of this Orders table to Details by clicking Details in the drop-down list on the table node.
Drag this Orders table node onto the item template region (the upper region) of the second DataRepeater control.

An OrdersBindingSource component and an OrdersTableAdapter component are added to the Component Tray.
Press F5 to run the application. When you select each customer in the first DataRepeater control, the orders for that customer are displayed in the second DataRepeater control.