Bands
- 5 minutes to read
Bands are visual and logical groups into which you can arrange columns. You can hide, display and reorder bands along with their child columns. This document describes the band features, how to anchor bands and how to organize them into a hierarchical structure. This topic consists of the following sections.
Bands Basics
A TreeList allows you to combine columns into bands. A band can own one or more columns, or one or more other bands (thus making it possible to build a hierarchy of bands).
The following image demonstrates a Tree List that contains three top-level bands (Main, Details and Picture) and two nested bands (Absolute Values and Related To Earth Values).
Bands can be created using the Tree List Designer. After you created bands using the Designer, ensure that the TreeListOptionsView.ShowBandsMode property is set to Default or True. Otherwise, created bands will be hidden on the form at design time and runtime.
TreeListBand objects encapsulate Tree List bands. Each band object provides various options: the band size (TreeListBand.Width, etc.), a child column collection (TreeListBand.Columns), a child band collection (TreeListBand.Bands), the band header appearance settings (TreeListBand.AppearanceHeader) and so on.
Bands combine columns. Thus, when you drag-and-drop a band by its header, its columns are moved as well. When you hide a band, its columns are hidden. By default, columns and bands can only be moved within their parent bands. To allow columns and bands to be moved between bands, enable the TreeListOptionsCustomization.AllowChangeColumnParent and TreeListOptionsCustomization.AllowChangeBandParent options, respectively. Dragging a band header edge allows changing the band’s width. The TreeListBand.OptionsBand and TreeList.OptionsCustomization properties provide access to the options that specify whether the described band’s features are available. See the Design-Time Band Customization topic to learn more.
To customize the appearance settings of all or individual band headers, use the TreeListAppearanceCollection.BandPanel and TreeListBand.AppearanceHeader properties, respectively. However, the background and border color settings are not in effect if the Tree List control is painted using the Skin, Office2003 or WindowsXP style (see the Look and Feel topic).
Each band has a caption displayed by the band header. This caption is specified by the TreeListBand.Caption property. If the TreeListOptionsView.AllowHtmlDrawHeaders option is enabled, you can use HTML tags to format the band caption (e.g., draw a caption or its part bold or italic, insert an image, etc.). For detailed information, see the HTML Text Formatting document. To assign images to bands, use TreeListBand.ImageOptions.
If the TreeListOptionsView.AllowBandColumnsMultiRow option is enabled, columns headers within bands can be arranged in multiple rows. In this case, column cells will be arranged one under another.
Bands Hierarchy
Tree List allows you to create hierarchical structures of bands. This means that bands located at higher levels contain bands located on lower levels. The number of band levels is unlimited.
The following image shows a simple hierarchical band structure. The Main, Details and Picture bands reside at the top hierarchical level. The Details band owns the Absolute Values and Related To Earth Values bands.
The TreeList.Bands property provides access to bands residing at the root hierarchical level. Each object within this collection has its own child band collection (TreeListBand.Bands). Bands stored in this collection are displayed at the second hierarchy level. They can also have their own child bands, etc.
The image below demonstrates a hierarchical structure of objects corresponding to the band structure shown above.
To obtain the root band for a specific child band, use the TreeListBand.RootBand property. The TreeListBand.ParentBand property returns the band’s parent. Each band has an effect on its children. For instance, the visibility of child bands/columns depends on the TreeListBand.Visible property’s value of the parent band (see below); changing the band width leads to changing the width of its children, etc.
Fixed Bands
A Tree List allows you to anchor bands to a control’s left or right edge. As a result, such bands are not moved when scrolling horizontally the TreeList’s content. . This is useful if you need to always display a certain band’s content regardless of the scrollbar position.
Use the TreeListBand.Fixed property to anchor a band. By default, this property value is None, and the band is not fixed. Setting the property to Left or Right anchors the band to the left or right control edge, respectively. Fixed bands are visually separated from other bands by a fixed line.
The image below shows a Tree List with bands fixed to the left and right edges.
Note that anchoring bands is in effect only when the columns auto width feature (TreeListOptionsView.AutoWidth) is disabled.
Hidden Bands
If a band’s TreeListBand.Visible property is set to false, this band (along with its child bands and columns) is hidden and is not displayed within the TreeList. If one of a band’s parents is invisible, this band is also hidden regardless of its Visible property. The actual band visibility is specified by the TreeListBand.ActualVisible property.
Hidden bands can be accessed using the Bands tab in the Customization Form. To prevent a hidden band from being shown in the Customization Form, set the band’s TreeListOptionsBand.ShowInCustomizationForm property to false. To hide the Bands tab, disable the TreeListOptionsCustomization.ShowBandsInCustomizationForm option. This form can be invoked by selecting the Column/Band Chooser item in the band header context menu.
The following image shows the Bands tab in the Customization Form with the Main, Picture and Absolute Values hidden bands.
You can hide a band by dropping its header to the Customization Form. To display the band, drag and drop its header to the target position within the TreeList. See the Design-Time Band Customization document for more information.