Skip to main content
Bands are rectangular regions in TeeGrid that can display custom content. They’re commonly used for headers, footers, and custom informational sections.

​
Understanding Bands

A band is a TGridBand object - a rectangle with support for:
  • Mouse hover highlighting
  • Custom height
  • Click events
  • Custom rendering
TeeGrid uses bands for:
  • Headers - Column headers and grid titles
  • Footers - Totals and summary information
  • Rows - The data rows themselves

​
Band Properties

All bands share these properties: 
// Height of the band
Band.Height.Value := 30;  // Fixed height in pixels
Band.Height.Percent := 10;  // Or percentage of total height

// Visibility
Band.Visible := True;

// Click handler
Band.OnClick := BandClickHandler;

​
Headers Collection

Add multiple header bands: 
// Headers is a collection of TGridBand
TeeGrid1.Headers.Visible := True;

// Add a text band to headers
var
  TitleBand: TTextBand;
begin
  TitleBand := TTextBand(TeeGrid1.Headers.Add);
  TitleBand.Text := 'Customer List';
  TitleBand.Height.Value := 40;
  TitleBand.TextRender.Format.Font.Size := 16;
  TitleBand.TextRender.Format.Font.Style := [fsBold];
  TitleBand.TextRender.Format.Brush.Color := clNavy;
  TitleBand.TextRender.Format.Brush.Visible := True;
  TitleBand.TextRender.Format.Font.Color := clWhite;
end;
Add multiple footer bands: 
TeeGrid1.Footer.Visible := True;

// Add a simple text footer
var
  FooterBand: TTextBand;
begin
  FooterBand := TeeGrid1.Footer.AddText('Total Records: ' + 
                                         IntToStr(TeeGrid1.Data.Count));
  FooterBand.Height.Value := 25;
  FooterBand.TextRender.Format.Brush.Color := clSilver;
  FooterBand.TextRender.Format.Brush.Visible := True;
end;

​
AddText Helper Method

Quickly add text bands: 
// AddText returns TTextBand
var
  Band: TTextBand;
begin
  Band := TeeGrid1.Headers.AddText('Grid Title');
  Band.TextRender.Format.Font.Size := 14;
  Band.TextRender.Format.Font.Style := [fsBold];
end;

​
TTextBand

TTextBand is a band that displays text: 
var
  TextBand: TTextBand;
begin
  TextBand := TTextBand.Create(TeeGrid1.Headers);
  TextBand.Text := 'My Header';
  
  // Format the text
  TextBand.TextRender.Format.Font.Color := clBlue;
  TextBand.TextRender.Format.Font.Size := 12;
  TextBand.TextRender.Format.Brush.Color := clWhite;
  TextBand.TextRender.Format.Brush.Visible := True;
  
  // Text alignment
  TextBand.TextRender.Format.TextAlign.Horizontal := THorizontalAlign.Center;
  TextBand.TextRender.Format.TextAlign.Vertical := TVerticalAlign.Center;
end;

​
Column Header Band

The main header showing column names is a special TColumnHeaderBand: 
// Access the column header
TeeGrid1.Header.Visible := True;
TeeGrid1.Header.Height.Value := 25;

// Format column headers
TeeGrid1.Header.Format.Brush.Color := clSilver;
TeeGrid1.Header.Format.Brush.Visible := True;
TeeGrid1.Header.Format.Font.Style := [fsBold];

// Enable column resizing
TeeGrid1.Header.AllowResize := True;

// Enable column dragging
TeeGrid1.Header.Drag.Allow := True;

// Row lines for multi-level headers
TeeGrid1.Header.RowLines.Visible := True;
TeeGrid1.Header.RowLines.Color := clGray;

​
Custom Band Classes

Create a custom band by inheriting from TGridBand: 
type
  TMyCustomBand = class(TGridBand)
  private
    FMyData: String;
  protected
    procedure Paint(var AData: TRenderData; const ARender: TRender); override;
  public
    property MyData: String read FMyData write FMyData;
  end;

procedure TMyCustomBand.Paint(var AData: TRenderData; const ARender: TRender);
begin
  // Custom painting logic
  AData.Painter.Fill.Color := clYellow;
  AData.Painter.FillRectangle(AData.Bounds);
  
  // Draw custom text
  AData.Painter.Font.Color := clBlack;
  AData.Painter.TextOut(AData.Bounds.Left + 10, AData.Bounds.Top + 5, FMyData);
end;

// Usage
var
  CustomBand: TMyCustomBand;
