Log In
[Expand]General Information
[Collapse]WinForms Controls
 [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]Binding to Data
   [Expand]Grid View
   [Expand]View Technology
   [Expand]Data Editing
   [Expand]Filtering and Locating Rows
   [Expand]Focus and Selection Handling
   [Expand]Processing Rows
   [Expand]Formatting Cell Values
   [Collapse]Master-Detail Relationships
     Master-Detail Overview
    [Collapse]Binding to Data Specifics
      Master-Detail: DataTable Use
      Master-Detail: Using Events
      Master-Detail: Implementing Master-Detail Relationships for Custom Objects
      Implement Master-Detail Relationships for Objects Using the IRelationList Interface
      Implement Master-Detail Relationships for Objects via Collection Properties
    [Expand]View Specifics
    [Expand]Row Specifics
   [Expand]Asynchronous Image Load
   [Expand]Export and Printing
   [Expand]Appearance and Conditional Formatting
   [Expand]Batch Modifications
   [Expand]Hit Information
   [Expand]Popup Menus
   [Expand]Saving and Restoring Layouts
   [Expand]Visual Elements
   [Expand]Design-Time Features
   [Expand]End-User Capabilities
    Included Components
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Map Control
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]PDF Viewer
  [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]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Report Server
[Expand]eXpressApp Framework
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Master-Detail: Using Events

Grid Control provides events for dynamically loading detail data for implementing master-detail relationships. This topic provides information on this functionality. Dynamic detail loading can be used regardless of the data source type. Alternatively, you can implement it by supporting the IRelationList interface for your data source. Refer to the Master-Detail: Implementing Master-Detail Relationships for Custom Objects topic for more information.

If your data source represents a System.Data.DataTable object, you can implement master-detail relationships using methods provided by the data source. In this case, however, master and detail data always reside in memory. Loading details dynamically may improve your application's performance.

You can use the detail's dynamic loading events and the data source's methods simultaneously to set up master-detail relationships. In this case, the events allow you to override the data source's master-detail settings.

The Master-Detail Overview document provides general information on methods for implementing master-detail mode.

Grid Control displays data using views technology. For information on Views in master-detail mode, see the Detail Pattern and Clone Views topic.

Expanded Dynamic Events for Detail Loading

Events provided by Grid Control for dynamic detail loading allow you to implement master-detail relationships of any complexity. For instance, you can implement the following tasks:

  • Specify a different number of master-detail relationships and therefore details for master rows;
  • Use different Views for representing the details that belong to different master rows but correspond to the same relationship;
  • Control whether or not details can be currently displayed, etc.
The mechanism of dynamic detail loading is based on the following events.
  • GridView.MasterRowGetRelationCount. Handle the event to specify the number of master-detail relationships for each master row. The master row handle is identified by the event's RowHandle parameter. The relation count must be set via the RelationCount parameter. When other dynamic detail loading events are fired, they obtain the RelationIndex parameter which refers to the current detail. The parameter's value varies from 0 to RelationCount - 1.

    The grid control also fires the MasterRowGetRelationCount event with the RowHandle set to the GridControl.InvalidRowHandle field value. If the RelationCount parameter is set to a positive value, Grid View will display master-detail expand buttons. Otherwise, expand buttons will be hidden. Details can still be expanded in this case via code or by double-clicking the row indicator panel's cell.

  • GridView.MasterRowEmpty. Handle the event to specify whether or not the current detail has data. The detail is identified by the master row handle and relation index. If a detail does not contain data, it cannot be opened.

    In some cases, you may want to hide a particular detail. For this purpose, you can set the event's IsEmpty parameter to true, even if the detail contains data.

    The grid, however, allows empty details to be opened if the GridOptionsDetail.AllowExpandEmptyDetails property is set to true. This can be useful to allow the end-user to add new records to empty details.
  • GridView.MasterRowGetChildList. Handle the event to provide data for the current detail. The detail is identified by the master row handle and relation index.
  • GridView.MasterRowGetRelationName. Handle the event to provide a name for the current relation (detail).

    The name supplied is used in several cases. First, it is used to get the default pattern view associated with a specified relationship name, and this will be used as a template for creating a real detail View (clone). The required pattern View is retrieved from the GridControl.LevelTree tree, which associates particular pattern Views with relationships. It is possible to override the pattern View chosen by default by handling the GridView.MasterRowGetLevelDefaultView event.

    Secondly, the name of the relationship is used by default as the display name for that detail. This is displayed in the corresponding detail tab and within a detail tooltip. To customize this display caption, the pattern View's BaseView.ViewCaption property or the master View's GridView.MasterRowGetRelationDisplayCaption event can be used.

  • GridView.MasterRowGetRelationDisplayCaption. Handle the event to provide a display caption for a specific relationship.

    If the GridView.MasterRowGetRelationName event is handled, the name supplied via the event's RelationName parameter serves as the default display caption for the processed relationship. It is also possible to customize the display caption via the BaseView.ViewCaption property of the pattern View that represents this relationship.

    The name supplied via the GridView.MasterRowGetRelationDisplayCaption event has the highest priority.

  • GridView.MasterRowGetLevelDefaultView. Handle the event to explicitly provide a pattern View for representing the current detail. Generally, you need to handle the event if the pattern View required does not belong to the GridControl.LevelTree tree. Otherwise, in most cases, you can provide the pattern View indirectly via the GridView.MasterRowGetRelationName event.
Additionally, you can handle the GridView.MasterRowExpanding event to prevent a detail from opening.

Expanded Example

The following example from the GridUnboundMasterViewDynamic tutorial illustrates how to implement master-detail relationships using dynamic detail loading events.

The grid's bound data source represents an ArrayList containing three Record objects. Each Record object exposes the public Name property initialized in the class constructor.

These records should be displayed as master rows in a grid control and provide access to detail data. The first row has three details ("Products", "Customers" and "Shippers"). The third row has only one detail ("Employees"). The second row will not display any detail for demonstration purposes.

A two-dimensional array is declared to identify the details available for each row. Each element defines a relationship name for a specific row and detail index (the maximum detail number in our case is 3).

The following code shows the event handlers that implement master-detail relationships as described above.

Child data for Products, Customers, Shippers and Employees relationships is represented by the custom ChildRecordsProducts, ChildRecordsCustomers, ChildRecordsShippers and Records classes respectively. See the tutorial project for the classes implementation.

The Views for representing relationships are determined implicitly based on the relation name retrieved via the GridView.MasterRowGetRelationName event handler. In the tutorial, pattern Views are created and associated with relationships' names at design time using the Level Designer:

Notice that the Level Designer defines pattern Views for the Employees, Products and Customers relationships. There is no pattern View for the Shippers relationship. Its details will be created based on the master View (gridView1) settings.

To get information on assigning Views to relationships via code, see the example in the Master-Detail: DataTable Use section, for instance. The following image shows a detail Card View representing the Products relation for the first master row.

The Shippers relationship is represented by a Grid View.

Expanded See Also

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