Tutorial: Banded Grid View - API

• Dec 19, 2022
• 7 minutes to read

This walkthrough is a transcript of the Banded Grid View - API video available on the DevExpress YouTube Channel.

In this tutorial, you will learn how to create a banded and advanced banded layout in code. You’ll start with switching the main View to the required type. Then, you’ll create first-level bands and their child bands to create a hierarchy. After bands are initialized, you will create columns and link them to parent bands. Finally, you’ll switch to the Advanced Banded Grid View where you will move columns to the second row and let column headers fill the empty space under them.

Starting Point

Start with the application that has a Grid Control bound to a Car database.

Switching to the Banded Grid View

The Create Banded Layout button in the Ribbon control will initiate the code that switches the layout to the Banded View. In the Click event handler, create a BandedGridView instance, disable its ColumnViewOptionsBehavior.AutoPopulateColumns option and assign the resulting object to the grid’s GridControl.MainView property.

C#

private void btnCreateBandedLayout_ItemClick(object sender, ItemClickEventArgs e) {
    // Switch to the Banded Grid View. 
    BandedGridView view = new BandedGridView();
    view.OptionsBehavior.AutoPopulateColumns = false;
    gridControl1.MainView = view;
}

Run the application and click the Create Banded Layout button. As you can see, the layout switched, but the newly created View is empty since automatic column generation was disabled.

Creating Top-Level Bands

Close the application and return to the handler code. Create the GridBand instances to add the Main, Performance Attributes and Notes bands at the top hierarchical level. Add the objects to the View’s BandedGridView.Bands collection.

C#

private void btnCreateBandedLayout_ItemClick(object sender, ItemClickEventArgs e) {
    // ...
    // Create top-level bands.  
    GridBand bandMain = new GridBand() { Name = "bandMain", Caption = "Main" };
    GridBand bandPerformanceAttributes = new GridBand() { Name = "bandPerformance", Caption = "Performance Attributes" };
    GridBand bandNotes = new GridBand() { Name = "bandNotes", Caption = "Notes" };
    view.Bands.AddRange(new GridBand[] { bandMain, bandPerformanceAttributes, bandNotes });
}

Run the application, click the button and now the View will have the bands displayed.

Creating Nested Bands

This time, create nested bands. To do this, create new band objects and add them to the Main band’s GridBand.Children collection.

C#

private void btnCreateBandedLayout_ItemClick(object sender, ItemClickEventArgs e) {
    // ...
    // Create nested bands.
    GridBand bandModel = new GridBand { Name = "bandModel", Caption = "Model" };
    GridBand bandPrice = new GridBand { Name = "bandPrice", Caption = "Price" };
    bandMain.Children.AddRange(new GridBand[] { bandModel, bandPrice });
}

Run the application and click the button to see the new hierarchical band structure.

Creating Banded Columns

Return to the click handler code and create columns represented by BandedGridColumn objects. Initialize their GridColumn.FieldName properties and make them visible. Add created columns to the View’s BandedGridView.Columns collection.

Format the Price column values as currency using the GridColumn.DisplayFormat property.

C#

private void btnCreateBandedLayout_ItemClick(object sender, ItemClickEventArgs e) {
    // ...
    // Create banded grid columns and make them visible.
    BandedGridColumn colTrademark = new BandedGridColumn() { Name = "colTrademark", FieldName = "Trademark", Visible = true };
    BandedGridColumn colModel = new BandedGridColumn() { Name = "colModel", FieldName = "Model", Visible = true };
    BandedGridColumn colCategory = new BandedGridColumn() { Name = "colCategory", FieldName = "Category", Visible = true };
    BandedGridColumn colPrice = new BandedGridColumn() { Name = "colPrice", FieldName = "Price", Visible = true };
    BandedGridColumn colHP = new BandedGridColumn() { Name = "colHP", FieldName = "HP", Visible = true };
    BandedGridColumn colLiter = new BandedGridColumn() { Name = "colLiter", FieldName = "Liter", Visible = true };
    BandedGridColumn colCyl = new BandedGridColumn() { Name = "colCyl", FieldName = "Cyl", Visible = true };
    BandedGridColumn colDescription = new BandedGridColumn() { Name = "colDescription", FieldName = "Description", Visible = true };
    BandedGridColumn colPicture = new BandedGridColumn() { Name = "colPicture", FieldName = "Picture", Visible = true };
    view.Columns.AddRange(new BandedGridColumn[] { colTrademark, colModel, colCategory, colPrice, colHP, colLiter, colCyl, colDescription, colPicture });

    // Format the Price column values as currency.
    colPrice.DisplayFormat.FormatType = DevExpress.Utils.FormatType.Numeric;
    colPrice.DisplayFormat.FormatString = "c2";
}

Run the app and click the button again. As you can see, columns are not displayed within the View and that’s because they haven’t been linked to bands yet.

Assigning Columns to Bands

To add a column to a band, set the columns’ BandedGridColumn.OwnerBand property.

C#

private void btnCreateBandedLayout_ItemClick(object sender, ItemClickEventArgs e) {
    // ...
    // Assign columns to bands.  
    colTrademark.OwnerBand = bandModel;
    colModel.OwnerBand = bandModel;
    colCategory.OwnerBand = bandModel;
    colPrice.OwnerBand = bandPrice;
    colHP.OwnerBand = bandPerformanceAttributes;
    colLiter.OwnerBand = bandPerformanceAttributes;
    colCyl.OwnerBand = bandPerformanceAttributes;
    colDescription.OwnerBand = bandNotes;
    colPicture.OwnerBand = bandNotes;
}

