How to: Configure Bands in a Grid List Editor (WinForms and ASP.NET Web Forms)
- 4 minutes to read
This topic describes how to group grid columns using bands in both WinForms and ASP.NET Web Forms XAF applications.
Note
- If you prefer to watch a video rather than walk through these step-by-step instructions, visit the corresponding tutorial on the DevExpress YouTube Channel: XAF: Bands in Grid List Editors. You can also see a demonstration of bands in the List Editors | Grid | Banded List View section of the Feature Center demo. The default location of the application is %PUBLIC%\Documents\DevExpress Demos 24.2\Components\XAF\FeatureCenter.NETFramework.XPO.
- ASP.NET Core Blazor applications do not support bands.
In this example, the Simple Project Manager demo application installed to the %PUBLIC%\Documents\DevExpress Demos 24.2\Components\XAF\SimpleProjectManager.NETFramework is used. However, you can follow the steps below in any XAF application that provides a List View with several columns, but obviously the captions will differ.
Run the Model Editor for the platform-agnostic module. In the node tree to the left, find the ListView node that you are going to customize (e.g., the ProjectTask_ListView node). Focus the BandsLayout child node. In the property grid to the right, set the IModelBandsLayout.Enable property to true.
After changing the Enabled value, you will notice that now it is possible to expand the child nodes of the BandsLayout node. By default, no bands are added, and this node contains columns only. To add a band, right-click BandsLayout and choose Add… | Band.
Focus the newly added node and specify a meaningful Id for it (e.g., TaskDetails).
Note
The IModelBand.Caption of a band is filled automatically based on the Id value. However, you can change the caption when required.
Select columns to be added to the TaskDetails band (hold the CTRL key and click the corresponding nodes). Then, drag the selected columns to the TaskDetails band node.
Analogously, add another band (e.g., Schedule) and move the remaining columns into it. The resulting bands layout is illustrated below.
Tip
You can add a band inside an existing band to create a complex bands hierarchy.
Run the WinForms application to see the result. According to the bands layout illustrated in the previous step, the ProjectTask List View has two bands - Schedule and TaskDetails. The Schedule band enclosures the Start Date and End Date columns. The Subject, Status and Assigned To columns are grouped into the TaskDetails band.
Run the ASP.NET Web Forms application to ensure that the bands layout is exactly the same.
Now let us try the extra configuration options available for WinForms only. Stop debugging and run the Model editor for the WinForms application project. In the node tree to the left, find the BandsLayout node that you configured in the previous steps. Focus a column within a band (e.g., Subject). Change the IModelBandedColumnWin.RowIndex value to 1.
Tip
In WinForms, you can specify what customization capabilities of bands are allowed to end users and hide band/column headers using the IModelBandsLayoutWin properties.
Run the WinForms application to see the result. The Subject column is now displayed below the Status and Assigned To columns that have zero RowIndex.
Important
When configuring bands, keep in mind the differences in behavior between WinForms and ASP.NET Web Forms grid controls:
- Columns that are not added to any band are visible in ASP.NET Web Forms applications only. The WinForms grid control does not display such columns.
- The IModelBandedColumnWin.RowIndex option is available for WinForms only. You cannot arrange column headers across rows in ASP.NET Web Forms applications.
- Options that restrict band configuration by users (see IModelBandsLayoutWin) are available in WinForms only.
That is why we recommend the following:
- Setup bands separately for WinForms and ASP.NET Web Forms. Configuring bands in a platform-agnostic module is suitable for very simple band layouts only.
- Avoid merging platform-specific band configuration in a common module.