Creating Summaries

• Jul 29, 2024
• 3 minutes to read

This topic demonstrates how to add footer and group summaries and display them within the TreeList control.

Use the following steps to add a summary to the TreeList control at design time:

• Select a column to display a summary using the Component Editor, or by clicking a column’s header in the TreeList control.

• Switch to the Object Inspector and click the ellipsis button next to the Summary.FooterSummaryItems property to invoke a collection editor to manage footer summaries. To manage group footer summaries, invoke a collection editor by clicking the ellipsis button next to the Summary.GroupFooterSummaryItems property.

• In the collection editor, add a summary item and specify the required summary type via the Kind property.

• Set the TreeList control’s OptionsView.Footer property to True to display the footer. Then, assign True to the column’s Options.Footer property to make footer cells visible to display footer summaries.

• To display group footer summaries, make the group footers and group footer cells visible by setting the TreeList control’s OptionsView.GroupFooters property and the column’s Options.GroupFooter property to True.

You can display summary item properties in the Object Inspector by clicking the corresponding footer and group footer cells.

The following code demonstrates how to create and display a column’s footer summary at runtime.

<TreeList>.OptionsView.Footer := True;
  <Column>.Options.Footer := True;
  with <Column>.Summary.FooterSummaryItems.Add do
    Kind := skSum;

Now you can run the application to see the result.

You can calculate a column’s summaries using the values of another column. To accomplish this, select the source column via the summary’s CalculatedColumn property.

To specify the format string for summary values, use the summary’s Format property. For instance, by setting this property to ‘SUM = $,0.00;-$,0.00’ for a currency column’s footer summary, you will get the following display text in footer cells:

The 0.00 string is a placeholder for the summary value. Two zeros following the point identify the number of digits in the summary value to the right of the decimal point. A comma stands for a thousands separator. A semicolon separates two patterns used to display positive and negative values. Other characters do not have a special meaning and are displayed on the screen as is. Thus, if the summary value is $23.01, the cell will display the ‘SUM = $23.01‘ string.

You can provide custom summary values by handling the OnSummary events. For example, you may use only selected nodes in the summary calculation or perform other calculations. To learn how to use the OnSummary and OnAfterSummary events, see the SummariesDemo shipped with the ExpressQuantumTreeList Suite.

Here is a code snippet taken from the SummariesDemo. This code calculates summaries based on the criteria specified via the footer or group footer context menu. The FCheckBudget and FCheckVacancies values indicate whether a particular condition is included in the criteria.

procedure TSummariesDemoMainForm.tlDepartmentsSummary(
  ASender: TcxCustomTreeList;
  const Arguments: TcxTreeListSummaryEventArguments;
  var OutArguments: TcxTreeListSummaryEventOutArguments);
begin
  // If a department doesn't match the specified criteria, exclude its
  // values from use in automatic summary calculations
  if FCheckBudget and (Arguments.Node.Values[clBudget.ItemIndex] <= 100000) or
    FCheckVacancies and not Arguments.Node.Values[clVacancy.ItemIndex] then
    OutArguments.Done := True;
end;