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

{if the SectionType is Group Header, apply the change} if (Crpe1.SectionFormat[cnt].SectionType = 'GH') then Crpe1.SectionFormat[cnt].BackgroundColor := clRed;

end; end;

SectionFormat Send method

Declaration

function Send: boolean;

Description

The Send method sends the SectionFormat values to the Crystal Reports Print Engine. This method is called automatically when the Execute method is called, provided that SendOnExecute is set to True.

It is strongly recommended that you leave SendOnExecute to True, and let the Crystal Reports component send the values to the Print Engine. If you set the SendOnExecute property to False, each Sub-class and each property that does not belong to a Sub-class must be manually sent before calling the Execute method. This feature is mainly provided for debugging purposes.

Example

In this example, the SectionFormat settings are sent from the Crystal component to the Crystal Reports Print Engine DLL. This is normally handled automatically in the Execute method:

Crpe1.SectionFormat.Send;

SectionFormatFormulas Properties

SectionFormatFormulas Formula property

Declaration

property Formula: TCrpeString;

Type

TCrpeString = class(TStringList)

VCL Reference

564

Description

The Formula property specifies the SectionFormatFormulas formula text. Any values in the Formula that must be seen as strings should be put in double quotes, for example:

Crpe1.SectionFormatFormulas.Formula.Text := '{company.STATE} = "CA"';

Before setting the Formula property, be sure the SectionFormatFormulas object is pointing to the correct Section, and the Section is pointing to the correct Formula Name item. See the Section and Name properties for more details.

See also Using Variables with Selection Formula, Page 102.

Example

This example retrieves the SectionFormatFormula information, then assigns a Suppress formula to the Details "a" section, so that the section will be suppressed if the State is California:

Crpe1.ReportName := 'Company.rpt'; Crpe1.SectionFormatFormulas.Retrieve; {Loop through the Areas}

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

{Check for Details area}

if Crpe1.SectionFormatFormulas[cnt].Section = 'Da' then begin

{Choose the Suppress formula} Crpe1.SectionFormatFormulas[cnt].Name := sfSuppress; {Clear it from any retrieved formula} Crpe1.SectionFormatFormulas[cnt].Formula.Clear;

