HierarchyPrintOptions.KeyFieldName Property

Specifies the name of the field that stores a data object’s (record’s) ID.

Namespace: DevExpress.XtraReports.UI

Assembly: DevExpress.XtraReports.v24.1.dll

NuGet Package: DevExpress.Reporting.Core

Declaration

C#

[DefaultValue("")]
public string KeyFieldName { get; set; }

VB.NET

<DefaultValue("")>
Public Property KeyFieldName As String

Property Value

Type	Default	Description
String	String.Empty	The name of the field that stores a data object’s (record’s) ID.

Property Paths

You can access this nested property as listed below:

Object Type	Path to KeyFieldName
DetailBand	.HierarchyPrintOptions .KeyFieldName

Remarks

Set the KeyFieldName and ParentFieldName properties if your report’s data has the Id-ParentID related fields.

In the following data object, the RegionID is the Key Field Name:

CountryData.cs

public class CountryData {
    public CountryData(int regionId, int parentRegionId, string region, double area) {
        RegionID = regionId;
        ParentRegionID = parentRegionId;
        Region = region;
        Area = area;
    }
    public int RegionID { get; set; }
    public int ParentRegionID { get; set; }
    public string Region { get; set; }
    public double Area { get; set; }
}

The following code creates the Detail band for the hierarchical report:

C#

using System.ComponentModel;
using System.Drawing;
using System.Windows.Forms;
using DevExpress.Utils;
using DevExpress.Utils.Svg;
using DevExpress.XtraPrinting;
using DevExpress.XtraPrinting.Drawing;
using DevExpress.XtraReports.UI;
// ...
            DetailBand detailBand = new DetailBand() {
                Name = "Detail",
                HeightF = 25,
                EvenStyleName = "EvenStyle",
                Padding = new PaddingInfo(5, 5, 0, 0),
                Font = new Font("Tahoma", 9f),
            };
            // Print root level nodes in bold
            detailBand.ExpressionBindings.Add(new ExpressionBinding("Font.Bold", "[DataSource.CurrentRowHierarchyLevel] == 0"));
            // Sort data on each hierarchy level by the Region field
            detailBand.SortFields.Add(new GroupField("Region", XRColumnSortOrder.Ascending));
            // Specify Id-ParentID related fields
            detailBand.HierarchyPrintOptions.KeyFieldName = "RegionID";
            detailBand.HierarchyPrintOptions.ParentFieldName = "ParentRegionID";
            // Specify the child node offset
            detailBand.HierarchyPrintOptions.Indent = 25;

            // Add an XRCheckBox control as the DetailBand's drill-down control to allow end users to collapse and expand tree nodes
            XRCheckBox expandButton = new XRCheckBox() {
                Name = "DrillDownCheckBox",
                BoundsF = new RectangleF(0, 0, 25, 25),
            };
            expandButton.ExpressionBindings.Add(new ExpressionBinding("Checked", "[ReportItems].[" + detailBand.Name + "].[DrillDownExpanded]"));
            SvgImage checkedSvg = SvgImage.FromResources("CreateHierarchicalReportInCode.Expanded.svg", typeof(ReportCreator).Assembly);
            SvgImage uncheckedSvg = SvgImage.FromResources("CreateHierarchicalReportInCode.Collapsed.svg", typeof(ReportCreator).Assembly);
            expandButton.GlyphOptions.Alignment = HorzAlignment.Center;
            expandButton.GlyphOptions.Size = new SizeF(16, 16);
            expandButton.GlyphOptions.CustomGlyphs[CheckBoxState.Checked] = new ImageSource(checkedSvg);
            expandButton.GlyphOptions.CustomGlyphs[CheckBoxState.Unchecked] = new ImageSource(uncheckedSvg);
            detailBand.DrillDownControl = expandButton;
            detailBand.DrillDownExpanded = false;

            XRLabel regionLabel = new XRLabel() {
                Name = "RegionLabel",
                BoundsF = new RectangleF(25, 0, 450, 25),
                TextAlignment = TextAlignment.MiddleLeft,
                // Anchor the label to both the left and right edges of the DetailBand so that it fits the page's width
                AnchorHorizontal = HorizontalAnchorStyles.Both
            };
            regionLabel.ExpressionBindings.Add(new ExpressionBinding("Text", "[Region]"));
            XRLabel AreaLabel = new XRLabel() {
                Name = "AreaLabel",
                TextFormatString = "{0:N0}",
                BoundsF = new RectangleF(475, 0, 175, 25),
                TextAlignment = TextAlignment.MiddleRight,
                // Anchor the label to the right edge of the DetailBand
                AnchorHorizontal = HorizontalAnchorStyles.Right
            };
            AreaLabel.ExpressionBindings.Add(new ExpressionBinding("Text", "[Area]"));
            detailBand.Controls.AddRange(new XRControl[] { expandButton, regionLabel, AreaLabel });
            return detailBand;
        }
    }

If you specify the KeyFieldName-ParentFieldName property pair, the report’s Detail band is printed in tree mode.

Note

Tree mode is supported for recursive data and data with ID-ParentID related fields. Specify either the ChildListFieldName property or the KeyFieldName- ParentFieldName property pair.

View Example: How to Create a Hierarchical Report in Code