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]Binding to Data
   [Expand]Grid View
   [Expand]View Technology
   [Expand]Grouping
   [Expand]Sorting
   [Expand]Summaries
   [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
    [Expand]Binding to Data Specifics
    [Expand]View Specifics
    [Collapse]Row Specifics
      Expanding and Collapsing Master Rows
      Navigating Through Master and Detail Rows
   [Expand]Asynchronous Image Load
   [Expand]Export and Printing
   [Expand]Appearance and Conditional Formatting
   [Expand]Batch Modifications
   [Expand]Hit Information
   [Expand]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]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]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Expanding and Collapsing Master Rows

To access child data when in master-detail mode, an end-user expands a master row by pressing its expand button. This opens a detail View that represents a specific master-detail relationship. If the master row has several details, you can allow the end-user to switch between them by using detail tabs or detail tooltips. This topic describes the methods provided by XtraGrid for collapsing and expanding master rows and opening specific details (detail Views). It contains the following sections.

 

Expanded Expanding/Collapsing Particular Master Rows

The methods used to expand/collapse master rows require row handles as parameters. Row handles represent unique integer values and these identify rows in a Grid View.

In master-detail mode, a master Grid View can display the following row types: master rows, group rows, new item row and auto filter row. To determine if a row is a master row, use the GridView.IsMasterRow method.

Each master row can have multiple master-detail relationships, and each is displayed within a corresponding detail View. Only one detail View of a master row can be displayed at one time. When expanding a row by clicking its expand button, the grid does the following.
  1. Determines which master-detail relationship is the default one.

    The default master-detail relationship is identified by the GridView.DefaultRelationIndex property, which specifies the zero-based index of a specific relationship among other relationships. By default, this property is set to 0.

  2. Checks whether or not the default detail (the detail that corresponds to the default master-detail relationship) contains data.

    If the detail doesn't contain any records, and the GridOptionsDetail.AllowExpandEmptyDetails property is set to true, the grid will allow you to expand this detail. Otherwise, the grid control will try to locate the first non-empty detail and will then expand it. Note that by default, empty details are not expanded.

    Note

    When populating a grid with data in a master-detail mode by using events, you need to handle the GridView.MasterRowEmpty event to provide information on whether a specific detail is empty.

  3. Creates and displays a detail View to represent the required detail data.

When an end-user collapses a row, all detail Views open for that row are destroyed.

To expand and/or collapse master rows by using code, the following methods can be used.

These methods provide a number of overloads that can be used to open or close the default or specific detail for the required master row.

A detail View can be identified by the index or name of the associated master-detail relationship. The relationship's index is a value between 0 and GridView.GetRelationCount - 1. To get the relationship's name by its index, use the GridView.GetRelationName method. The GridView.GetRelationIndex performs the opposite operation.

To get the current expansion status of the row, call the GridView.GetMasterRowExpanded or GridView.GetMasterRowExpandedEx method.

Expanded Example 1

The following code toggles the expansion status of the focused row in the currently focused View.

 

The following table details possible situations in which the GridView.ExpandMasterRow, GridView.SetMasterRowExpanded or GridView.SetMasterRowExpandedEx method is called to open a specific detail.
The original state Result
The master row is collapsed initially. The method expands the master row, creates the specified detail View and makes it visible.
The master row is expanded initially. If the specified detail View does not exist, this method creates it and then displays it in the detail section. Otherwise, this method simply switches focus to it.

The following table details the possible situations in which the GridView.CollapseMasterRow, GridView.SetMasterRowExpanded or GridView.SetMasterRowExpandedEx method is called to close a specific detail View.

The original state Result
The specified detail View does not exist or the master row is collapsed. The method does nothing.
Only the detail View specified exists for the row. All other detail Views were either not open or were destroyed. The method collapses the row.
Several detail Views exist for the row, including the one specified. The method destroys the specified View and switches focus to the first available View.

 

To retrieve the index of the open detail View, use the GridView.GetVisibleDetailRelationIndex method. The detail View itself can be obtained by using the GridView.GetVisibleDetailView method. It is possible to access a detail View (not only the one open) by using the GridView.GetDetailView method. Note that this method only works if the detail View you need to reference exists. This method returns null if the specified detail View does not exist. This can be the case if:

  • it has been destroyed in code (for instance, the GridView.CollapseMasterRow method was called with the relationName parameter referring to this detail);
  • this detail has been destroyed as a result of the master row being collapsed by an end-user;
  • this detail hasn't been opened yet (for instance, if the master row has been expanded with another detail opened).

Expanded Example 2

The following example shows how you can expand a master row recursively. The RecursExpand method iterates through the master-detail relationships and opens corresponding detail Views. If the opened detail View has master-detail relationships, its child rows are expanded as well, etc.

 

By default, if the master row details don't contain data, the row cannot be expanded. To allow empty details to be opened, set the GridOptionsDetail.AllowExpandEmptyDetails property to true. The GridView.IsMasterRowEmptyEx method returns whether or not a specific detail View contains data.

Expanded Expanding/Collapsing All The Master Rows

To collapse all the master rows for a particular View, you can use the GridView.CollapseAllDetails method. All the detail Views will be destroyed.

XtraGrid does not provide a method to expand all the master rows for a single View. You can, however, write a procedure as follows.

Note that the BaseView.BeginUpdate and BaseView.EndUpdate methods are used to prevent excessive visual updating when expanding master rows. For more information, refer to the Batch Modifications Overview document.

The ExpandAllRows method may take some time, especially if the View and its open child Views contain a lot of data.

Expanded Events

Before a master row is expanded, the grid generates the GridView.MasterRowExpanding event. This also occurs before a detail View is displayed in the detail section as a result of switching to it by using detail tabs, detail tooltips or in code. This event provides the Allow parameter, which you can use to prevent the detail View from being displayed on screen. Other parameters of this event identify the master row and detail the affected View.

If you need to perform actions only when the detail View is created (not when it regains focus), you can handle the GridControl.ViewRegistered event.

After a detail View is displayed, the GridView.MasterRowExpanded event is fired. This event serves only as a notification.

The GridView.MasterRowCollapsing event is fired when an attempt is made to collapse a master row, or destroy a detail View by using the GridView.SetMasterRowExpandedEx or GridView.CollapseMasterRow methods. The event's Allow parameter allows you to cancel the action. The RelationIndex parameter identifies the detail View being closed. If the RelationIndex is set to -1, it is assumed that the entire master row is about to be collapsed and all its detail Views are to be destroyed.

After a master row has been collapsed or after a detail View has been destroyed, the notification GridView.MasterRowCollapsed event is fired.

To react to a particular detail View being destroyed, you can handle the GridControl.ViewRemoved event.

Expanded See Also

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