{Add the new formula} Crpe1.SectionFormatFormulas[cnt].Formula.Add('{company.STATE}

= "CA"'); Break;

end; end;

Crpe1.Output := toWindow; Crpe1.Execute;

SectionFormatFormulas Item property

Declaration

property Item[nIndex: integer]: TCrpeSectionFormatFormulas;

VCL Reference

565

Description

The Item property is a default array property. It is read-only, and only available at runtime. It's primary use is to provide an easy way to navigate through the SectionFormatFormulas object, allowing the object to be treated like an array.

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

¾Item returns a reference to itself, so the SectionFormatFormulas properties can be used right after the subscript: SectionFormatFormulas[2].Section := GH1a;

Example

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

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

Crpe1.SectionFormatFormulas.Retrieve;

{Set SectionFormatFormulas object to the 2nd item} Crpe1.SectionFormatFormulas.Item[1];

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

Crpe1.SectionFormatFormulas.Retrieve;

{Set SectionFormatFormulas object to the 2nd item} Crpe1.SectionFormatFormulas[1];

SectionFormatFormulas ItemIndex property

Declaration

property ItemIndex: integer;

Description

ItemIndex is a Run-time only property which can be used to obtain the current SectionFormatFormulas item number, or set the SectionFormatFormulas 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 (SectionFormatFormulas[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

566

Example

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

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

SectionFormatFormulas Name property

Declaration

property Name: TCrSectionFormatFormula;

Type

TCrSectionFormatFormula = (sfSuppress, sfPrintAtBottomOfPage, sfNewPageBefore, sfNewPageAfter, sfResetPageNAfter, sfKeepTogether, sfSuppressBlankSection, sfUnderlaySection, sfBackgroundColor);

Description

The Name property specifies which Formula the SectionFormatFormulas object is currently pointing to, and which formula name the Formula property will apply to. These names correspond to the Formula buttons that appear in the SectionFormat dialog in Crystal Reports Designer.

●Name acts as a look up field, so assigning a new value to the Name property will cause that Formula Name (if it exists) to be the currently active one for the SectionFormatFormulas object.

●The Retrieve method will obtain the applicable Formula names for each Section in the Report.

●The Names available in a given Section are accessible via the Names array property and the NameCount method.

●The IndexOfName method will return the index number of a given Formula Name and the NameIndex property will return the index value of the current Formula item. The index number represents the position of that Formula in the Names array, not the position in the SectionFormatFormulas object.

Explanation

After Retrieve has been called, the SectionFormatFormulas object contains an item for each Section in the Report, and each of these Section items also contains an item for each Formula Name available to that Section. To locate a given Formula for a given Section, the first step is to navigate the SectionFormatFormulas object to the Section item:

Crpe1.SectionFormatFormulas.Section := 'Da'; {or}

{assuming Details "a" is the 4th Section} Crpe1.SectionFormatFormulas[4];

VCL Reference

567

And then navigate to the Formula Name item for that Section:

Crpe1.SectionFormatFormulas.Name := sfSuppress; {or}

Crpe1.SectionFormatFormulas.Names[0];

The arrangement of Sections and Formulas could be illustrated like this: SectionFormatFormulas

●Section item: RH

¾Names Items

¾sfSuppress

¾sfHide

¾sfNewPageBefore

¾sfNewPageAfter

¾sfKeepTogether

¾sfResetPageNAfter

¾sfPrintAtBottomOfPage

¾sfSuppressBlankSection

¾sfUnderlaySection

¾sfBackgroundColor

●Section item: PH

¾Names Items

¾sfSuppress

¾sfHide

¾sfResetPageNAfter

¾sfSuppressBlankSection

¾sfUnderlaySection

¾sfBackgroundColor

●Section item: GH1

¾Names Items

¾sfSuppress

¾sfHide

¾etc.

VCL Reference

568

Since some SectionFormat Formula options are not available for certain Sections, it is not wise to assume that each SectionFormatFormula item will have 10 Formulas associated with it. On the contrary, it could have anywhere from 6 to 10 Formulas. For the Main Report, Page Headers (PH) and Page Footers (PF) have only 6 available options. For a Subreport, the same limitations apply to Report Header b (RHb) and Report Footer b (RFb). The following chart lists the Sections that have limitations, and which options can have formulas:

x = available; o = not available

	Main Report	Sections	Subreport	Subreport
Formula Names	PH	PF	RHb	RFb
sfSuppress	x	x	x	x
sfHide	x	x	x	x
sfNewPageBefore	o	o	o	o
sfNewPageAfter	o	o	o	o
sfKeepTogether	o	o	o	o
sfResetPageNAfter	x	x	x	x
sfPrintAtBottomOfPage	o	o	o	o
sfSuppressBlankSection	x	x	x	x
sfUnderlaySection	x	x	x	x
sfBackgroundColor	x	x	x	x

Attempting to set formulas for Sections that do not support that formula will cause errors when the Report is run. To avoid this, the IndexOfName method can be used to determine if a given Formula Name actually exists in the particular Section.

NOTE: Crystal Reports 6.0.x.151 reads the SectionFormatFormula options incorrectly from older 6.0 version Reports (or it may be that the older 6.0 Reports did not quite store the options correctly!). This is only apparent on the RH and RF Sections of a Subreport. Instead of the formula limitations (noted in the chart above) appearing in the second Report Header (RHb) and second Report Footer (RFb), they appear on the last sub-section of the Report Header, which could be RHb if there are only 2 sub-sections (which is the default), or it could be anything else (RHd, for example). Also, the RFb limitations do not appear at all. This behavior does not appear when designing a new Report in 6.0.x.151, only when loading one designed with an earlier version. For this reason, when dealing with Subreports and SectionFormatFormulas, the IndexOfName method is useful to make sure a formula option is available for the Section before attempting to assign a Formula.

Example

This example retrieves the SectionFormatFormula information, then assigns a Suppress formula to the Details "a" section, so that the section will be suppressed if the State is California:

Crpe1.ReportName := 'Company.rpt'; Crpe1.SectionFormatFormulas.Retrieve; {Loop through the Areas}

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

VCL Reference

569