Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Collapse]Data Grid
   [Expand]Getting Started
   [Expand]Data Binding
   [Expand]Views
   [Expand]Data Editing and Validation
   [Expand]Grouping
   [Expand]Sorting
   [Expand]Filter and Search
   [Expand]Summaries
   [Expand]Focus and Selection Handling
    Formatting Cell Values
   [Collapse]Master-Detail Relationships
     Working with Master-Detail Relationships in Code
   [Expand]Asynchronous Image Load
   [Expand]Export and Printing
   [Expand]Appearance and Conditional Formatting
    Split Presentation
    Row Preview Sections
    Scrolling
   [Expand]Batch Modifications
   [Expand]Hit Information
    Hints
   [Expand]Popup Menus
   [Expand]Saving and Restoring Layouts
   [Expand]Visual Elements
   [Expand]Design-Time Features
   [Expand]Examples
   [Expand]End-User Capabilities
    Included Components
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Working with Master-Detail Relationships in Code

Data Binding

Public API

Expanded Binding to a Regular Database at Runtime

The code below illustrates how to bind a Data Grid to a sample MS Access "NorthWind" database with a master GridView and a detail CardView. You can download and review the complete sample project here.

Expanded Binding to Objects with Collection Properties

If the Data Grid is bound to a data source where records provide property (or properties) of the IList type (e.g., ArrayList or List<T>), these collection properties are treated as detail Views unless the GridOptionsDetail.EnableMasterViewMode is explicitly disabled.

Properties of the IList<T>, ICollection<T> and IEnumerable types are not recognized as collection properties by default. To treat them as collection properties, enable the BaseView.DataController.AllowIEnumerableDetails option prior to binding the Data Grid to a data source.

In this example, the Data Grid is bound to an ArrayList object "NestedRecords". Data source entities are objects of the "NestedRecord" class, which provides two properties: a string "Name" and an ArrayList "ChildList". Such a data source is automatically recognized by the Data Grid as a master-detail source.

Expanded Load Details Dynamically by Handling Events

To load details dynamically, rather from a bound source, handle the following events.

Primary Events

  • GridView.MasterRowGetRelationCount
    Fires repeatedly for every row and allows you to specify several details for this row. To identify a row for which the event is raised, read the event's RowHandle parameter. Then, set the RelationCount parameter accordingly to the desired number of detail tables. Occasionally, the Data Grid fires this event with a RowHandle equal to the GridControl.InvalidRowHandle constant. This is a service event that allows you to display or hide all master row expand/collapse buttons. Set the RelationCount to any positive number to show these buttons.
  • GridView.MasterRowEmpty
    Fires for each row that has been marked by the GridView.MasterRowGetRelationCount event as a row that has details. For each of these non-empty rows, the GridView.MasterRowEmpty event fires as many times as the MasterRowGetRelationCount event's RelationCount parameter is. To retrieve the number of the currently processed detail, read the RelationIndex parameter, then set the IsEmpty parameter to a required boolean value. Empty details are not shown.
  • GridView.MasterRowGetRelationName
    This parameter allows you to set the RelationName parameter for each detail. This name is used to retrieve the required pattern View from the GridControl.LevelTree tree. At the same time, the RelationName specifies a default caption for the detail tab.
  • GridView.MasterRowGetChildList
    When the required pattern View is obtained, the Data Grid creates its clone View to display detail data. Set the event's ChildList parameter to provide data to these clones.

Optional Events

Demo: Master-detail mode using events

Expanded Load Details Dynamically by Implementing the IRelationList/IRelationListEx Interfaces

As an alternative to handling View events, you can also implement the IRelationList/IRelationListEx interface for your runtime created data or a .NET data structure (e.g., a System.Data.DataView object). The IRelationList interface provides the following members.

The IRelationListEx interface extends the IRelationList with two additional methods. These allow you to provide different numbers of master-detail relationships for master rows and customize captions for relationships.

The code below demonstrates the IRelationList interface implemented for the NWTables class, which serves as a data source in the Master-Detail (unbound) demo.

Demo: Master-Detail (unbound)

Expanded Access Views

GridControl.MainView
Retrieves the top-level master View.

GridView.GetDetailView
Returns a detail clone View for a specific master row. The example below illustrates how to retrieve the focused cell value for a clone View.


BaseView.ParentView
For clone Views, this property returns a master View. For pattern and main Views, returns null (Nothing in Visual Basic).

GridView.GetVisibleDetailView
Returns a currently visible detail clone for a specific master row.

GridControl.Views
Provides access to master and clone Views that are currently visible. Detail clones are dynamically added to or removed from this collection as details expand or collapse.

GridControl.LevelTree
Provides access to a hierarchical structure that associates pattern Views with master-detail relationships. Hierarchy nodes are represented by the GridLevelNode class objects. The following sample illustrates how to replace a View for a master-detail "Orders" relationship with a new banded View.

Expanded Access Rows

BaseView.SourceRow, BaseView.SourceRowHandle
Returns a row (or its handle) that owns this clone View.

Expanded Expand and Collapse Rows

GridView.ExpandMasterRow, GridView.CollapseMasterRow
Expands or collapses the specific master row.

GridView.GetMasterRowExpanded, GridView.SetMasterRowExpanded
Call these methods to identify whether or not a particular master row is collapsed and expand it manually.

GridView.GetMasterRowExpandedEx, GridView.SetMasterRowExpandedEx
Call these methods to identify whether or not a specific clone of a master row is visible, and if not, show it.

GridView.CollapseAllDetails
Collapses all master rows for a specific View.

Expanded Example 1: Process All Rows

The following example iterates through rows of all master and clone Views. To access clones, master rows must be expanded. After all rows have been processed, their original expand/collapse state is restored.

Expanded Example 2: Recursively Expand a Master Row

This method expands a row and scans for its detail Views. If there are any, they are expanded as well. The process repeats until all underlying details are expanded.

Expanded Example 3: Expand All Master Rows

The Data Grid does not provide a method to expand all master rows for a single View. You can, however, implement such a method yourself.

Expanded See Also

How would you rate this topic?​​​​​​​