Example

The following code illustrates the use of the ItemIndex property to make sure the GroupSortFields object is pointing to the first GroupSortFields item:

if Crpe1.GroupSortFields.ItemIndex <> 0 then Crpe1.GroupSortFields[0];

GroupSortFields Number property

Declaration

property Number: TCrGroupSortFieldsNumber;

Type

TCrGroupSortFieldsNumber = integer;

Description

The Number property specifies the Number of the GroupSortField. It is a key property, and therefore serves as a lookup; that is, assigning it a value will cause the GroupSortFields object to point to the item that has a GroupSortField Number with the same value. Before using the Number property to navigate through the GroupSortFields, the Retrieve method should be called, or the manual Add method.

Example

This example uses the Number property to cause the GroupSortFields object to point to the second GroupSortField item:

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

Crpe1.GroupSortFields.Retrieve;

Crpe1.GroupSortFields.Number := 1;

Crpe1.GroupSortFields.Direction := sdAscending;

Crpe1.Output := toWindow;

Crpe1.Execute;

GroupSortFields Methods

GroupSortFields Add method

Declaration

procedure Add(GroupSortFieldNumber: TCrGroupSortFieldsNumber);

VCL Reference

391

Type

TCrGroupSortFieldsNumber = integer;

Description

The Add method does two things:

1.Adds an item to the GroupSortFields object.

2.Sets the internal index of the GroupSortFields object to that new item.

It requires a GroupSortField number as a parameter, which should be a number corresponding to a GroupSortField in the Report (although it is possible with GroupSortFields to add a new item that is not currently in the Report). GroupSortFields are numbered starting from zero. If the Add method is used, the steps to using GroupSortFields are:

1Add an item to the GroupSortFields object (you must specify the GroupSortField number).

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

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

Unlike most of the other VCL properties which can only modify Report values, SortFields and GroupSortFields can be used to add items in the Report that have not been previously designed into it. However, care must be taken that the item added is the next available number in sequence. In other words, if a Report contains 3 GroupSortFields, and a new, fourth GroupSortField is to be added, it must be assigned a number of 3, since the existing ones will be numbered 0, 1, and 2.

NOTE: It is easier to use the Retrieve method instead of Add, since it ensures that the number of items, and the GroupSortField numbers are correct for the current Report. However, for adding new GroupSortFields that are not currently in the Report, the Add method must be used.

Example

Here is a simple procedure that locates the next available GroupSortField number when Adding a new GroupSortField to the GroupSortFields object:

procedure AddGroupSortField; var

cnt1,cnt2 : integer; begin

{Locate the first available number}

cnt1 := 0; {stores the new number to be checked}

cnt2 := 0; {cycles through the list for each new number} while cnt2 < Crpe1.GroupSortFields.Count do

begin

if Crpe1.GroupSortFields[cnt2].Number = cnt1 then begin

Inc(cnt1); cnt2 := 0;

end

VCL Reference

392

else

Inc(cnt2);

end; Crpe1.GroupSortFields.Add(cnt1);

end;

This example retrieves the GroupSortFields from a Report, sets them all to be deleted, and then adds a new GroupSortField:

var

cnt: integer; begin

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

{Set all GroupSortFields to be deleted. They are not actually deleted until Execute is called}

for cnt := 0 to (Crpe1.GroupSortFields.Count - 1) do Crpe1.GroupSortFields[cnt].DeleteGSF := True;

{Add a new SortField} Crpe1.GroupSortFields.Add(Crpe1.GroupSortFields.Count); Crpe1.GroupSortFields.Field := 'Sum({company.SALES},{company.STATE})'; Crpe1.GroupSortFields.Direction := sdAscending;

Crpe1.Output := toWindow; Crpe1.Execute;

end;

GroupSortFields Clear method

Declaration

procedure Clear;

Description

This method can be used to clear the internal memory of the GroupSortFields 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 GroupSortFields object of the current Report/Subreport specified in the Subreports object. Therefore, to clear all the GroupSortFields of all the Subreports will require a looping procedure that goes through each Subreport and applies the Clear method.

Example

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

Crpe1.GroupSortFields.Clear;

VCL Reference

393

This code clears the GroupSortFields properties for all the Subreports:

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

Crpe1.Subreports[cnt];

Crpe1.GroupSortFields.Clear; end;

GroupSortFields CopyFrom method

Declaration

function CopyFrom(Source: TCrpeGroupSortFields): boolean;

Description

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

([DPSOH

The following example copies all the GroupSortFields property values to a temporary TCrpeGroupSortFields object:

var

tempGroupSortFields : TCrpeGroupSortFields; begin

tempGroupSortFields := TCrpeGroupSortFields.Create; tempGroupSortFields.CopyFrom(Crpe1.GroupSortFields); {...later, when finished with the temp object...} tempGroupSortFields.Free;

end;

GroupSortFields Count method

Declaration

function Count: integer;

Description

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

VCL Reference

394