Run the application, click the buttons and see that columns are now visible under their corresponding bands.

Switching to the Advanced Banded Grid View

Return to code and modify the handler so that it creates an Advanced Banded Grid View instead of a standard Banded Grid View. You will simply have to use a different class for the view. The rest of the code will continue working.

C#

private void btnCreateBandedLayout_ItemClick(object sender, ItemClickEventArgs e) {
    // Switch to the Advanced Banded Grid View. 
    AdvBandedGridView view = new AdvBandedGridView();
    view.OptionsBehavior.AutoPopulateColumns = false;
    gridControl1.MainView = view;
   // ...
}

Run the application. The layout is the same as before, only the Column Auto Width feature is now disabled.

Arranging Columns into Multiple Rows

Close the application and arrange column headers into multiple rows. To display the Category and Liter columns under other columns within their parent bands, set their BandedGridColumn.RowIndex property to 1.

C#

private void btnCreateBandedLayout_ItemClick(object sender, ItemClickEventArgs e) {
    // ...
    // Set the vertical position of column headers.
    colCategory.RowIndex = 1;
    colLiter.RowIndex = 1;
}

Run the application again. You can see the change, but now empty spaces appear under certain column headers.

Automatically Stretching Column Headers

To automatically modify the height of column headers to fill empty spaces, enable their BandedGridColumn.AutoFillDown option.

C#

private void btnCreateBandedLayout_ItemClick(object sender, ItemCl
    // ...
    // Stretch columns to fit empty spaces below them.
    colPrice.AutoFillDown = true;
    colDescription.AutoFillDown = true;
    colPicture.AutoFillDown = true;
}        

Run the application and click the Create Banded Layout button again to see the final result.

Complete Code

C#

private void btnCreateBandedLayout_ItemClick(object sender, ItemClickEventArgs e) {
    // Switch to the Advanced Banded Grid View. 
    AdvBandedGridView view = new AdvBandedGridView();
    view.OptionsBehavior.AutoPopulateColumns = false;
    gridControl1.MainView = view;

    // Create top-level bands.  
    GridBand bandMain = new GridBand() { Name = "bandMain", Caption = "Main" };
    GridBand bandPerformanceAttributes = new GridBand() { Name = "bandPerformance", Caption = "Performance Attributes" };
    GridBand bandNotes = new GridBand() { Name = "bandNotes", Caption = "Notes" };
    view.Bands.AddRange(new GridBand[] { bandMain, bandPerformanceAttributes, bandNotes });

    // Create nested bands.
    GridBand bandModel = new GridBand { Name = "bandModel", Caption = "Model" };
    GridBand bandPrice = new GridBand { Name = "bandPrice", Caption = "Price" };
    bandMain.Children.AddRange(new GridBand[] { bandModel, bandPrice });

    // Create banded grid columns and make them visible.
    BandedGridColumn colTrademark = new BandedGridColumn() { Name = "colTrademark", FieldName = "Trademark", Visible = true };
    BandedGridColumn colModel = new BandedGridColumn() { Name = "colModel", FieldName = "Model", Visible = true };
    BandedGridColumn colCategory = new BandedGridColumn() { Name = "colCategory", FieldName = "Category", Visible = true };
    BandedGridColumn colPrice = new BandedGridColumn() { Name = "colPrice", FieldName = "Price", Visible = true };
    BandedGridColumn colHP = new BandedGridColumn() { Name = "colHP", FieldName = "HP", Visible = true };
    BandedGridColumn colLiter = new BandedGridColumn() { Name = "colLiter", FieldName = "Liter", Visible = true };
    BandedGridColumn colCyl = new BandedGridColumn() { Name = "colCyl", FieldName = "Cyl", Visible = true };
    BandedGridColumn colDescription = new BandedGridColumn() { Name = "colDescription", FieldName = "Description", Visible = true };
    BandedGridColumn colPicture = new BandedGridColumn() { Name = "colPicture", FieldName = "Picture", Visible = true };
    view.Columns.AddRange(new BandedGridColumn[] { colTrademark, colModel, colCategory, colPrice, colHP, colLiter, colCyl, colDescription, colPicture });

    // Format the Price column values as currency.
    colPrice.DisplayFormat.FormatType = DevExpress.Utils.FormatType.Numeric;
    colPrice.DisplayFormat.FormatString = "c2";

    // Assign columns to bands.  
    colTrademark.OwnerBand = bandModel;
    colModel.OwnerBand = bandModel;
    colCategory.OwnerBand = bandModel;
    colPrice.OwnerBand = bandPrice;
    colHP.OwnerBand = bandPerformanceAttributes;
    colLiter.OwnerBand = bandPerformanceAttributes;
    colCyl.OwnerBand = bandPerformanceAttributes;
    colDescription.OwnerBand = bandNotes;
    colPicture.OwnerBand = bandNotes;

    // Set the vertical position of column headers.
    colCategory.RowIndex = 1;
    colLiter.RowIndex = 1;

    // Stretch columns to fit empty spaces below them.
    colPrice.AutoFillDown = true;
    colDescription.AutoFillDown = true;
    colPicture.AutoFillDown = true;
}