Custom Bands Example

Add custom header and footer bands to display additional information

Overview

Bands are custom rows that appear in the grid’s header or footer areas. They can display static text, column-specific information, totals, or any custom content.

Basic Band Creation

Text Band

The simplest band type displays static text:

uses
  Tee.Grid.Bands;

function NewTitle(const ACollection: TCollection; const AText: String): TTextBand;
begin
  result := TTextBand.Create(ACollection);
  result.Text := AText;
  
  // Customize appearance
  result.Format.Font.Size := 12;
  result.Format.Stroke.Visible := True;
  result.Format.Stroke.Color := TColors.Red;
end;

procedure AddHeaderBand;
var
  SampleHeader: TTextBand;
begin
  // Add to grid headers
  SampleHeader := NewTitle(TeeGrid1.Headers, 'Header Sample' + #13#10 + 'Text');
  
  // Move to top
  SampleHeader.Index := 0;
end;

Columns Band

Display custom text for each column:

uses
  Tee.Grid.Bands.Columns;

procedure AddCustomBand;
var
  Footer: TColumnsBand;
begin
  // Create the band in grid footer
  Footer := TColumnsBand.Create(TeeGrid1.Footer);
  
  // Set custom text for specific columns
  Footer.Text[TeeGrid1.Columns[1]] := 'Kg';
  Footer.Text[TeeGrid1.Columns[3]] := 'Lb';
end;

Complete Example

From Unit_Custom_Bands.pas:

unit Unit_Custom_Bands;

interface

uses
  Vcl.Forms, Vcl.ExtCtrls, Vcl.StdCtrls,
  VCLTee.Control, VCLTee.Grid,
  Tee.Grid.Bands.Columns,
  Tee.GridData.Strings;

type
  TCustomBandForm = class(TForm)
    TeeGrid1: TTeeGrid;
    Panel1: TPanel;
    procedure FormCreate(Sender: TObject);
  private
    Data: TStringsData;
    Footer: TColumnsBand;
    procedure AddSampleData;
    procedure AddCustomBand;
    procedure CreateGridEditor;
  end;

implementation

uses
  VCLTee.Editor.Grid, Tee.Grid.Columns, Tee.Painter;

procedure TCustomBandForm.AddCustomBand;
begin
  // Create the band, associate with grid footer
  Footer := TColumnsBand.Create(TeeGrid1.Footer);
  
  // Set custom text for columns
  Footer.Text[TeeGrid1.Columns[1]] := 'Kg';
  Footer.Text[TeeGrid1.Columns[3]] := 'Lb';
end;

procedure TCustomBandForm.AddSampleData;
var
  col, row: Integer;
  Column: TColumn;
begin
  Data := TStringsData.Create(5, 4);
  
  Data.Headers[0] := 'C0';
  Data.Headers[1] := 'C1';
  Data.Headers[2] := 'C2';
  Data.Headers[3] := 'C3';
  Data.Headers[4] := 'C4';
  
  // Fill with random numbers
  for col := 0 to Data.Columns - 1 do
    for row := 0 to Data.Rows - 1 do
      Data[col, row] := FloatToStr(Random(100));
  
  TeeGrid1.Data := Data;
  
  // Right-align all columns
  for Column in Data.ColumnList do
  begin
    Column.TextAlignment := TColumnTextAlign.Custom;
    Column.TextAlign.Horizontal := THorizontalAlign.Right;
  end;
end;

procedure TCustomBandForm.CreateGridEditor;
var
  Editor: TTeeGridEditor;
begin
  Editor := TTeeGridEditor.Embedd(Self, Panel1, TeeGrid1);
  
  // Show the Bands tab by default
  Editor.PageGrid.ActivePage := Editor.TabBands;
  Editor.PageGridChange(Editor);
end;

procedure TCustomBandForm.FormCreate(Sender: TObject);
begin
  AddSampleData;
  AddCustomBand;
  CreateGridEditor;
  
  // Set footer to float at bottom of last visible row
  TeeGrid1.Footer.Floating := True;
end;

end.

Footer Options

Floating Footer

// Footer appears at bottom of last visible row
// (only when vertical scrollbar is not present)
TeeGrid1.Footer.Floating := True;

// Footer always at bottom of grid control
TeeGrid1.Footer.Floating := False;

Footer Visibility

// Show footer
TeeGrid1.Footer.Visible := True;

// Hide footer
TeeGrid1.Footer.Visible := False;

Advanced Bands

Totals Band

Display calculated totals for columns:

uses
  Tee.Grid.Totals;

function CreateTotals(const ACollection: TCollection): TColumnTotals;
var
  result: TColumnTotals;
begin
  result := TColumnTotals.Create(ACollection);
  
  // Add calculations
  result.Calculation.Add('Name', TColumnCalculation.Count);
  result.Calculation.Add('Children', TColumnCalculation.Sum);
  result.Calculation.Add('Height', TColumnCalculation.Average);
  
  // Access sub-column
  result.Calculation.Add(
    result.Columns['Address'].Items['Number'],
    TColumnCalculation.Max
  );
  
  // Format the totals
  result.Format.Font.Style := [fsBold];
end;

procedure AddTotals;
var
  tmp: TColumnTotals;
begin
  tmp := CreateTotals(TeeGrid1.Footer);
  TTotalsHeader.CreateTotals(TeeGrid1.Footer, tmp);
end;

Available Calculations

type
  TColumnCalculation = (
    Count,      // Number of rows
    Sum,        // Sum of values
    Average,    // Average value
    Min,        // Minimum value
    Max         // Maximum value
  );

Multi-Line Text Bands

procedure AddMultiLineHeader;
var
  tmp: TTextBand;
begin
  tmp := TTextBand.Create(TeeGrid1.Headers);
  tmp.Text := 'Line 1' + #13#10 + 'Line 2' + #13#10 + 'Line 3';
  
  // Enable multi-line display
  tmp.Format.TextAlign.Vertical := TVerticalAlign.Center;
end;

Styled Bands

Gradient Background

procedure AddStyledFooter;
var
  tmp: TTextBand;
begin
  tmp := TTextBand.Create(TeeGrid1.Footer);
  tmp.Text := 'Footer Sample Text';
  
  // Enable gradient
  tmp.Format.Brush.Show;
  tmp.Format.Brush.Gradient.Show;
  tmp.Format.Brush.Gradient.Direction := TGradientDirection.Horizontal;
  tmp.Format.Brush.Gradient.StartColor := clWhite;
  tmp.Format.Brush.Gradient.EndColor := clSilver;
end;

Border and Stroke

procedure StyleBand(const ABand: TTextBand);
begin
  // Add border
  ABand.Format.Stroke.Visible := True;
  ABand.Format.Stroke.Color := TColors.Navy;
  ABand.Format.Stroke.Width := 2;
  
  // Background color
  ABand.Format.Brush.Show;
  ABand.Format.Brush.Color := TColors.LightBlue;
  
  // Font styling
  ABand.Format.Font.Style := [fsBold];
  ABand.Format.Font.Color := TColors.DarkBlue;
  ABand.Format.Font.Size := 14;
end;

Managing Multiple Bands

Adding Multiple Bands

procedure AddMultipleBands;
var
  Band1, Band2, Band3: TTextBand;
begin
  // Headers can contain multiple bands
  Band1 := TTextBand.Create(TeeGrid1.Headers);
  Band1.Text := 'Top Header';
  Band1.Index := 0;  // First position
  
  Band2 := TTextBand.Create(TeeGrid1.Headers);
  Band2.Text := 'Middle Header';
  
  // Footer can also have multiple bands
  Band3 := TTextBand.Create(TeeGrid1.Footer);
  Band3.Text := 'Footer Info';
end;

Removing Bands

// Clear all footer bands
TeeGrid1.Footer.Clear;

// Clear all header bands
TeeGrid1.Headers.Clear;

// Free specific band
SampleHeader.Free;

Band Positioning

// Move band to top
Band.Index := 0;

// Move band to bottom
Band.Index := TeeGrid1.Headers.Count - 1;

// Insert at specific position
Band.Index := 2;

Interactive Grid Editor

TeeGrid includes a visual editor for bands:

uses
  VCLTee.Editor.Grid, VCLTee.Editor.Grid.Bands;

// Edit grid headers
TGridBandsEditor.Edit(Self, TeeGrid1.Headers);

// Edit grid footer
TGridBandsEditor.Edit(Self, TeeGrid1.Footer);

// Edit entire grid
TTeeGridEditor.Edit(Self, TeeGrid1);

Embedded Editor

procedure CreateEmbeddedEditor;
var
  Editor: TTeeGridEditor;
begin
  // Embed editor in a panel
  Editor := TTeeGridEditor.Embedd(Self, Panel1, TeeGrid1);
  
  // Navigate to Bands tab
  Editor.PageGrid.ActivePage := Editor.TabBands;
  Editor.PageGridChange(Editor);
end;

Use Cases

Unit Labels

// Add unit labels below column headers
var
  Units: TColumnsBand;
begin
  Units := TColumnsBand.Create(TeeGrid1.Headers);
  Units.Text[TeeGrid1.Columns['Weight']] := 'kg';
  Units.Text[TeeGrid1.Columns['Height']] := 'cm';
  Units.Text[TeeGrid1.Columns['Temperature']] := '°C';
end;

Summary Information

// Display summary in header
var
  Summary: TTextBand;
begin
  Summary := TTextBand.Create(TeeGrid1.Headers);
  Summary.Text := 'Sales Report - Q4 2024';
  Summary.Format.Font.Size := 16;
  Summary.Format.Font.Style := [fsBold];
  Summary.Index := 0;
end;

Column Grouping

// Group related columns with a header band
var
  Group: TColumnsBand;
begin
  Group := TColumnsBand.Create(TeeGrid1.Headers);
  Group.Text[TeeGrid1.Columns['Q1']] := 'Quarter 1';
  Group.Text[TeeGrid1.Columns['Q2']] := '';
  Group.Text[TeeGrid1.Columns['Q3']] := 'Quarter 2';
  Group.Text[TeeGrid1.Columns['Q4']] := '';
  Group.Index := 0;
end;

Key Concepts

Band Types

• TTextBand: Static text spanning all columns
• TColumnsBand: Different text per column
• TColumnTotals: Calculated column totals
• TTotalsHeader: Label for totals band

Collections

• TeeGrid1.Headers: Bands above the grid
• TeeGrid1.Footer: Bands below the grid
• NewGroup.Header: Bands for detail grids (master-detail)
• NewGroup.Footer: Footer for detail grids

Features Demonstrated

• Creating text and column bands
• Styling bands with colors, fonts, gradients
• Adding totals calculations
• Managing multiple bands
• Using the visual band editor
• Floating footer behavior

Best Practices

1. Use TColumnsBand for column-specific information (units, notes)
2. Use TTextBand for general information (titles, summaries)
3. Add totals to footer for easy summary viewing
4. Style consistently with your application theme
5. Position carefully using Index property

Next Steps

• Learn about Themes for consistent styling
• Explore Master-Detail with band totals
• See Database Grid for data binding

Related Examples

• Master-Detail
• Themes
• Basic Grid