begin
  CustomBand := TMyCustomBand.Create(TeeGrid1.Headers);
  CustomBand.MyData := 'Custom Data';
  CustomBand.Height.Value := 30;
end;

​
Band Events

​
OnClick

Handle band clicks: 
procedure TForm1.BandClick(Sender: TObject);
var
  Band: TGridBand;
begin
  Band := TGridBand(Sender);
  ShowMessage('Band clicked: ' + Band.ClassName);
end;

// Assign event
TitleBand.OnClick := BandClick;

​
Floating Bands

Make bands float over content: 
TeeGrid1.Headers.Floating := True;
// Headers will overlay content instead of pushing it down

​
Band Height Modes

​
Fixed Height

Band.Height.Value := 40;  // 40 pixels

​
Percentage Height

Band.Height.Percent := 15;  // 15% of available height

​
Auto Height

For text bands, height can auto-calculate based on text: 
Band.Height.Automatic := True;

​
Multiple Headers Example

Create a grid with title and column headers: 
procedure TForm1.SetupHeaders;
var
  TitleBand: TTextBand;
  InfoBand: TTextBand;
begin
  // Add title
  TitleBand := TeeGrid1.Headers.AddText('Sales Report');
  TitleBand.Height.Value := 35;
  TitleBand.TextRender.Format.Font.Size := 16;
  TitleBand.TextRender.Format.Font.Style := [fsBold];
  TitleBand.TextRender.Format.Brush.Color := TAlphaColors.Darkblue;
  TitleBand.TextRender.Format.Brush.Visible := True;
  TitleBand.TextRender.Format.Font.Color := TAlphaColors.White;
  
  // Add info band
  InfoBand := TeeGrid1.Headers.AddText('Q4 2024');
  InfoBand.Height.Value := 25;
  InfoBand.TextRender.Format.Brush.Color := TAlphaColors.Lightblue;
  InfoBand.TextRender.Format.Brush.Visible := True;
  
  // Column headers are automatic
  TeeGrid1.Header.Visible := True;
  TeeGrid1.Header.Height.Value := 30;
end;
Add calculated totals in footer: 
uses
  Tee.Grid.Totals;

procedure TForm1.SetupFooter;
var
  Totals: TColumnTotals;
  TotalBand: TTotalsHeader;
begin
  // Create totals band
  Totals := TColumnTotals.Create(TeeGrid1.Footer);
  
  // Add calculations
  Totals.Calculation.Add('Amount', TColumnCalculation.Sum);
  Totals.Calculation.Add('Quantity', TColumnCalculation.Sum);
  Totals.Calculation.Add('Price', TColumnCalculation.Average);
  
  // Add header for totals
  TotalBand := TTotalsHeader.CreateTotals(TeeGrid1.Footer, Totals);
  TotalBand.Text := 'Totals:';
end;

​
Bands in Sub-Grids

Each TRowGroup has its own headers and footers: 
procedure TForm1.NewDetailGroup(const Sender, NewGroup: TRowGroup);
var
  DetailTitle: TTextBand;
begin
  // Add header to detail grid
  DetailTitle := NewGroup.Headers.AddText('Order Details');
  DetailTitle.Height.Value := 25;
  DetailTitle.TextRender.Format.Brush.Color := clLightGray;
  DetailTitle.TextRender.Format.Brush.Visible := True;
  
  // The detail grid has its own column header
  NewGroup.Header.Visible := True;
end;

​
Band Spacing

// Spacing between bands (default: 0)
TeeGrid1.Headers.Spacing := 2;  // 2 pixels between each header band

​
Hiding/Showing Bands

// Hide all headers
TeeGrid1.Headers.Visible := False;

// Hide column header only
TeeGrid1.Header.Visible := False;

// Hide specific band
TitleBand.Visible := False;

// Hide all footers
TeeGrid1.Footer.Visible := False;

​
Band Lines

Add borders to bands: 
// For TGridBandLines descendants
TitleBand.Lines.Visible := True;
TitleBand.Lines.Color := clGray;
TitleBand.Lines.Width := 1;

​
Best Practices

  • Use AddText() for simple text headers/footers
  • Keep band heights reasonable (20-40 pixels for text)
  • Use percentage heights sparingly, as they change with window size
  • Group related information in separate bands
  • Use consistent colors for visual hierarchy
  • Consider Floating := True for overlay effects
  • Remember that each sub-grid has its own header/footer collections
  • Use custom band classes for complex rendering needs

Build docs developers (and LLMs) love

Get started for freeTalk to us