Obtain And Set Summary Values
- 6 minutes to read
The ExpressQuantumGrid supports two summary types: footer summary and group summary. These summaries’ values are calculated via several built in functions: Max, Min, Sum, Average and Count. The ExpressQuantumGrid provides several events, which can be used for custom summary implementations (see the Create Custom Summary topic for details).
This topic explains how to work with the summary values. It consists of the following sections:
Footer summary values;
Group summary values.
FOOTER SUMMARY VALUES
The following code demonstrates how to obtain the value of a footer summary calculated for a specific data field. Note, that the FooterSummaryValues property returns the value of the footer summary item as a Variant:
//...
var
I: Integer;
AValue: Variant;
begin
with tvOrders.DataController.Summary do
begin
for I := 0 to FooterSummaryItems.Count - 1 do
begin
if TcxGridDBTableSummaryItem(FooterSummaryItems[I]).Column = tvOrdersPurchaseDate then
begin
AValue := FooterSummaryValues[I];
end;
end;
end;
end;
//...
GROUP SUMMARY VALUES
In Chart Views, group summaries are calculated when series values are aggregated in the same categories using data groups. Group summaries are calculated for each category and displayed as aggregate series values. Group summaries are displayed as data markers which correspond to aggregate series values.
There are two types of group summaries:
group summaries, displayed when a View is grouped by any column values (accessed via the View.DataController.Summary.DefaultGroupSummaryItems collection);
summary groups, displayed when grouping occurs by specific columns (accessed via the View.DataController.Summary.SummaryGroups collection).
All summary items representing both the group summaries and summary groups can be accessed via the GroupSummaryItems collection.
Use the View.DataController.Summary.GroupSummaryValues property to obtain or set the values of the group summary. This property provides access to all the summary values, regardless of the corresponding group’s row state (expanded or collapsed). It uses the index of the required data group and the required group summary index among the group summaries associated with the specified data group to address a summary value. The data group index can be retrieved via properties of the TcxDataControllerGroups object, representing the collection of all groups within a View.
The following code demonstrates how to use the GroupSummaryValues property to obtain a summary value. It locates the summary item, associated with the Purchase Date column from among the summary items of the fifth group row at the first group level.
//...
var
AValue: Variant;
AGroups: TcxDataControllerGroups;
I: Integer;
//...
//the AGroups variable references a TcxDataControllerGroups instance
//representing all data groups within the tvOrders View
AGroups := tvOrders.DataController.Groups;
with tvOrders.DataController.Summary do
begin
//searching within the collection of the summary items associated
//with the first group level...
for I := 0 to GroupSummaryItems[0].Count - 1 do
begin
//for a summary item whose Column property addresses the Purchase
//Date column...
if TcxGridTableSummaryItem(GroupSummaryItems[0].Items[I]).Column = tvOrdersPurchaseDate then
//...and assigning such item's value to the AValue variable. The
//required value is addressed via the ChildDataGroupIndex property
//which is passed -1 as the root group level index and 4 as the
//required group row index within the root group level
AValue := GroupSummaryValues[AGroups.ChildDataGroupIndex[-1, 4], I];
end;
end;
//...
To obtain or set only visible group summaries’ values use the View.DataController.Summary.GroupSummaryDisplayValues property, which addresses summary values via the required row index.
The formatted representation of the group summary can be accessed through two properties:
The View.DataController.Summary.GroupFooterSummaryTexts property provides access to the texts of group summaries displayed within the group footers;
The View.DataController.Summary.GroupSummaryText property provides access to the text representations of group summaries, displayed within the group rows.
The following code demonstrates how to obtain the group summary value, displayed within the Payment Amount column footer of the second row at the first group level. This code uses the GroupFooterIndexOfItemLink property to obtain the index of the required group summary. Keep in mind that the summary value can be obtained as a Variant value.
var
AValue: Variant;
AFooterItemIndex: Integer;
//...
with tvOrders.DataController.Summary do
begin
//the AFooterItemIndex variable contains the index of a group summary
//displayed within the tvOrdersPaymentAmount column footer at the
//first group level
AFooterItemIndex := GroupFooterIndexOfItemLink[0, tvOrdersPaymentAmount];
//the AValue variable is used to store the group summary value
//displayed within the tvOrdersPaymentAmount column footer of the
//second row at the first group level
AValue := GroupSummaryDisplayValues[1, 0, AFooterItemIndex];
end;
//...
The following code snippet shows how to calculate a total for group footer summaries and custom paint group footers within the View’s OnCustomDrawPartBackground event handler based on the calculated total.
procedure <Form>.<View>CustomDrawPartBackground(Sender: TcxCustomGridTableView; ACanvas: TcxCanvas; AViewInfo: TcxCustomGridCellViewInfo; var ADone: Boolean);
var
AFooterTotalValue: Variant;
AFooterViewInfo: TcxGridRowFooterViewInfo;
I, AGroupLevel: Integer;
AColor: TColor;
begin
if AViewInfo.GetHitTest(AViewInfo.Bounds.TopLeft).HitTestCode = htGroupFooter then
begin
with Sender.DataController.Summary do
begin
AFooterViewInfo := TcxGridRowFooterViewInfo(AViewInfo);
AGroupLevel := AFooterViewInfo.GroupLevel;
for I := 0 to GroupSummaryItems[AGroupLevel].Count - 1 do
// Calculating a total using a group footer's summary values
AFooterTotalValue := AFooterTotalValue + GroupSummaryDisplayValues[AFooterViewInfo.GridRecord.Index, AGroupLevel, I];
if AFooterTotalValue < 500 then
AColor := clRed
else
AColor := clGreen;
ACanvas.FillRect(AFooterViewInfo.Bounds, AColor);
end;
ADone := True;
end;
end;