GridControl.LevelTree Property

Provides access to a hierarchical structure that associates pattern Views with specific master-detail relationships.

Namespace: DevExpress.XtraGrid

Assembly: DevExpress.XtraGrid.v24.1.dll

NuGet Packages: DevExpress.Win.Grid, DevExpress.Win.Navigation

Declaration

C#

[Browsable(false)]
public GridLevelTree LevelTree { get; }

VB.NET

<Browsable(False)>
Public ReadOnly Property LevelTree As GridLevelTree

Property Value

Type	Description
GridLevelTree	A GridLevelTree object that associates pattern Views with specific master-detail relationships.

Remarks

The LevelTree property can be used to associate pattern Views (these are used as templates when creating detail Views at runtime) with specific master-detail relationships.

The LevelTree represents a tree-like structure, its nodes define grid levels. All nodes (except for the root node) associate specific master-detail relationships (given by their names) with pattern Views. A node’s RelationName and LevelTemplate properties specify the relationship’s name and pattern View respectively.

The root grid level in the LevelTree always refers to the GridControl.MainView View (the node’s LevelTemplate and GridControl.MainView properties’ values match). The main View is used to display top-level data in the master-detail hierarchy.

The nesting level of a specific node in the LevelTree should match the nesting level of the corresponding master-detail relationship in the grid’s data source.

At runtime, when a specific relationship (detail View) should be displayed, the Grid Control calculates the nesting level of this relationship. It then searches the LevelTree at this nesting level for the node whose RelationName matches the name of the required relationship. If such a node is found its LevelTemplate property defines the pattern View for representing the processed relationship. If such a node is not found the GridControl.ShowOnlyPredefinedDetails property will control what happens:

• if the GridControl.ShowOnlyPredefinedDetails property is set to false (the default value) the pattern View which represents the required detail will be created based upon the master view;
• if the GridControl.ShowOnlyPredefinedDetails property is set to true the processed relationship is forbidden from being displayed. When this option is enabled only the relationships that have entries in the LevelTree can be displayed in the XtraGrid. Other relationships are not displayed.

The grid’s Level Designer represents the hierarchy of the LevelTree‘s nodes in visual form. Clicking its Retrieve Details button creates grid levels for all the master-detail relationships found in the bound data source (this is in effect for a DataTable data source). The level designer can then be used to assign pattern Views to particular relationships.

See the Master-Detail Relationships topic for more information on the hierarchical data representation.

Example

Assume that a grid control displays a master-detail relationship between two tables. The relationship is named “Orders”. The following example shows how to replace the existing View representing the “Orders” relationship with a new banded View.

First a node within the GridControl.LevelTree representing the “Orders” relationship is located. The existing View is disposed of and a new banded View is then assigned to this relationship.

C#

using DevExpress.XtraGrid;
using DevExpress.XtraGrid.Views.Base;
using DevExpress.XtraGrid.Views.Grid;
using DevExpress.XtraGrid.Views.BandedGrid;

// Collapse all the details opened for the master rows in the main view.
(gridControl1.MainView as GridView).CollapseAllDetails();

// Get the node at the first nesting level that stores a view for the "Orders" relation.
GridLevelNode node = gridControl1.LevelTree.Nodes["Orders"];
if(node == null) return;
// The old view which represents the "Orders" relation.
BaseView oldView = node.LevelTemplate;         
// Dispose of this view.
oldView.Dispose();

// Create a new view.
BandedGridView bandedView = new BandedGridView(gridControl1);            
// Associate this view with the "Orders" relation.
node.LevelTemplate = bandedView;

// Customize the new view.
GridBand band = bandedView.Bands.Add("Orders");
BandedGridColumn column = (BandedGridColumn)bandedView.Columns.Add("ID");
column.OwnerBand = band;
column.Visible = true;

column = (BandedGridColumn)bandedView.Columns.AddField("ProductID");
column.OwnerBand = band;
column.Visible = true;

VB.NET

Imports DevExpress.XtraGrid
Imports DevExpress.XtraGrid.Views.Base
Imports DevExpress.XtraGrid.Views.Grid
Imports DevExpress.XtraGrid.Views.BandedGrid

' Collapse all the details opened for the master rows in the main view.
CType(GridControl1.MainView, GridView).CollapseAllDetails()

' Get the node at the first nesting level that stores a view for the "Orders" relation.
Dim node As GridLevelNode = GridControl1.LevelTree.Nodes("Orders")
If node Is Nothing Then Return
' The old view which represents the "Orders" relation.
Dim oldView As BaseView = node.LevelTemplate
' Dispose of this view.
oldView.Dispose()

' Create a new view.
Dim bandedView As BandedGridView = New BandedGridView(GridControl1)
' Associate this view with the "Orders" relation.
node.LevelTemplate = bandedView

' Customize the new view.
Dim band As GridBand = bandedView.Bands.Add("Orders")
Dim column As BandedGridColumn = bandedView.Columns.Add("ID")
column.OwnerBand = band
column.Visible = True

column = bandedView.Columns.AddField("ProductID")
column.OwnerBand = band
column.Visible = True