Description

The TopNOptions property determines if the TopN feature is active or not. If TopNOptions is set to tnUnsorted or tnDefault, the TopN features are deactivated. The possible values for this property are:

TopN Option	Description
tnUnsorted	Groups are not sorted by a summary field.
tnSorted	Groups are sorted by the TopNField (a summary field).
tnTopN	Groups are selected based on the value of the TopNGroups property from highest
	down.
tnBottomN	Groups are selected based on the value of the TopNGroups property from lowest up.
tnDefault	TopN Options are left as defined in the Report.

Example

This example shows how to use the TopN features of GroupOptions. In this case, the top 10 groups (based on the summary of their Sales) will be shown on the Report. All other groups will be discarded. The TopN selection will take place on the outer Group (Group number 1):

Crpe1.ReportName := 'C:\Company.rpt'; Crpe1.GroupOptions.Retrieve; Crpe1.GroupOptions[0].TopNOptions := tnTopN; Crpe1.GroupOptions[0].TopNGroups := 10; Crpe1.GroupOptions[0].TopNSortField := 'Sum({company.SALES},{company.STATE})'; Crpe1.GroupOptions[0].TopNDiscardOthers := cTrue; Crpe1.Output := toWindow;

Crpe1.Execute;

GroupOptions TopNSortField property

Declaration

property TopNSortField: string

Description

The TopNSortField property specifies the formula text of the expression that will control the TopN sorting/ selection feature.

●TopNSortField is normally a summary field, and has the same syntax and purpose as the Field property of GroupSortFields.

●TopNOptions must be set to one of the following in order for TopNSortField to take effect:

tnSorted, tnTopN, tnBottomN.

●The TopNSortField value will cause any other GroupSortFields for the specified Group to be deleted when the Report is run.

VCL Reference

375

Example

This example shows how to use the TopN features of GroupOptions. In this case, the top 10 groups (based on the summary of their Sales) will be shown on the Report. All other groups will be discarded. The TopN selection will take place on the outer Group (Group number 1):

Crpe1.ReportName := 'C:\Company.rpt'; Crpe1.GroupOptions.Retrieve; Crpe1.GroupOptions[0].TopNOptions := tnTopN; Crpe1.GroupOptions[0].TopNGroups := 10; Crpe1.GroupOptions[0].TopNSortField := 'Sum({company.SALES},{company.STATE})'; Crpe1.GroupOptions[0].TopNDiscardOthers := cTrue; Crpe1.Output := toWindow;

Crpe1.Execute;

GroupOptions Methods

GroupOptions Add method

Declaration

procedure Add(GroupNumber: TCrGroupOptionsNumber);

Type

TCrGroupOptionsNumber = integer;

Description

The Add method adds an item to the GroupOptions object and sets the internal index to that item. It requires a Group number as a parameter, which should be a number corresponding to a Group in the Report.

Contrary to most other items in the Crystal VCL, Groups are numbered starting from one, so as to be consistent with the Group naming convention: GH1 is the first group header, etc. (although the GroupOptions object is still zero based, so GroupOptions[0].Number is usually equal to 1).

The steps to using the Add method with GroupOptions are:

1Add an item to the GroupOptions object (you must specify the Group Number).

2Fill the item's properties (Field, Condition, etc.) with values.

3When Execute is called, the properties will be sent to the Print Engine.

NOTE: It is easier to use the Retrieve method instead of Add, since it ensures that the number of items, and the Group numbers are correct for the current Report.

VCL Reference

376

Example

The Add method can be used to manually add an item to the GroupOptions object, instead of using Retrieve:

Crpe1.ReportName := 'C:\Company.rpt';

{Specify Group Number - must be same as in Report} Crpe1.GroupOptions.Add(1); Crpe1.GroupOptions.KeepTogether := cTrue; Crpe1.Output := toWindow;

Crpe1.Execute;

GroupOptions Clear method

Declaration

procedure Clear;

Description

This method can be used to clear the internal memory of the GroupOptions object. It is called automatically if the Clear method is called for the main component, or if a new Report name is assigned to the ReportName property, but may be called in code as desired.

The Clear method is only applied to the GroupOptions object of the current Report/Subreport specified in the Subreports object. Therefore, to clear all the GroupOptions of all the Subreports will require a looping procedure that goes through each Subreport and applies the Clear method.

Example

This code clears the GroupOptions properties for the main Report (assuming the default state of Subreports[0]):

Crpe1.GroupOptions.Clear;

This code clears the GroupOptions for all the Subreports:

for cnt := 1 to (Crpe1.Subreports.Count - 1) do begin

Crpe1.Subreports[cnt];

Crpe1.GroupOptions.Clear; end;

VCL Reference

377

GroupOptions CopyFrom method

Declaration

function CopyFrom(Source: TCrpeGroupOptions): boolean;

Description

The CopyFrom method copies the GroupOptions property values from another TCrpeGroupOptions object. It is similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.

Example

The following example copies all the GroupOptions property values to a temporary TCrpeGroupOptions object:

var

tempGroupOptions : TCrpeGroupOptions; begin

tempGroupOptions := TCrpeGroupOptions.Create; tempGroupOptions.CopyFrom(Crpe1.GroupOptions); {...later, when finished with the temp object...} tempGroupOptions.Free;

end;

GroupOptions Count method

Declaration

function Count: integer;

Description

The Count method can be used to obtain the number of items currently in the GroupOptions object. It is handy for setting up loops to make similar changes to each item.

Example

The Count method is useful for looping constructions. You would normally want to call Retrieve first:

var

cnt: integer; begin

Crpe1.ReportName := 'C:\Company.rpt'; Crpe1.GroupOptions.Retrieve;

for cnt := 0 to (Crpe1.GroupOptions.Count - 1) do Crpe1.GroupOptions[cnt].KeepTogether := cTrue;

end;

VCL Reference

378