windowsforms-3473-controls-and-libraries-data-grid-master-detail-relationships.md
The DevExpress WinForms Data Grid control supports master-detail data presentation – with any number of nesting levels and any number of details at each level. Detail views can display any type of information.
Run Demo: Master-Detail Watch Video
Drop the Data Grid control onto a form. Use the Data Grid’s smart tag menu to run the DevExpress Data Source Configuration Wizard.
Important
The DevExpress Data Source Wizard calls the standard Visual Studio Data Source Configuration Wizard that is not available in .NET projects. You should create datasets, binding sources, and table adapters manually (or you can generate them in a .NET Framework project and add to the .NET project).
Important Notes Related to Design-Time Customization in .NET Apps
Click Next to proceed. Select the Orders and Order Details tables. These tables are associated with the “OrderID” key (case sensitive).
Note
You may need to register the Microsoft.ACE.OLEDB.12.0 provider on the local machine.
Bind the Data Grid to a master data table.
Run the application. The expand/collapse buttons are disabled because the detail data is not loaded.
Tip
Use the OptionsDetail.SmartDetailExpandButtonMode property to specify the display of expand/collapse buttons.
Drag the TableAdapter component associated with the detail data table from the Visual Studio toolbox to the design surface.
Load detail data in code:
private void Form1_Load(object sender, EventArgs e) {
// This line is auto-generated by the Data Source Configuration Wizard.
this.ordersTableAdapter.Fill(this.nwindDataSet.Orders);
// Loads detail data.
this.order_DetailsTableAdapter1.Fill(this.nwindDataSet.Order_Details);
}
Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs)
' This line is auto-generated by the Data Source Configuration Wizard.
Me.ordersTableAdapter.Fill(Me.nwindDataSet.Orders)
' Loads detail data.
Me.order_DetailsTableAdapter1.Fill(Me.nwindDataSet.Order_Details)
End Sub
Run the application to see the result. The Data Grid displays both master and detail tables.
Read the following topic for information and examples on how to set up master-detail relations in code: How to Work with Master-Detail Relations in Code.
Click the Retrieve Details button in the Grid’s Level Designer to automatically retrieve detail levels from a data source.
Do the following to create and customize a detail level manually:
Important
The level name must exactly match the name of the master-detail relation.
The following screenshot illustrates the result:
Important
The level name (GridLevelNode.RelationName) must exactly match the name and case of the master-detail relation with which the view is associated. If a detail view displays data from a collection property, the level name must match the collection name.
The Data Grid displays the detail views (relationships) that exist in its GridControl.LevelTree. Disable the grid’s ShowOnlyPredefinedDetails option to display all relations in a data source.
Note
The Data Grid retrieves the detail Views by level names that must match real master-detail relation names (or collection property names, if your pattern Views display collection property data). When you click the “Retrieve Details” button at design time, the level names for all relationships found in a data source are set automatically.
For other cases, specify the valid name through the GridControl.LevelTree collection. Levels with invalid names use master View copies instead of custom Views.
Tip
How to reorder detail tabs in the master-detail view
Views that you assign to detail levels are Pattern Views. The Data Grid dynamically creates a Clone View based on the settings of its pattern view when a user expands a master row (a clone view is a copy of a pattern view).
The following screenshot displays the “Orders - Order Details” relationship. The “cardView1” is a pattern view. The Data Grid uses its settings to create a clone view at runtime when a user expands a master row. The Data Grid destroys the clone view when the user collapses the master row.
Important
Pattern views do not contain any real data. Do not use APIs of pattern views to access columns and rows, get cell values, calculate summaries, etc. Use APIs of clone views to access detail data at runtime.
Use the following methods to obtain views:
sender parameter of Grid Control events.Read the following topic for detailed information and examples: How to Access Detail Views in Code.
Read the following quick-reference guide for general information and examples:
Master-Detail Mode - DevExpress WinForms Cheat Sheet
Use the BaseView.DetailHeight property to set the height of a detail View. For Layout Detail Views, this property specifies the maximum allowed height. A Layout View automatically resizes its height to fit the cards.
The following settings allow you to customize the display of detail views.
Important
The level name must exactly match the name of the master-detail relation with which the view is associated. If a pattern View displays data from a collection property, the level name must match the collection name.
The caption of a detail tab that displays a clone view matches the corresponding level name. If the level name is specified in CamelCase and has no spaces between the words (for example, “ForeignVendorList”), the Data Grid splits the tab caption into separate words (“Foreign Vendor List”).
Use the pattern view’s ViewCaption property to rename detail tabs of its clone views.
cardView1.ViewCaption = "Order Details";
cardView1.ViewCaption = "Order Details"
You can also handle the pattern view’s GridView.MasterRowGetRelationDisplayCaption event to rename tabs of certain clone views based on a condition. Only a GridView and its descendant views (BandedGridView, AdvBandedGridView) can be master views.
The code below handles the MasterRowGetRelationDisplayCaption event to specify custom tab captions.
In the image below, tab captions contain the master row’s Company Name column values.
using DevExpress.XtraGrid.Views.BandedGrid;
private void advBandedGridView1_MasterRowGetRelationDisplayCaption(object sender, MasterRowGetRelationNameEventArgs e) {
AdvBandedGridView view = sender as AdvBandedGridView;
string companyName = (string)view.GetRowCellValue(e.RowHandle, colCompanyName);
if(e.RelationIndex == 1)
e.RelationName = $"{companyName}: Products";
}
Imports DevExpress.XtraGrid.Views.BandedGrid
AddHandler advBandedGridView1.MasterRowGetRelationDisplayCaption, AddressOf advBandedGridView1_MasterRowGetRelationDisplayCaption
Private Sub advBandedGridView1_MasterRowGetRelationDisplayCaption(sender As Object, e As MasterRowGetRelationNameEventArgs)
Dim view As AdvBandedGridView = TryCast(sender, AdvBandedGridView)
Dim companyName = CStr(view.GetRowCellValue(e.RowHandle, colCompanyName))
If e.RelationIndex = 1 Then e.RelationName = $"{companyName}: Products"
End Sub
You can enable the master view’s AllowHtmlDrawDetailTabs option to parse HTML-inspired tags in detail tab captions.
The DetailTabStyle event fires for each detail view. This event allows you to assign a custom image to the processed tab and apply custom appearance settings to the tab caption.
Use the Caption event argument to obtain or change the processed tab caption. The following arguments allow you to specify the tab style:
You can also use the IsSelected argument to apply a specific style depending on whether the tab is selected.
The RefreshDetailTab(Int32) method allows you to update a detail tab at runtime.
Each view can display a scrollbar (in Classic mode). Use the DetailMode property to switch to Embedded mode. In this mode, the Data Grid displays a single scroll bar for the master and clone views.
The expand buttons displayed in master rows can display tooltips that contain links. Users can click these links to expand certain clone views. This can be useful when detail tabs are hidden. Use the GridOptionsDetail.ShowDetailTabs option to show/hide detail tabs.
Use the GridOptionsDetail.EnableDetailToolTip property to enable/disable detail tooltips.
Run Demo: Master-Detail (advanced)
Use the following settings to configure the display and behavior of detail expand buttons:
How to: Hide Expand Buttons for Master Rows with Empty Details
Use the parent view’s GridView.ExpandMasterRow and GridView.CollapseMasterRow methods to expand/collapse the specified master row. The CollapseAllDetails() method collapses all master rows in a view. You can also use the SetMasterRowExpanded method to expand/collapse a master row.
Handle the MasterRowExpanding and MasterRowCollapsing events to prevent the user from expanding/collapsing specific master rows.
Read the following topic for additional information: Working with Master-Detail Relationships in Code.
Enable the pattern view’s SynchronizeClones option to synchronize its clone views. When a user groups data, resizes a column, or performs any other operation that changes a clone view, the Data Grid applies the same changes to all clone views of the corresponding pattern view.
Run Demo: Master-Detail (advanced)
Enable the GridOptionsView.ShowChildrenInGroupPanel option to use a joint group panel for master and detail views.
Master-detail grouping requires that Clone View Synchronization is enabled. Use the master view’s ChildGridLevelName property to specify the name of the detail level.
Run Demo: Master-Detail Grouping
If the root master view’s AllowZoomDetail option is enabled, its detail views display the Zoom button. Users can click this button to maximize detail views.
Use the ZoomView() and NormalView() methods to zoom into or out of detail views.
Use the Data Grid’s DefaultView property to get the currently maximized detail view. The Data Grid raises the DefaultViewChanged event when a user zooms into or out of a detail view.
The following example maximizes the first detail view for the focused master row, processes it, and zooms out of the detail view.
using DevExpress.XtraGrid.Views.Grid;
using DevExpress.XtraGrid.Views.Base;
// ...
GridView View = gridControl1.FocusedView as GridView;
if(View.IsMasterRow(View.FocusedRowHandle)) {
int detailIndex = 0;
View.SetMasterRowExpandedEx(View.FocusedRowHandle, detailIndex, true);
ColumnView childView = (ColumnView)View.GetDetailView(View.FocusedRowHandle, detailIndex);
if(childView != null) {
// Zooms into the detail view.
childView.ZoomView();
// Do something.
// ...
// Zooms out of the detail view.
childView.NormalView();
}
}
Imports DevExpress.XtraGrid.Views.Grid
Imports DevExpress.XtraGrid.Views.Base
Dim View As GridView = gridControl1.FocusedView
If (View.IsMasterRow(View.FocusedRowHandle)) Then
Dim detailIndex As Integer = 0
View.SetMasterRowExpandedEx(View.FocusedRowHandle, detailIndex, True)
Dim childView As ColumnView = View.GetDetailView(View.FocusedRowHandle, detailIndex)
If Not childView Is Nothing Then
' Zooms into the detail view.
childView.ZoomView()
' Do something.
' ...
' Zooms out of the detail view.
childView.NormalView()
End If
End If
The following example zooms into and out of detail views with the CTRL+Left Arrow and CTRL+Right Arrow shortcuts:
private void gridControl1_ProcessGridKey(object sender, System.Windows.Forms.KeyEventArgs e) {
if(e.Control) {
if(e.KeyCode == Keys.Right) {
gridControl1.FocusedView.ZoomView();
e.Handled = true;
}
else if(e.KeyCode == Keys.Left) {
gridControl1.DefaultView.NormalView();
e.Handled = true;
}
}
}
Private Sub gridControl1_ProcessGridKey(ByVal sender As Object, ByVal e As KeyEventArgs) _
Handles gridControl1.ProcessGridKey
If e.Control Then
If e.KeyCode = Keys.Right Then
gridControl1.FocusedView.ZoomView()
e.Handled = True
ElseIf e.KeyCode = Keys.Left Then
gridControl1.DefaultView.NormalView()
e.Handled = True
End If
End If
End Sub
Run Demo: Master-Detail (advanced)
Set the view’s OptionsPrint.PrintDetails property to true to print expanded details.
Enable the OptionsPrint.ExpandAllDetails option to print/export the Grid Control with all master rows expanded.
Set the master view’s EnableMasterViewMode property to false to disable the Master-Detail mode.
Read the following topic for information and examples: Working with Master-Detail Relationships in Code.
GridView and its descendant views (BandedGridView and AdvBandedGridView) can be master views.See Also
Working with Master-Detail Relationships in Code
What Can Cause Properties, Methods, and Events of a Detail View to Fail?