Description

The Item property is a default array property. It is read-only, and only available at runtime. Its primary use is to provide an easy way to navigate through the various items stored in the SortFields object, allowing the object to be treated like an array.

●Item is a default property, so it does not need to be specified when using the subscript: SortFields[2] is the same as SortFields.Item[2].

●Item returns a reference to itself, so the SortFields properties can be used right after the subscript: SortFields[2].Field := '{company.STATE}';

Example

Since Item is a default array property, the following two blocks of code do the same thing:

Crpe1.ReportName := 'MyReport.rpt'; Crpe1.SortFields.Retrieve;

{Set SortFields object to the 3rd item} Crpe1.SortFields.Item[2]; Crpe1.ReportName := 'MyReport.rpt'; Crpe1.SortFields.Retrieve;

{Set SortFields object to the 3rd item} Crpe1.SortFields[2];

SortFields ItemIndex property

Declaration

property ItemIndex: integer;

Description

ItemIndex is a Run-time only property which can be used to obtain the current SortFields item number, or set the SortFields object to another item.

Each object in the Crystal component that can contain more than one item uses an internal Index to maintain which item it is currently looking at, similar to the ItemIndex property of a ListBox. This Index is updated whenever the Item property is used (SortFields[2], for example), or whenever the key property (if applicable) is assigned a new lookup value (key properties are things like Formulas.Name, or SortFields.Number which serve as look-up properties).

The easiest way to read the current Index number is to use the ItemIndex property.

VCL Reference

614

Example

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

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

SortFields Number property

Declaration

property Number: TCrSortFieldsNumber;

Description

The Number property specifies the actual SortField number. It is zero-based, so the first SortField in a Report is zero (0). Number is a key property, and therefore serves as a lookup; that is, assigning it a value will cause the SortFields object to point to the item that has a SortField Number with the same value. Before using the Number property to navigate through the SortFields, the Retrieve method should be called, or the manual Add method.

Example

This example uses the Number property to cause the SortFields object to point to the second SortField item:

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

Crpe1.SortFields.Retrieve;

Crpe1.SortFields.Number := 1;

Crpe1.SortFields.Direction := sdAscending;

Crpe1.Output := toWindow;

Crpe1.Execute;

SortFields Methods

SortFields Add method

Declaration

procedure Add(SortFieldNumber: TCrSortFieldsNumber);

VCL Reference

615

Type

TCrSortFieldsNumber = integer;

Description

The Add method does two things:

1.Adds an item to the SortFields object.

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

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

1Add an item to the SortFields object (you must specify the SortField number).

2Fill the item's properties (Direction, Field, 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 SortFields, and a new, fourth SortField 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 SortField numbers are correct for the current Report. However, for adding new SortFields that are not currently in the Report, the Add method must be used. When using Add in this way, the SortField number specified must be one greater than the highest SortField number currently in the Report (or one higher than the SortField number in the VCL if more than one SortField is being added).

Example

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

procedure AddSortField; 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.SortFields.Count do

begin

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

VCL Reference

616

Inc(cnt1); cnt2 := 0;

end else

Inc(cnt2);

end; Crpe1.SortFields.Add(cnt1);

end;

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

var

cnt: integer; begin

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

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

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

{Add a new SortField} Crpe1.SortFields.Add(Crpe1.SortFields.Count); Crpe1.SortFields.Field := '{company.STATE}'; Crpe1.SortFields.Direction := sdAscending; Crpe1.Output := toWindow;

Crpe1.Execute; end;

SortFields Clear method

Declaration

procedure Clear;

Description

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

VCL Reference

617