Seugute Crystu keports 7.

0
1echncu kelerence
Voume 4
Seagate Software, Inc.
840 Cambie Street
Vancouver, B.C., Canada V6B 4J2
1999 (manual and software) Seagate Software, Inc. All Rights Reserved.
Seagate Software, Seagate, and the Seagate logo are registered trademarks of Seagate
Technology, Inc., or one of its subsidiaries. Seagate Crystal Reports, Seagate Crystal Info,
Seagate Info, the Seagate Crystal Reports logo, and Smart Navigation are trademarks or
registered trademarks of Seagate Software, Inc. All other product names referenced are
believed to be the registered trademarks of their respective companies.
Manual written by:
ELUCIDEX
655 Stuart Road
Bellingham, WA 98226
http://www.elucidex.com
1999
C C N 1 L N 1 S
|
Chaptcr 1 - VCl Rcfcrcncc
1Crpe Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Propertes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Propertes y Croup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . l3l
Lvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . l66
\ndowLvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . l76
1ypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Constunts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Lrror Codes - VCL Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Lrror Codes - Crystu keports Prnt Lngne. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2l0
Sub-Cuss Propertes und Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2l4
VCI Re|etetce 1
VuIumc 4
1 VCL kelerence
What yuu wiII find in this chaptcr...
TCrpe Component, Page 2
Properties, Page 2
Properties By Group, Page 5
Methods, Page 131
Events, Page 166
WindowEvents, Page 176
Types, Page 200
Constants, Page 206
Error Codes - VCL Component, Page 207
Error Codes - Crystal Reports Print Engine, Page 210
Sub-Class Properties and Methods, Page 214
Note: Overview material for the Crystal VCL Component can be found in
Seagate Crystal Reports Technical Reference: Volume 1 -
Development Tools, Chapter 7.
VCI Re|etetce 2
TCrpc Cumpuncnt
The TCrpe Component encapsulates the functionality available in the Seagate Crystal Reports Print Engine
DLL(CRPE32.DLL) and can be easily added to any Delphi project and compiled into your final executable
application.
Prupcrtics
These are the Properties that belong specifically to the TCrpe class. Each Sub-class also has its own Properties
which can be viewed by going to the section for that particular Sub-class.
Property Name Read Only Run-time only Design-time only Sub-class
About, Page 6
x
AreaFormat, Page 7
x
AreaFormatFormulas, Page 10
x
CanCloseEngine, Page 13
x x
Connect, Page 13
x
ConnectMethod, Page 15
DesignControls, Page 17
x
DetailCopies, Page 19
DialogParent, Page 20
x
DiscardSavedData, Page 21
Export, Page 21
x
FieldMapping, Page 26
Formulas, Page 27
x
GraphData, Page 30
x
GraphOptions, Page 32
x
GraphText, Page 34
x
GraphType, Page 36
x
VCI Re|etetce !
GroupCondition, Page 39
x
GroupOptions, Page 41
x
GroupSelection, Page 43
x
GroupSortFields, Page 46
x
HasSavedData, Page 47
x x
IsJobFinished, Page 48
x x
JobNumber, Page 49
x x
LastErrorNumber, Page 49
x x
LastErrorString, Page 50
x x
LoadEngineOnUse, Page 51
LogOnInfo, Page 52
x
LogOnServer, Page 54
x x
Margins, Page 56
x
Output, Page 58
Pages, Page 59
x x
ParamFields, Page 61
x
PrintDate, Page 67
x
PrintEnded, Page 68
x x
Printer, Page 68
x
PrintOptions, Page 81
x
ProgressDialog, Page 83
Records, Page 84
x x x
ReportName, Page 85
ReportOptions, Page 87
x
VCI Re|etetce 4
ReportTitle, Page 89
SectionFont, Page 90
x
SectionFormat, Page 93
x
SectionFormatFormulas, Page
96
x
SectionHeight, Page 98
x
Selection, Page 100
x
SendOnExecute, Page 104
SessionInfo, Page 105
x
SortFields, Page 107
x
SQL, Page 108
Status, Page 111
x x
Subreports, Page 112
x
SummaryInfo, Page 114
x
Tables, Page 116
x
Version, Page 118
x x
WindowButtonBar, Page 119
x
WindowCursor, Page 121
WindowEvents, Page 123
WindowParent, Page 124
WindowSize, Page 126
x
WindowState, Page 127
WindowStyle, Page 128
x
WindowZoom, Page 130
x
VCI Re|etetce S
Prupcrtics By Gruup
Grou Proerly Name
Engine LoadEngineOnUse, Page 51
Error LastErrorNumber, Page 49
LastErrorString, Page 50
Export Export, Page 21
Formulas AreaFormatFormulas, Page 10
Formulas, Page 27
GroupSelection, Page 43
ParamFields, Page 61
SectionFormatFormulas, Page 96
Selection, Page 100
General About, Page 6
DesignControls, Page 17
FieldMapping, Page 26
ProgressDialog, Page 83
Graphs GraphData, Page 30
GraphOptions, Page 32
GraphText, Page 34
GraphType, Page 36
Group/Sort GroupCondition, Page 39
GroupOptions, Page 41
GroupSortFields, Page 46
SortFields, Page 107
Margins Margins, Page 56
Pages Pages, Page 59
PrintDate PrintDate, Page 67
Printer Printer, Page 68
Printer Properties, Page 81
PrintJob CanCloseEngine, Page 13
IsJobFinished, Page 48
JobNumber, Page 49
PrintEnded, Page 68
SendOnExecute, Page 104
Status, Page 111
Records Records, Page 84
VCI Re|etetce 6
Abuut
DccIaratiun
property About: TCrpeAboutBox;
Typc
TCrpeAboutBox = class(TForm)
Report DetailCopies, Page 19
DiscardSavedData, Page 21
HasSavedData, Page 47
Output, Page 58
ReportName, Page 85
ReportOptions, Page 87
ReportTitle, Page 89
Sections AreaFormat, Page 7
SectionFont, Page 90
SectionFormat, Page 93
SectionHeight, Page 98
SessionInfo SessionInfo, Page 105
Subreports Subreports, Page 112
SQL Connect, Page 13
ConnectMethod, Page 15
LogOnInfo, Page 52
LogOnServer, Page 54
SQL, Page 108
SQL Params property, Page 632
SummaryInfo SummaryInfo, Page 114
Tables Tables, Page 116
Version Version, Page 118
Window DialogParent, Page 20
WindowButtonBar, Page 119
WindowCursor, Page 121
WindowEvents, Page 123
WindowParent, Page 124
WindowSize, Page 126
WindowState, Page 127
WindowStyle, Page 128
WindowZoom, Page 130
Grou Proerly Name
VCI Re|etetce 7
Dcscriptiun
The About property is the first property in the Object Inspector and launches a dialog box which shows the
Version number of the Crystal Reports Component. The Version number is divided into four parts, i.e.:
7.4.0.0
The first number represents the highest Seagate Crystal Reports version supported:
5=SCR 5
6=SCR 6
7=SCR 7
The second number represents the Delphi version:
2=Delphi 2
3=Delphi 3
4=Delphi 4
The third number represents the VCL release version:
0=First release
The fourth number represents the release build-version:
0=First release build
ArcaFurmat
DccIaratiun
property AreaFormat: TCrpeAreaFormat;
Typc
TCrpeAreaFormat = class(TPersistent)
Dcscriptiun
AreaFormat controls how the area sections of a Report behave. It is similar to SectionFormat, except that
SectionFormat applies to individual sub-sections, whereas AreaFormat works on all of the sections of the same
type at once.
G The Section naming format has been adopted from the Crystal Reports "short" section naming
convention, so RH means ReportHeader, GH3 means GroupHeader 3, etc. See About Section Names,
Volume 1, Chapter 7, for more information.
G If the Retrieve method is used to get the Area information from the Report, the AreaFormat object will
be automatically populated with valid area section names, which appear in the Section property.
VCI Re|etetce 8
G If the manual Add method is used instead, the programmer will have to specify which section to add to
the object.
G The Count, Item, and ItemIndex properties can be used to navigate through the different section items
in the AreaFormat object.
G The Hide property will cause a section to be hidden, although drill-down is still possible. To suppress a
section so that it is not processed, and is not available for drill-down, use the Suppress property.
G The KeepTogether property will prevent a section from splitting on a page break. This is not the same as
KeepGroupTogether, which is available via the KeepTogether property of the GroupOptions object.
G The NewPageAfter and NewPageBefore properties determine if a page break will happen after or
before a particular section.
G The PrintAtBottomOfPage property will cause the section to appear at the bottom of the page.
G The ResetPageNAfter property will cause the Page Number to be reset after a particular section.
G The SectionAsCode property offers the ability to treat the Section name as a Section Code Number,
which can be useful for doing mathematical expressions to filter out certain sections.
G The SectionType method returns just the first characters of the Section name, so for GH1 (Group Header
1), the SectionType would be GH (Group Header).
limitatiuns
For Report Header (RH) areas, the NewPageBefore property does not apply.
For Report Footer (RF) areas, the NewPageAfter property does not apply.
For Page Header (PH) and Page Footer (PF) areas, the following options do not apply (setting them will have
no effect on the Report):
Hide
KeepTogether
NewPageAfter
NewPageBefore
PrintAtBottomOfPage
ArcaFurmat fxampIc
The code below retrieves the AreaFormat settings from the Report, then loops through looking for the Details
area, and sets various options for that area:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormat.Retrieve;
for cnt := 0 to (Crpe1.AreaFormat.Count - 1) do
begin
VCI Re|etetce 0
{Look for Details area}
if Crpe1.AreaFormat[cnt].Section = 'D' then
begin
Crpe1.AreaFormat[cnt].Hide := cFalse;
Crpe1.AreaFormat[cnt].KeepTogether := cTrue;
Crpe1.AreaFormat[cnt].NewPageAfter := cDefault;
Crpe1.AreaFormat[cnt].NewPageBefore := cDefault;
Crpe1.AreaFormat[cnt].PrintAtBottomOfPage := cFalse;
Crpe1.AreaFormat[cnt].ResetPageNAfter := cTrue;
Crpe1.AreaFormat[cnt].Suppress := cFalse;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
The following example hides the Details area of a Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormat.Retrieve;
Crpe1.AreaFormat.Section := 'D';
Crpe1.AreaFormat.Hide := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
ArcaFurmat Prupcrtics
AreaFormat Hide property, Page 214
AreaFormat Item property, Page 215
AreaFormat ItemIndex property, Page 215
AreaFormat KeepTogether property, Page 216
AreaFormat NewPageAfter property, Page 217
AreaFormat NewPageBefore property, Page 218
AreaFormat PrintAtBottomOfPage property, Page 218
AreaFormat ResetPageNAfter property, Page 219
AreaFormat Section property, Page 220
AreaFormat SectionAsCode property, Page 221
AreaFormat Suppress property, Page 222
VCI Re|etetce 16
ArcaFurmat Mcthuds
AreaFormat Add method, Page 223
AreaFormat Clear method, Page 224
AreaFormat CopyFrom method, Page 225
AreaFormat Count method, Page 225
AreaFormat Create method, Page 226
Area Format Delete method, Page 226
AreaFormat Destroy method, Page 226
AreaFormat Retrieve method, Page 227
AreaFormat SectionType method, Page 228
AreaFormat Send method, Page 228
ArcaFurmatFurmuIas
DccIaratiun
property AreaFormatFormulas: TCrpeAreaFormatFormulas;
Typc
TCrpeAreaFormatFormulas = class(TPersistent)
Dcscriptiun
The AreaFormatFormulas object can be used to specify formulas that control the AreaFormat options. In
Crystal Reports Designer, these formulas are found in the Formula buttons that appear beside each option in
the Section Format dialog box. AreaFormatFormulas apply formula control to the general areas of a report
(Report Header, Group Header 1, Details, etc.), whereas SectionFormatFormulas apply formula control to the
specific sections (Report Header a, Group Header 2b, Details c, etc.).
The Section naming format has been adopted from the Crystal Reports "short" section naming convention, so
RH means ReportHeader, GH3 means GroupHeader 3, etc. See About Section Names, Volume 1, Chapter 7, for
more information.
G The Section property specifies which report area the AreaFormatFormulas will apply to.
G The Name property specifies which formatting option the AreaFormatFormulas will apply to.
G The Formula property specifies the text of the Formula that is being applied.
G The Retrieve method can be used to get the AreaFormatFormulas information from the report.
G If the manual Add method is used instead, the programmer will have to specify which section to add to
the AreaFormatFormulas object.
VCI Re|etetce 11
G The Count method returns the number of items currently contained in the AreaFormatFormulas object.
G The Item, and ItemIndex properties can be used to navigate through the different section items in the
AreaFormat object.
G The IndexOf method will return the internal index number of the AreaFormatFormulas item that has a
Section name which matches the specified value.
G The SectionAsCode property offers the ability to treat the Section name as a Section Code Number,
which can be useful for doing mathematical expressions to filter out certain sections.
G The SectionType method returns just the first characters of the Section name, so for GH1 (Group Header
1), the SectionType would be GH (Group Header).
G The Names property can be used to navigate through the individual formulas available for a specified
section.
G The NameCount method can be used to set the subscript bounds when looping through the Names
property. IndexOfName and NameIndex are also useful in locating a specific Formula name within a
given AreaFormatFormulas item.
limitatiuns
AreaFormatFormulas has certain limitations similar to those of AreaFormat:
G For Report Header (RH) areas, the afNewPageBefore formula does not apply.
G For Report Footer (RF) areas, the afNewPageAfter formula does not apply. For Page Header (PH) and
Page Footer (PF) areas, the following formulas do not apply:
afHide
afKeepTogether
afNewPageAfter
afNewPageBefore
afPrintAtBottomOfPage
Attempting to assign values to the formulas for these areas will cause errors when the Report is run.
ArcaFurmatFurmuIas fxampIc
This example retrieves the AreaFormatFormula information, then assigns a Suppress formula to the Details
area, so that the Details area will be suppressed if the State is California:
Crpe1.ReportName := 'Company.rpt';
Crpe1.AreaFormatFormulas.Retrieve;
{Loop through the Areas}
for cnt := 0 to (Crpe1.AreaFormatFormulas.Count - 1) do
begin
{Check for Details area}
if Crpe1.AreaFormatFormulas[cnt].Section = 'D' then
VCI Re|etetce 12
begin
{Choose the Suppress formula}
Crpe1.AreaFormatFormulas[cnt].Name := afSuppress;
{Clear it from any previous formula}
Crpe1.AreaFormatFormulas[cnt].Formula.Clear;
{Add the new formula}
Crpe1.AreaFormatFormulas[cnt].Formula.Add('{company.STATE} = "CA"');
Break;
end;
end;
Crpe1.Execute;
ArcaFurmatFurmuIas Prupcrtics
AreaFormatFormulas Formula property, Page 229
AreaFormatFormulas Item property, Page 230
AreaFormatFormulas ItemIndex property, Page 231
AreaFormatFormulas Name property, Page 231
AreaFormatFormulas NameIndex Property, Page 234
AreaFormatFormulas Names Property, Page 235
AreaFormatFormulas Section property:, Page 235
AreaFormatFormulas SectionAsCode property, Page 237
ArcaFurmatFurmuIas Mcthuds
AreaFormatFormulas Add method, Page 238
AreaFormatFormulas Check method, Page 239
AreaFormatFormulas Clear method, Page 239
AreaFormatFormulas CopyFrom method, Page 240
AreaFormatFormulas Count method, Page 240
AreaFormatFormulas Create method, Page 241
AreaFormatFormulas Delete method, Page 241
AreaFormatFormulas Destroy method, Page 242
AreaFormatFormulas IndexOf method, Page 242
VCI Re|etetce 1!
CanCIuscfnginc
DccIaratiun
property CanCloseEngine: boolean;
Dcscriptiun
CanCloseEngine is a runtime, read-only property that determines whether or not the Crystal Reports Print
Engine can be closed. Use this function before calling CloseEngine to verify that the engine is no longer
processing print jobs. If the Print Engine closes while a print job is still running, an error can occur in your
application or on the user's system.
NO7F: 7he Cryslal comonenl wll aulomalcally close lhe Prnl Fngne when ls Deslroy melhod s called, or
when lhe Form l s on s deslroyed.
CanCIuscfnginc fxampIc
The CanCloseEngine property can be used to determine if the Print Engine is done processing jobs. In this
example the VCL is dynamically created and freed:
var
Crpe1: TCrpe;
begin
Crpe1 := TCrpe.Create(Self);
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
while not Crpe1.CanCloseEngine do
Application.ProcessMessages;
Crpe1.Free;
end;
NO7F: In lhe examle above, lhe CanCloseFngne wll nol relurn 7rue unll all Prnl )obs are lnshed
rocessng. Olher roerles such as Is)obFnshed, PrnlFnded, and Slalus wll work on jusl lhe currenl Prnl
)ob, and could be used nslead.
Cunncct
DccIaratiun
property Connect: TCrpeConnect;
Typc
TCrpeConnect = class(TPersistent)
VCI Re|etetce 14
Dcscriptiun
The Connect object contains the properties that refer to the Report LogOn information required to connect to
an ODBC or SQL datasource. It has the same four basic properties as LogOnInfo:
ServerName
UserID
Password
DatabaseName
Whereas LogOnInfo allows different LogOn parameters for each table, Connect takes one set of parameters
and applies them to all the tables in a Report. Therefore, if a Report is designed with tables from more than
one Server, LogOnInfo should be used instead of Connect. However, if the main Report uses one Server, and
the Subreport uses another, then Connect can still be used, since it can apply to Subreports as well.
G The Retrieve method will obtain the ServerName, UserID, and DatabaseName from the current Report,
and fill the Connect properties with those values. If these values are to remain the same as when the
Report was designed, all that needs to be supplied is the Password.
G The Test method can be used to test the connection once the four basic properties have been filled in.
G The Propagate property is designed to take the LogOn information from the main Report and use it for
the Subreports as well. If Propagate is set to True for the main Report, the Connect information from
the main Report will be used for all the Subreports. But if Propagate is set to True on a Subreport, then
only that Subreport will use the Connect parameters set in the main Report. See the Example for an
illustration of this.
NO7F: Imorlanl! In order lo use lhe IogOnInlo roerles, lhe Cre1.ConneclMelhod roerly musl be sel lo
useConnecl. 7hs sellng lells lhe VCIs Fxecule melhod whch class lo use lor conneclng: Connecl or IogOnInlo.
NO7F: When runnng a Reorl lhal requres lhe Connecl roerles lo be sel (mosl SQI dalabases), make sure
lhal lhe roer lles have been nslalled n order lor lhe conneclon lo succeed:
G Il lhe conneclon s beng eslablshed va an ODBC Dala Source, make sure lhe ODBC drver has been
nslalled, and lhe Dala Source has been roerly conlgured on lhe comuler.
G Il lhe conneclon s beng eslablshed va Cryslals nalve SQI drvers, make sure lhe Clenl layer has
been nslalled and lhal lhe Dalabase/BIN localon s n lhe PA7H slalemenl ol lhe AU7OFXFC.BA7 lle.
Cunncct fxampIc
The following code will use the Connect parameters for the main Report and apply them to all Subreports also:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ConnectMethod := useConnect;
Crpe1.Connect.Retrieve;
Crpe1.Connect.Password := 'Agent86';
Crpe1.Connect.Propagate := True;
Crpe1.Execute;
VCI Re|etetce 1S
This example will apply the Connect parameters from the main Report to the first Subreport only:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ConnectMethod := useConnect;
{Retrieve the Subreports}
Crpe1.Subreports.Retrieve;
{Set the Connect Parameters}
Crpe1.Connect.Retrieve;
Crpe1.Connect.Password := 'Agent86';
{Switch to Subreport 1}
Crpe1.Subreports[1];
{Set the Connect Propagate flag for Subreport 1}
Crpe1.Connect.Propagate := True;
Crpe1.Execute;
Cunncct Prupcrtics
Connect DatabaseName property, Page 248
Connect Password property, Page 249
Connect Propagate property, Page 250
Connect ServerName property, Page 251
Connect UserID property, Page 251
Cunncct Mcthuds
Connect Clear method, Page 252
Connect CopyFrom method, Page 253
Connect Create method, Page 253
Connect Retrieve method, Page 253
Connect Send method, Page 254
Connect Test method, Page 255
CunncctMcthud
DccIaratiun
property ConnectMethod: TCrConnectMethod;
Typc
TCrConnectMethod = (useConnect, useLogOnInfo);
VCI Re|etetce 16
Dcscriptiun
The ConnectMethod property is used to tell the VCL which connection method will be used to set the log on
information for Reports using SQL tables or ODBC datasources that require passwords. There are two classes
in the VCL that can set this information: Connect and LogOnInfo. Trying to determine which one was to be
used when the VCL ran a Report was not always easy, so the ConnectMethod property was created to make
this more clear.
By default, ConnectMethod is set to useConnect.
NO7F: 7hs roerly ales lo lhe whole Reorl, ncludng Subreorls. 7herelore, l s nol ossble, lor
examle, lo use Connecl on lhe man Reorl and IogOnInlo on lhe Subreorl. Il ConneclMelhod s sel lo
useConnecl, lhe Connecl class wll be used lor lhe man Reorl and any Subreorls. Il ConneclMelhod s sel lo
useIogOnInlo, lhe IogOnInlo class wll be used lor lhe man Reorl and any Subreorls.
CunncctMcthud fxampIc
This code sets the ConnectMethod to useConnect, then fills in the Connect Password property:
Crpe1.ReportName := 'C:\Company.rpt';
{Set the ConnectMethod}
Crpe1.ConnectMethod := useConnect;
{Retrieve the Connect information from the Report}
Crpe1.Connect.Retrieve;
{Set the Connect Password}
Crpe1.Connect.Password := '007';
{Propagate the Connect property values to any Subreports}
Crpe1.Connect.Propagate := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
This code sets the ConnectMethod to useLogOnInfo, then fills in the LogOnInfo Password property:
var
cnt : integer;
begin
Crpe1.ReportName := 'c:\Company.rpt';
{Set the ConnectMethod}
Crpe1.ConnectMethod := useLogOnInfo;
{Retrieve the LogOnInfo information from the Report}
Crpe1.LogOnInfo.Retrieve;
{Set the LogOnInfo Password for all tables}
for cnt := 0 to (Crpe1.LogOnInfo.Count - 1) do
Crpe1.LogOnInfo[cnt].Password := '007';
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
VCI Re|etetce 17
DcsignCuntruIs
DccIaratiun
property DesignControls: TCrpeDesignControlsDlg;
Typc
TCrpeDesignControlsDlg = class(TForm)
Dcscriptiun
The DesignControls property is a design time-only property. Clicking the dialog button on the Object Inspector,
or running it from the component menu (right-click on the component to get the menu), will bring up a small
button-bar dialog box which can be used to load, retrieve, run, and page through Reports at design time.
Rcpurt Buttuns
These buttons are on the first row of the DesignControls dialog box and control the opening, closing, retrieving
and running of Reports from the Delphi design time editor.
Opcn Rcpurt
This button brings up the Open Dialog box to choose a Report to load. It updates the ReportName property
with the new choice.
CIusc Rcpurt
This button closes the currently open Report, and clears the ReportName property. It is equivalent to calling
CloseWindow, CloseJob, and clearing ReportName in code.
VCI Re|etetce 18
Rctricvc Data
This button brings up the Retrieve Report Data dialog box:
This dialog box allows you to choose which items you would like to retrieve report data for. Any items that
are checked will have their data retrieved from the Report into the VCL when the Retrieve button is clicked.
From there, the data can be edited in the Object Inspector, and then the report can be previewed to see the
effect of the changes.
Quick Prcvicw
This button runs the Report to whichever destination is specified in the Output property.
Prcvicw Rcpurt
This button runs the Report to a Preview Window. If the WindowParent property has been set to the current Form,
or a Panel on the Form, the Preview Window will be attached to that Form or Panel. When the Preview Window is
attached to another Form or Panel, the Window controls will be inaccessible at design-time. Therefore, the other
buttons on the DesignControls dialog box can be used to page through or close the Preview Window.
Print Rcpurt
This button runs the Report to a printer. The Print dialog box will appear to allow you to choose the destination
printer.
VCI Re|etetce 10
fxpurt Rcpurt
This button exports the Report. You will be prompted for the Export options. This is accomplished by setting
the PromptForOptions property of the Export object to True.
Winduw Buttuns
These buttons are on the second row of the Design Controls dialog box and control the closing, paging and
zoom level of the Preview Window of a Report run from the Design Controls dialog box. These controls are
especially useful when the WindowParent property has been set to a Form or Panel, in which case the Preview
Window controls will not be accessible at design-time.
CIusc Winduw
This button can be used to close the currently open Preview Window.
First Pagc
This button can be used to go to the first page of the currently open Preview Window.
Prcviuus Pagc
This button can be used to go to the previous page of the currently open Preview Window.
Ncxt Pagc
This button can be used to go to the next page of the currently open Preview Window.
last Pagc
This button can be used to go to the last page of the currently open Preview Window.
CanccI
This button can be used to cancel the processing of a Report after the Preview, Print, or Export buttons have
been clicked. It is equivalent to calling CancelJob in code.
Zuum
This button changes the Zoom level of the currently open Preview Window.
DctaiICupics
DccIaratiun
property DetailCopies: integer;
Dcscriptiun
The DetailCopies property determines how many times the Details band of the Report will print out. This is
normally used for Mailing Label-style Reports, where more than one label may be desired for each customer
in a list. This property can also be applied to Subreports.
VCI Re|etetce 26
DctaiICupics fxampIc
This code sample sets the DetailCopies to 2. The Details area of the Report will be printed out twice per record.
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.DetailCopies := 2;
Crpe1.Output := toPrinter;
Crpe1.Execute;
DiaIugParcnt
DccIaratiun
property DialogParent: TCrWinControl;
Typc
TCrWinControl = TWinControl;
Dcscriptiun
DialogParent is a run-time only property that causes the Preview Window dialogs to have the same Z-Order
as the Parent Form they are attached to. Z-Order affects the order in which windows are drawn on the screen,
so in this case, the Preview Window dialog boxes would be brought to the front of the screen when the Parent
Form is brought to the front. In this situation, care must be taken not to close the Parent Form while the Crystal
Preview Window is writing to one of the dialog boxes.
To set DialogParent, simply assign it the name of the Form or Panel desired.
DiaIugParcnt fxampIc
In this example. the Preview Window dialogs will have the same Z-Order as Form1:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.DialogParent := Form1;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 21
DiscardSavcdData
DccIaratiun
property DiscardSavedData: boolean;
Dcscriptiun
A Report can be created with Saved Data. This means that the data it was last run with is saved with the
Report, and unless it is discarded, the Report will by default run with the Saved Data instead of reading the
Database. This is sometimes desirable, such as when a Report is being distributed to users who do not have
access to the Database but would like to preview and print the Reports anyway.
In most other cases, applications that call Reports should make sure they discard the Saved Data. Setting this
property to True will do that. The HasSavedData property can also be checked to see if the Report has Saved
Data or not.
Note that if a Report is executed at runtime, and it is still the currently loaded Report in the VCL, running it
again will cause it to use the Saved Data from the previous run. Therefore, if running a Report more than once
in a row, with different parameters, make sure and set DiscardSavedData to True between each run.
DiscardSavcdData fxampIc
This code example sets the DiscardSavedData property to True. Any data saved with the Report, either when
the Report was saved in Crystal Reports Designer, or because the Report was run once already, will be
discarded:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.DiscardSavedData := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
fxpurt
DccIaratiun
property Export: TCrpeExport;
Typc
TCrpeExport = class(TPersistent)
VCI Re|etetce 22
Dcscriptiun
The Export object is one of the largest in the Crystal component and contains all the options that apply to
exporting a Report to one of the supported Export formats. In order to have the Export options apply, the
Output property of the Crystal component must be set to Export.
G The Destination property determines if the exported file will go to File, to E-mail, to Exchange Folder, or
to Application.
G The FileName property applies if going to disk file.
G The FileType property determines what the export type will be (RTF, Ascii, HTML, ODBC, etc.).
G The Email object contains the properties that apply if the Destination is set to Email. When exporting to
Email, the FileName property will not apply, but the FileName will be taken from the ReportName.
One exception to this rule is the HTML format, in which a FileName can be specified when exporting to
Email.
G The Exchange object contains the properties that apply if the Destination is set to Exchange.
G The ODBC object contains the properties that apply if the Destination is set to ODBCTable.
G The Excel5Ext object contains the properties that apply if the FileType is set to Excel5Extended.
G The CharSepQuote and CharSepSeparator properties apply if the FileType is set to CharacterSeparated.
G The LinesPerPage property applies if the FileType is set to PaginatedText.
G The UseRptDateFmt and UseRptNumberFmt properties apply if the FileType is set to one of the
following: Records, TabSeparated, Dif, Csv, or CharacterSeparated.
G The PromptOnOverwrite property determines if a warning dialog box will appear if the file specified in
the FileName property already exists (assuming that the Destination is set to go toFile).
G The PromptForOptions property will cause all the Export settings to be ignored, and will instead
prompt the user for the various options.
G The AppName property applies if the Destination is set to Application.
The Clear property can be used to set the Export object back to its default values. These defaults consist of
clearing all the string fields, and setting the following properties:
FileType := Ascii;
Destination := toFile;
UseRptNumberFmt := TCRPE_DEFAULT_USERPTNUMBERFMT;
UseRptDateFmt := TCRPE_DEFAULT_USERPTDATEFMT;
LinesPerPage := TCRPE_DEFAULT_LINESPERPAGE;
ColumnHeadings := False;
PromptForOptions := False;
PromptOnOverwrite := False;
TCRPE_DEFAULT_USERPTNUMBERFMT= True;
TCRPE_DEFAULT_USERPTDATEFMT = True;
TCRPE_DEFAULT_LINESPERPAGE = 60;
VCI Re|etetce 2!
fxpurt fxampIc
Exporting to File in Ascii format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := Ascii;
Crpe1.Export.FileName := 'C:\MyReport.txt';
Crpe1.Execute;
Exporting to File in ODBCTable format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toFile;
FileType := ODBCTable;
ODBC.Source := 'SQLServer';
ODBC.User := 'Maxwell Smart';
ODBC.Password := 'Agent86';
ODBC.Table := 'ReportTable';
end;
Crpe1.Execute;
Export to Email in HTML format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toEmailViaMapi;
FileType := HTML30;
FileName := 'C:\MyReport.htm';
Email.ToList := 'Maxwell Smart';
Email.CCList := 'The Chief';
Email.Subject := 'Chaos';
Email.Message := 'Would you believe...';
end;
Crpe1.Execute;
VCI Re|etetce 24
Export to Exchange Folder in PaginatedText format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toMSExchange;
FileType := PaginatedText;
LinesPerPage := 25;
Exchange.Profile := 'Microsoft Outlook';
Exchange.Folder := 'Personal Folders@Inbox';
Exchange.Password := 'Agent86';
end;
Crpe1.Execute;
fxpurt Prupcrtics
Export AppName property, Page 255
Export CharSepQuote property, Page 256
Export CharSepSeparator property, Page 257
Export Destination property, Page 258
Export Email property, Page 260
G Properties
Export Email CCList property, Page 261
Export Email Message property, Page 261
Export Email Subject property, Page 262
Export Email ToList property, Page 263
Export Email VIMBCCList property, Page 263
G Methods
Export Email Clear method, Page 264
Export Email CopyFrom method, Page 265
Export Excel5Ext property, Page 265
G Properties
Export Excel5Ext Area property, Page 266
Export Excel5Ext ColumnHeadings property, Page 267
Export Excel5Ext ColumnWidth property, Page 268
Export Excel5Ext Constant property, Page 269
Export Excel5Ext TabularFormat property, Page 269
VCI Re|etetce 2S
G Methods
Export Excel5Ext Clear method, Page 270
Export Excel5Ext CopyFrom method, Page 270
Export Excel5Ext Create method, Page 271
Export Exchange Property, Page 271
G Properties
Export Exchange Folder property, Page 272
Export Exchange Password property, Page 273
Export Exchange Profile property, Page 274
G Methods
Export Exchange Clear method, Page 274
Export Exchange CopyFrom method, Page 275
Export FileName property, Page 276
Export FileType property, Page 277
Export LinesPerPage property, Page 279
Export ODBC Property, Page 279
G Properties
Export ODBC Password property, Page 281
Export ODBC Source property, Page 281
Export ODBC Table property, Page 282
Export ODBC User property, Page 283
G Methods
Export ODBC Clear method, Page 283
Export ODBC CopyFrom method, Page 284
Export PromptForOptions property, Page 284
Export PromptOnOverwrite property, Page 286
Export UseRptDateFmt property, Page 286
Export UseRptNumberFmt property, Page 287
fxpurt Mcthuds
Export Clear method, Page 288
Export CopyFrom method, Page 289
VCI Re|etetce 26
Export Create method, Page 289
Export Destroy method, Page 290
Export Send method, Page 290
FicIdMapping
DccIaratiun
property FieldMapping: TCrFieldMappingType;
Typc
TCrFieldMappingType = (fmAuto, fmPrompt, fmEvent);
Dcscriptiun
FieldMapping can be used to provide a way to remap database field names in a Report if the field names have
changed since the Report was designed. If the field names stored in the Report no longer match the physical
database table field names, the fields in the Report are considered to be "unmapped". The FieldMapping
setting is used in the VerifyDatabase method to determine how unmapped fields will be handled.
VerifyDatabase will cause the Print Engine to do one of three things, depending on the setting of the
FieldMapping property:
1. FieldMapping set to fmAuto
Any fields in the Report that no longer have the same field names will be removed from the Report.
2. FieldMapping set to fmPrompt
If any field names have changed, the Print Engine will show a Mapping dialog box that can be used to
map the fields to fields from the current database table.
3. FieldMapping set to fmEvent
If any field names have changed, an OnFieldMapping event will be triggered. This event is on the events
page of the Object Inspector, and allows the developer to either design their own Mapping dialog box, or
bypass the dialog box by doing the mapping in code.
NO7F: FeldMang s only avalable n SCR 7 or hgher. 7he aclual sequence ol calls made lo nvoke
FeldMang should lollow lhs order:
G Sel lhe ReorlName roerly.
G Sel any IogOn Inlormalon (l usng ODBC or SQI lables) va elher Connecl, IogOnInlo, or
IogOnServer.
G Sel any new 7able localon nlormalon va lhe 7ables objecl.
G Sel lhe FeldMang roerly.
G Call VerlyDalabase.
Allernalvely, l VerlyDalabase s nol called dreclly n code, l wll aulomalcally run when Cre1.Fxecule s called.
VCI Re|etetce 27
FicIdMapping fxampIc
If the database structure or field names have changed, the following code will bring up Crystal's built-in Field
Mapping dialog box:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.FieldMapping := fmPrompt;
Crpe1.VerifyDatabase;
FurmuIas
DccIaratiun
property Formulas: TCrpeFormulas;
Typc
TCrpeFormulas = class(TPersistent)
Dcscriptiun
The Formulas object contains all the properties that apply to Formulas in a Report.
G The Name property specifies the name of the formula.
G The Formula property holds the formula text.
G The default array property Item, and the ItemIndex property, can be used to navigate through the
various formulas that may be stored in the Formulas object.
G Formulas may be retrieved from the Report via the Retrieve method.
G The Add/Delete methods can be used instead of Retrieve/Clear to manually add and remove items in
the Formulas object.
G The Check method provides an easy way of checking the syntax of the Formula text before running the
Report.
Formulas are a very powerful feature in Crystal Reports and besides their normal summary functions, can be
used at runtime to control everything from Section and Field formatting to Grouping and Sorting.
FurmuIas fxampIc
The following procedures show how easy it is to use the features of the new VCL in the Delphi environment.
The components placed on the Form are:
TListBox - lbFormulaNames
TMemo - memoFormulas
TButton - FormulaCheck
VCI Re|etetce 28
The Button click event is associated with this procedure:
procedure btnFormulaCheckClick(Sender: TObject);
The ListBox click event is associated with this procedure:
procedure lbFormulaNamesClick(Sender: TObject);
The Memo change event is associated with this procedure:
procedure memoFormulasChange(Sender: TObject);
This procedure initializes the Form's components with data from the Report:
procedure UpdateForm;
The Formula names are loaded into the ListBox in the UpdateForm procedure. When a name is clicked in the
ListBox, the Memo component becomes updated with the Formula Text associated with that formula name.
When the formula is edited in the memo, it is written back to the Crystal component's Formula Text property.
Finally, when the button is clicked, the Formula is checked to see if the syntax is good.
{UpdateForm procedure}
procedure TfrmMain.UpdateForm;
var
cnt: smallint;
begin
lbFormulaNames.Clear;
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Formulas.Retrieve;
{Loop through Formulas and add Formula Names to ListBox}
if Crpe1.Formulas.Count > 0 then
begin
for cnt := 0 to (Crpe1.Formulas.Count - 1) do
begin
Crpe1.Formulas[cnt];
lbFormulaNames.Items.Add(Crpe1.Formulas.Name);
end;
lbFormulaNames.ItemIndex := 0;
lbFormulaNamesClick(Self);
end;
end;
{lbFormulaNamesClick procedure}
{Notice how we disable the Memo OnChange event. If we
don't do this, it will write back the first line to the
VCL, overwriting the rest of the formula stored there}
VCI Re|etetce 20
procedure TfrmMain.lbFormulaNamesClick(Sender: TObject);
begin
Crpe1.Formulas[lbFormulaNames.ItemIndex];
{Disable the OnChange event.}
memoFormulas.OnChange := nil;
{Copy the Formula from the VCL}
memoFormulas.Lines.Assign(Crpe1.Formulas.Formula);
{Re-enable the OnChange event}
memoFormulas.OnChange := memoFormulasChange;
end;
{memoFormulasChange procedure}
procedure TfrmMain.memoFormulasChange(Sender: TObject);
begin
Crpe1.Formulas.Formula.Assign(memoFormulas.Lines);
end;
{btnFormulaCheckClick procedure}
procedure TfrmMain.btnFormulaCheckClick(Sender: TObject);
begin
if Crpe1.Formulas.Check then
ShowMessage('Formula is good')
else
ShowMessage('Formula has an error');
end;
FurmuIas Prupcrtics
Formulas Formula property, Page 290
Formulas Item property, Page 291
Formulas ItemIndex property, Page 292
Formulas Name property, Page 293
FurmuIas Mcthuds
Formulas Add method, Page 293
Formulas Check method, Page 294
Formulas Clear method, Page 295
Formulas CopyFrom method, Page 296
Formulas Count method, Page 296
Formulas Create method, Page 297
VCI Re|etetce !6
Formulas Delete method, Page 297
Formulas Destroy method, Page 298
Formulas IndexOf method, Page 298
Formulas Retrieve method, Page 299
Formulas Send method, Page 300
GraphData
DccIaratiun
property GraphData: TCrpeGraphData;
Typc
TCrpeGraphData = class(TPersistent)
Dcscriptiun
The GraphData object contains the properties and methods required to change the data that a Graph is based on.
G The Number property specifies the Graph Number, and can be used as a lookup value to point the
GraphType object to a specific GraphType item. See How Graphs are Numbered, Page 37, for more
information on the numbering scheme.
G The Section property specifies the section that the Graph is located in, and uses the "short" section
naming convention used in the Crystal Reports Designer. See About Section Names, Volume 1, Chapter 7,
for more information.
G The Retrieve method can be used to fill the GraphData object with information from the Report.
G The Count method will indicate the number of GraphData items currently stored in the GraphData
object.
G The Item, and ItemIndex properties can be used to navigate through the GraphData items in the
GraphData object.
G The RowGroupN property specifies which Group number in the report is used to create the values in
the rows of the Graph. Use -1 for default. Group numbers start with 1.
G The ColGroupN property specifies which Group number in the report is used to create the values in the
columns of the Graph. Use -1 for Default. Group numbers start with 1.
G The SummarizedFieldN property specifies which Summary field in the report is used to set the values
of the risers in the Graph. Summary fields are numbered in order of their creation. Use -1 for default.
Summary Field numbers start with 0.
VCI Re|etetce !1
G The Direction property is used to specify in what direction a Graph will read its data from the Report.
For normal Group/Total Graph, the Direction, is always Cols. For Cross-Tab Graphs, use any of the
following TCrGraphDirection values:
G The SectionAsCode property offers the ability to treat the Section name as a Section Code Number,
which can be useful for doing mathematical expressions to filter out certain sections.
G The SectionType method returns just the first characters of the Section name, so for GH1 (Group Header
1), the SectionType would be GH (Group Header).
NO7F: Grahs based on Formulas or Delals nslead ol Grous, wll nol have GrahDala.
GraphData fxampIc
The sample code below illustrates the use of the GraphData object to change the Summary Field that the Graph
is based on:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphData.Retrieve;
if Crpe1.GraphData.Count > 0 then
Crpe1.GraphData[0].SummarizedFieldN := 1;
Crpe1.Execute;
GraphData Prupcrtics
GraphData ColGroupN property, Page 301
GraphData Direction property, Page 301
GraphData Item property, Page 302
GraphData ItemIndex property, Page 303
GraphData Number property, Page 304
GraphData RowGroupN property, Page 305
GraphData Section property, Page 305
GraphData SectionAsCode property, Page 306
GraphData SummarizedFieldN property, Page 307
7CrGrahDreclon Meanng
Rows Use only row values in graph.
Cols Use only column values in graph.
RowCol Graph by row values, then by column values.
ColRow Graph by column values, then by row values.
Unknown The direction of the graph is unknown.
VCI Re|etetce !2
GraphData Mcthuds
GraphData Add method, Page 308
GraphData Clear method, Page 308
GraphData CopyFrom method, Page 309
GraphData Count method, Page 310
GraphData Create method, Page 310
GraphData Delete method, Page 310
GraphData Destroy method, Page 311
GraphData Retrieve method, Page 311
GraphData SectionType method, Page 312
GraphData Send method, Page 313
GraphOptiuns
DccIaratiun
property GraphOptions: TCrpeGraphOptions;
Typc
TCrpeGraphOptions = class(TPersistent)
Dcscriptiun
The GraphOptions object contains all the properties and methods that relate to changing the features of the
appearance of Graphs.
G The Number property specifies the Graph Number, and can be used as a lookup value to point the
GraphOptions object to a specific GraphOptions item. See How Graphs are Numbered, Page 37 for more
information on the numbering scheme.
G The Section property specifies the section that the Graph is located in, and uses the "short" section
naming convention used in the Crystal Reports Designer. See About Section Names, Volume 1, Chapter 7,
for more information.
G The Retrieve method can be used to fill the GraphOptions object with information from the Report.
G The Count property will indicate how many GraphOptions items are currently in the GraphOptions object.
G The Item and ItemIndex properties can be used to navigate through the GraphOptions items in the
GraphOptions object.
VCI Re|etetce !!
G The Max property specifies the maximum value that will appear in the Graph. Any Graph values above
this value are not charted.
G The Min property specifies the minimum value that will appear in the Graph. Any Graph values below
this value are not charted.
G The DataValues property specifies whether or not to display the numeric value associated with each
riser on the chart. If set to cTrue, a value appears in the Graph for each riser.
G The GridLines property specifies whether or not to display Grid Lines on the Graph.
G The BarDirection property specifies which way to display the bars in a Bar Graph: vertically or horizontally.
G The Legend property specifies whether or not to display the Graph Legend.
G The Font property specifies the Font for all text and values in the entire Graph.
G The SectionAsCode property offers the ability to treat the Section name as a Section Code Number,
which can be useful for doing mathematical expressions to filter out certain sections.
G The SectionType method returns just the first characters of the Section name, so for GH1 (Group Header
1), the SectionType would be GH (Group Header).
GraphOptiuns fxampIc
This code sample shows how to retrieve the GraphOptions from a Report, then change various properties for
the first Graph:
Crpe1.ReportName := 'C:\Company.rpt';
with Crpe1.GraphOptions do
begin
Retrieve;
Item[0];
GridLines := cTrue;
Font := 'Times New Roman';
DataValues := cFalse;
BarDirection := bdVertical;
Legend := cTrue;
end;
Crpe1.Execute;
GraphOptiuns Prupcrtics
GraphOptions BarDirection property, Page 314
GraphOptions DataValues property, Page 314
GraphOptions Font property, Page 315
GraphOptions GridLines property, Page 315
GraphOptions Item property, Page 316
GraphOptions ItemIndex property, Page 317
GraphOptions Legend property, Page 317
VCI Re|etetce !4
GraphOptions Max property, Page 318
GraphOptions Min property, Page 318
GraphOptions Number property, Page 319
GraphOptions Section property, Page 320
GraphOptions SectionAsCode property, Page 321
GraphOptiuns Mcthuds
GraphOptions Add method, Page 321
GraphOptions Clear method, Page 322
GraphOptions CopyFrom method, Page 323
GraphOptions Count method, Page 324
GraphOptions Create method, Page 324
GraphOptions Delete method, Page 324
GraphOptions Destroy method, Page 325
GraphOptions Retrieve method, Page 325
GraphOptions SectionType method, Page 326
GraphOptions Send method, Page 327
GraphTcxt
DccIaratiun
property GraphText: TCrpeGraphText;
Typc
TCrpeGraphText = class(TPersistent)
Dcscriptiun
The GraphText object contains the properties and methods required to change the text on a Graph.
G The Number property specifies the Graph Number, and can be used as a lookup value to point the
GraphType object to a specific GraphType item. See How Graphs are Numbered, Page 37, for more
information on the numbering scheme.
G The Section property specifies the section that the Graph is located in, and uses the "short" section
naming convention used in the Crystal Reports Designer. See About Section Names, Volume 1, Chapter 7,
for more information.
VCI Re|etetce !S
G The Retrieve method can be used to fill the GraphText object with information from the Report.
G The Count method will indicate how many GraphText items are currently in the GraphText object.
G The Item and ItemIndex properties can be used to navigate through the GraphText items in the
GraphText object.
G The Title property specifies the main title text that will appear above the Graph.
G The SubTitle property specifies the subtitle text that will appear directly under the main Title.
G The FootNote property specifies the footnote text that will appear under the Graph.
G The GroupsTitle property specifies the title of the Groups which are being graphed.
G The SeriesTitle property specifies the title of the Series which is being graphed.
G The XAxisTitle property specifies the title text that will appear for the X axis. Not valid for Pie graphs.
G The YAxisTitle property specifies the title text that will appear for the Y axis. Not valid for Pie graphs.
G The ZAxisTitle property specifies the title text that will appear for the Z axis. This value is only valid for
3D graphs.
G The SectionAsCode property offers the ability to treat the Section name as a Section Code Number,
which can be useful for doing mathematical expressions to filter out certain sections.
G The SectionType method returns just the first characters of the Section name, so for GH1 (Group Header
1), the SectionType would be GH (Group Header).
GraphTcxt fxampIc
The following example retrieves the GraphText information from the Report, then changes the various
GraphText properties for the first Graph:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
if Crpe1.GraphText.Count > 0 then
begin
Crpe1.GraphText[0].Title := 'New Title';
Crpe1.GraphText[0].SubTitle := 'New Sub Title';
Crpe1.GraphText[0].SeriesTitle := 'New Series Title';
Crpe1.GraphText[0].FootNote := 'New FootNote';
Crpe1.GraphText[0].GroupsTitle := 'New Groups Title';
Crpe1.GraphText[0].SeriesTitle := 'New Series Title';
Crpe1.GraphText[0].XAxisTitle := 'New XAxis Title';
Crpe1.GraphText[0].YAxisTitle := 'New YAxis Title';
Crpe1.GraphText[0].ZAxisTitle := 'New ZAxis Title';
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce !6
GraphTcxt Prupcrtics
GraphText FootNote property, Page 328
GraphText GroupsTitle property, Page 328
GraphText Item property, Page 329
GraphText ItemIndex property, Page 330
GraphText Number property, Page 330
GraphText Section property, Page 331
GraphText SectionAsCode property, Page 332
GraphText SeriesTitle property, Page 333
GraphText SubTitle property, Page 334
GraphText Title property, Page 334
GraphText XAxisTitle property, Page 335
GraphText YAxisTitle property, Page 335
GraphText ZAxisTitle property, Page 336
GraphTcxt Mcthuds
GraphText Add method, Page 337
GraphText Clear method, Page 338
GraphText CopyFrom method, Page 338
GraphText Count method, Page 339
GraphText Create method, Page 339
GraphText Delete method, Page 340
GraphText Destroy method, Page 340
GraphText Retrieve method, Page 340
GraphText SectionType method, Page 341
GraphText Send method, Page 342
GraphTypc
DccIaratiun
property GraphType: TCrpeGraphType;
Typc
TCrpeGraphType = class(TPersistent)
VCI Re|etetce !7
Dcscriptiun
The GraphType object contains the properties and methods needed to change the style of the Graphs that are
in a Report.
G The Number property specifies the Graph Number, and can be used as a lookup value to point the
GraphType object to a specific GraphType item. See How Graphs are Numbered, Page 37, for more
information on the numbering scheme.
G The Section property specifies the section that the Graph is located in, and uses the "short" section
naming convention used in the Crystal Reports Designer. See About Section Names, Volume 1, Chapter 7,
for more information.
G The Style property specifies the actual Graph Type.
G The Retrieve property can be used to fill the GraphType object with information about each Graph.
G Alternatively, the manual Add method can also be used, but the actual Graph Number, as well as the
Section it is in, will need to be specified.
G The SectionAsCode property offers the ability to treat the Section name as a Section Code Number,
which can be useful for doing mathematical expressions to filter out certain sections.
G The SectionType method returns just the first characters of the Section name, so for GH1 (Group Header
1), the SectionType would be GH (Group Header).
Huw Graphs arc Numbcrcd
The Crystal Reports Print Engine numbers Graphs from top to bottom and left to right within a section.
Therefore, it is possible to have more than one Graph with the same number, since they reside in different
sections. This is why it is necessary to specify both a Graph Number and a Graph Section for each Graph that
will be changed. In the Crystal Reports VCL component, there are two ways of dealing with Graph numbering:
Thc Rctricvc mcthud
If the Retrieve method is used for obtaining Graph information (GraphType, GraphText, GraphOptions,
GraphData) from a Report, then the Crystal component stores the actual Print Engine Graph Number
internally, and uses a modified numbering system for the Number property, whereby the Graphs are
numbered per Report, and not per Section. In this way, each Graph has a unique Number value. The Section
property still shows the proper Section value, but the Graphs are numbered uniquely, so there are no
duplicates. This was necessary so that Number could be used as a lookup property in the Object Inspector.
Thc Add mcthud
If the Add method is used to manually add an Graph item to one of the VCL component's Graph objects
(GraphType, GraphData, GraphOptions, GraphText), then the original Print Engine numbering scheme
should be used. This requires that the developer have a good knowledge of what each Report contains, and
where the Graphs are placed.
It is recommended that the Retrieve method be used as much as possible, as it is less error-prone, does not
require the developer to know before-hand the actual Graph number and Section for each Graph, and is easier
to deal with (i.e. no duplicate numbers).
VCI Re|etetce !8
GraphTypc fxampIc
This example retrieves the GraphType information from the Report and then changes the Style to 3D Bars:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphType.Retrieve;
if Crpe1.GraphType.Count > 0 then
begin
Crpe1.GraphType[0].Style := ThreeDBars;
Crpe1.Execute;
end;
GraphTypc Prupcrtics
GraphType Item property, Page 343
GraphType ItemIndex property, Page 343
GraphType Number property, Page 344
GraphType Section property, Page 345
GraphType SectionAsCode property, Page 346
GraphType Style property, Page 346
GraphTypc Mcthuds
GraphType Add method, Page 348
GraphType Clear method, Page 349
GraphType CopyFrom method, Page 349
GraphType Count method, Page 350
GraphType Create method, Page 350
GraphType Delete method, Page 351
GraphType Destroy method, Page 351
GraphType Retrieve method, Page 351
GraphType SectionType method, Page 352
GraphType Send method, Page 353
VCI Re|etetce !0
GruupCunditiun
DccIaratiun
property GroupCondition: TCrpeGroupCondition;
Typc
TCrpeGroupCondition = class(TPersistent)
Dcscriptiun
The GroupCondition object contains the properties that refer to the Grouping fields in a Report. Unlike
SortFields and GroupSortFields, a GroupCondition cannot be added or deleted from a Report at runtime.
However, it is possible to set all the Groups to the same field, thus in effect nullifying all but one of them. The
main properties in GroupCondition are:
G The Number property represents the actual Group number in the Report, and unlike most of the other
numbering in the component, Groups start with number 1. This is easier to remember, since in the
Crystal Reports Designer there is no such thing as Group 0.
G The Field property specifies the actual field value that the Group is based on, which could be a database
field, or a formula field. Remember to enclose database fields in braces {}, and to prefix formula names
with the @ symbol.
G The Condition property specifies the condition that the Group changes on.
G The Direction property specifies in which order the Groups will be sorted.
G The Retrieve method can be used to retrieve and fill the GroupCondition object with values from the Report.
G The Count method will return how many items are in the GroupCondition object (i.e. how many groups
are in the Report), and can be used for looping constructs.
G The Number property, the default array property Item, and the ItemIndex property can be used to
navigate through the items in the GroupCondition object.
NO7F: Il you have Cryslal Reorls 6.0, GrouOlons can be used nslead ol GrouCondlon. Il has all lhe
lunclonally ol GrouCondlon, lus 7oN roerles, and olher lealures as well.
VCI Re|etetce 46
GruupCunditiun fxampIc
This sample retrieves the GroupCondition values from the Report, and sets the first Group to the
{company.STATE} field, ascending:
Crpe1.ReportName := 'C:\Company.rpt';
with Crpe1.GroupCondition do
begin
Retrieve;
Number := 1;
Field := '{company.STATE}';
Condition := AnyChange;
Direction := gcAscending;
end;
Crpe1.Execute;
GruupCunditiun Prupcrtics
GroupCondition Condition property, Page 354
GroupCondition Direction property, Page 355
GroupCondition Field property, Page 356
GroupCondition GroupType property, Page 357
GroupCondition Item property, Page 358
GroupCondition ItemIndex property, Page 358
GroupCondition Number property, Page 359
GruupCunditiun Mcthuds
GroupCondition Add method, Page 360
GroupCondition Clear method, Page 361
GroupCondition CopyFrom method, Page 361
GroupCondition Count method, Page 362
GroupCondition Create method, Page 362
GroupCondition Delete method, Page 363
GroupCondition Destroy method, Page 363
GroupCondition Retrieve method, Page 364
GroupCondition Send method, Page 365
VCI Re|etetce 41
GruupOptiuns
DccIaratiun
property GroupOptions : TCrpeGroupOptions;
Typc
TCrpeGroupOptions = class(TPersistent)
Dcscriptiun
GroupOptions contains all the properties that relate to Grouping, including TopN control.
G The Number property specifies the Group Number. Groups are numbered from 1 up, so the first Group
in a Report is 1.
G The Condition property setting determines when a new group will be formed. For Groups based on
Date and Boolean fields, there are specific values that can be assigned. For all other Groups,
"AnyChange" is the only condition that is applicable.
G The Direction property determines in what order the Groups will be sorted: gdAscending,
gdDescending, gdOriginal, gdSpecified, or gdDefault.
G The Field property contains the actual Grouping field, which can be a Database field or a Formula field.
G The GroupType property specifies the data type of the field or formula that the Group is based on:
gtOther, gtDate, or gtBoolean.
G The KeepTogether property specifies whether the Group will be split over two pages or not when it will
not all fit at the bottom of a page.
G The RepeatGH property specifies whether the Group Header will be repeated on the top of the next
page when a Group is split over two pages.
G The Retrieve method will fetch the GroupOptions values from the Report and fill the GroupOptions
object with corresponding items.
G The Count method returns the number of GroupOptions items currently contained in the
GroupOptions object.
G The Item and ItemIndex methods can be used to navigate through the GroupOptions object.
G The Clear method removes all items from the GroupOptions object.
G The Add and Delete methods provide a manual alternative to Retrieve/Clear for adding and deleting
items from the GroupOptions object.
G There are four properties that apply specifically to TopN Group selection. TopN refers to the selecting
and ordering of Groups. The sorting part is also available via the GroupSortFields object, but the
selecting part is not. This can be used to show only a specified number of Groups, i.e. the Top 5 based
on a certain summary field.
VCI Re|etetce 42
G The TopNGroups property specifies the number of Groups to select.
G The TopNSortField property specifies the summary field that the Groups will be ordered by.
G The TopNDiscardOthers property specifies whether the Groups that are out of the N range will be
discarded or whether they will be included in a Group called "Others".
G The TopNOptions property specifies how the TopN properties will be applied. The options are:
tnUnsorted, tnSorted, tnTopN, tnBottomN, and tnDefault.
NO7F: GrouOlons s new as ol Cryslal Reorls 6.0, and s lherelore nol avalable lo Cryslal S.0 users (lhey
wll have lo use GrouCondlon nslead). GrouCondlon can slll be used wlh Cryslal 6.0 l desred, bul l s
nol as owerlul as GrouOlons (l lacks lhe 7oN conlrol, elc.). Also, GrouCondlon and GrouOlons
should nol be used logelher, snce lhey bolh cover lhe same ground.
GruupOptiuns fxampIc
This sample retrieves the GroupOptions values from the Report, and sets the first Group to the
{company.STATE} field, ascending:
Crpe1.ReportName := 'C:\Company.rpt';
with Crpe1.GroupOptions do
begin
Retrieve;
Number := 1;
Field := '{company.STATE}';
Condition := AnyChange;
Direction := gcAscending;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
GruupOptiuns Prupcrtics
GroupOptions Condition property, Page 365
GroupOptions Direction property, Page 367
GroupOptions Field property, Page 368
GroupOptions GroupType property, Page 368
GroupOptions Item property, Page 369
GroupOptions ItemIndex property, Page 370
GroupOptions KeepTogether property, Page 371
GroupOptions Number property, Page 371
GroupOptions RepeatGH property, Page 372
GroupOptions TopNDiscardOthers property, Page 373
VCI Re|etetce 4!
GroupOptions TopNGroups property, Page 374
GroupOptions TopNOptions property, Page 374
GroupOptions TopNSortField property, Page 375
GruupOptiuns Mcthuds
GroupOptions Add method, Page 376
GroupOptions Clear method, Page 377
GroupOptions CopyFrom method, Page 378
GroupOptions Count method, Page 378
GroupOptions Create method, Page 379
GroupOptions Delete method, Page 379
GroupOptions Destroy method, Page 379
GroupOptions Retrieve method, Page 380
GroupOptions Send method, Page 381
GruupScIcctiun
DccIaratiun
property GroupSelection: TCrpeGroupSelectionFormula;
Typc
TCrpeGroupSelectionFormula = class(TPersistent)
Dcscriptiun
The GroupSelection object deals with the Group Selection Formula of a Report. It's main properties and
methods are:
G The Formula property holds the text of the Group Selection Formula.
G The Replace property is a Boolean property that specifies if the text in the Formula property will replace
the Group Selection that is already in the Report, or whether it will be ANDed on to the end of it.
G The Retrieve method will fetch the Group Selection Formula that is currently in the Report, and place it
in the Formula property.
G The Check method can be used to determine whether the Formula syntax is correct.
VCI Re|etetce 44
GruupScIcctiun fxampIc
This code sample passes a new Group Selection formula into the Report, replacing the one that was currently
there:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupSelection.Formula.Assign('Sum({company.SALES}, {company.STATE}) >
30000.00');
Crpe1.GroupSelection.Replace := True;
Crpe1.Execute;
Using VariabIcs with GruupScIcctiun FurmuIa
Delphi variables can be used with the GroupSelection Formula if they are declared as string or converted to
string (regardless of the actual data type) before being passed to Crystal Reports. Remember also, that string
values require extra quotes for Crystal Reports, as well as the usual single quotes that Delphi requires. The
following examples cover some of the ways in which variables can be used:
1. Passing Integer values from Edit boxes:
var
nStart : string;
nEnd : string;
begin
nStart := Edit1.Text;
nEnd := Edit2.Text;
Crpe1.GroupSelection.Formula[0] :=
'Maximum({company.SALES},{company.STATE}) >= ' + nStart +
'AND Maximum({company.SALES},{company.STATE}) <= ' + nEnd;
2. Passing Integer variables:
var
nSales : integer;
begin
nSales := 12345;
Crpe1.GroupSelection.Formula[0] :=
'Maximum({company.SALES},{company.STATE}) > ' + IntToStr(nSales);
3. Passing Date variables (Crystal Reports accepts dates only as a string data type in the
Date(YYYY,MM,DD) format):
var
dStart : string;
dEnd : string;
begin
dStart := '1998,01,31';
dEnd := '1998,06,30';
Crpe1.GroupSelection.Formula[0] :=
'Maximum({company.STARTDATE},{company.STATE}) in Date(' + dStart + ') to
Date(' + dEnd + ')';
VCI Re|etetce 4S
4. Passing Date variables divided into Day, Month, Year:
var
dYear : string;
dMonth : string;
dDay : string;
begin
dYear := '1998';
dMonth := '06';
dDay := '31';
Crpe1.GroupSelection.Formula[0] :=
'Maximum({company.STARTDATE},{company.STATE}) = Date(' + dYear + ',' + dMonth
+ ',' + dDay + ')';
5. Passing Date variables entered in Edit boxes:
var
dYear : string;
dMonth : string;
dDay : string;
dWhole : string;
begin
dYear := Edit1.Text;
dMonth := Edit2.Text;
dDay := Edit3.Text;
dWhole := 'Date(' + dYear + ',' + dMonth + ',' + dDay + ')';
Crpe1.GroupSelection.Formula[0] :=
'Maximum({company.STARTDATE},{company.STATE}) = ' + dWhole;
GruupScIcctiun Prupcrtics
GroupSelection Formula property, Page 381
GroupSelection Replace property, Page 382
GruupScIcctiun Mcthuds
GroupSelection Check method, Page 383
GroupSelection Clear method, Page 384
GroupSelection CopyFrom method, Page 385
GroupSelection Create method, Page 385
GroupSelection Destroy method, Page 386
GroupSelection Retrieve method, Page 386
GroupSelection Send method, Page 387
VCI Re|etetce 46
GruupSurtFicIds
DccIaratiun
property GroupSortFields: TCrpeGroupSortFields;
Typc
TCrpeGroupSortFields = class(TPersistent)
Dcscriptiun
The GroupSortFields object contains the properties needed to set and modify the sorting of the Groups in a
Report. The main properties are:
G The Number property contains the GroupSortField number, which is zero-based.
G The Field property contains the actual GroupSortField string. This should be a Summary field, although
it does not need to be a Summary field that already exists in the Report. Any field names used in the
Field property should be enclosed in braces: {company.STATE}.
G The Direction property specifies the sorting direction, either sdDescending, sdAscending, or sdDefault.
G The DeleteGSF property can be used to delete a GroupSortField. When a GroupSortField is set to be
deleted, and the Report is run, the deleted GroupSortField will no longer be in the Report that is
currently loaded in memory, or the Crystal component either. To reference it again, the Report will
have to be re-loaded, or the Add method will have to be used to add it back.
G The Retrieve method will fetch the GroupSortFields currently in the Report.
G The Count method will return the number of GroupSortFields items stored in the GroupSortFields
object.
G The Item and ItemIndex properties can be used to navigate through the items in the GroupSortFields
object.
Nutc un Summary ficIds
Summary fields are usually constructed in this fashion:
SummaryFunction(DatabaseField,GroupingField)
so they usually look something like this:
Sum({company.SALES},{company.STATE})
This would read: "Sum of the Company's Sales per State". The last parameter must be a field that the Report
is grouped on.
VCI Re|etetce 47
GruupSurtFicIds fxampIc
The code below shows how to change the Field value of a GroupSortField, and set the Sort Direction to
descending:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupSortFields.Retrieve;
Crpe1.GroupSortFields[2];
Crpe1.GroupSortFields.Field := 'Sum({company.SALES},{company.STATE})';
Crpe1.GroupSortFields.Direction := sdDescending;
Crpe1.Execute;
GruupSurtFicIds Prupcrtics
GroupSortFields DeleteGSF property, Page 387
GroupSortFields Direction property, Page 388
GroupSortFields Field property, Page 389
GroupSortFields Item property, Page 389
GroupSortFields ItemIndex property, Page 390
GroupSortFields Number property, Page 391
GruupSurtFicIds Mcthuds
GroupSortFields Add method, Page 391
GroupSortFields Clear method, Page 393
GroupSortFields CopyFrom method, Page 394
GroupSortFields Count method, Page 394
GroupSortFields Create method, Page 395
GroupSortFields Delete method, Page 395
GroupSortFields Destroy method, Page 396
GroupSortFields Retrieve method, Page 396
GroupSortFields Send method, Page 397
HasSavcdData
Dcscriptiun
The HasSavedData property is a read-only property that queries the Report loaded to determine if it has Saved
Data or not.
When a Report is saved in the Crystal Designer with Saved Data turned on, the data it was last run with is
saved with the Report, and unless it is discarded, the Report will by default run with the Saved Data instead
of reading the Database. This is sometimes desirable, such as when a Report is being distributed to users who
do not have access to the Database but would like to preview and print the Reports anyway.
VCI Re|etetce 48
In most other cases, the Saved Data should be discarded so that the data is refreshed with new values from the
database. The HasSavedData property can be used in conjunction with the DiscardSavedData property to
accomplish this.
fxampIc
In the following example, if the report has saved data, it will be discarded:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.DiscardSavedData := Crpe1.HasSavedData;
Crpe1.Output := toWindow;
Crpe1.Execute;
ls|ubFinishcd
DccIaratiun
property IsJobFinished: boolean;
Dcscriptiun
IsJobFinished is a run-time, read-only property that monitors the Print Job to see if it is finished or still in
progress. You can use this function any time you have a call that is contingent on a Print Job being finished. It
would normally be checked after the Execute method has been called.
If the Output is set to go toWindow, IsJobFinished will return True immediately after the Report has been
displayed in the Preview Window, even if that Preview Window has not been closed yet. To check for window
close, use the OnWindowClose event, or the ReportWindowHandle method.
fxampIc
The following code example shows how to use the IsJobFinished property to determine if a Print Job is finished
processing:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toPrinter;
Crpe1.Execute;
while not Crpe1.IsJobFinished do
Application.ProcessMessages;
Crpe1.CloseJob;
VCI Re|etetce 40
|ubNumbcr
DccIaratiun
property JobNumber: Word;
Dcscriptiun
The JobNumber property is a run-time, read-only property that returns the number assigned by the Crystal
Reports Print Engine to the current Report Print Job.
Each time a Report (or a Subreport) is opened, the Print Engine assigns it a specific number which is used when
passing values back to the Print Engine. This number is handled internally in the Crystal component and does
not normally need to be accessed by the user.
Because the JobNumber is now a public property, it is possible to use this number to make calls directly to the
Crystal Reports Print Engine DLL, just as the component does internally. However, since the component now
offers practically all the functionality of the Print Engine DLL calls, with much less work, it is usually not
necessary to do so. Also, care must be taken not to make changes via direct calls to the Print Engine that might
confuse the VCL, such as closing the PrintJob.
See OnJobOpened event, Page 173 for more information.
fxampIc
In this example, the current Print Job number will be shown:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.OpenJob;
ShowMessage(IntToStr(Crpe1.JobNumber));
lastfrrurNumbcr
DccIaratiun
property LastErrorNumber: integer;
Dcscriptiun
The LastErrorNumber property is a run-time only property which holds the number of the last error that
occurred after calling the Execute method. There are two types of errors that can occur in the Crystal
component:
1. Errors that occur in the Print Engine - these have Error Number values of 500 or greater.
2. Errors that occur in the Crystal component - these have Error Number values of 100 to 400.
VCI Re|etetce S6
When a Print Engine error occurs, the component raises an Error exception, which would normally display a
dialog box box with the Error Number and Error String displayed. By using the OnError event, this exception
can be by-passed or a custom dialog box can be used instead. If the exception is by-passed, the internal
procedure that the error occurred in will either be exited, or if it is a loop, will proceed to the next iteration.
See OnError for more details.
LastErrrorString can also be used to obtain the text string of the Error message.
fxampIc
This example shows how to display the LastErrorNumber and LastErrorString. Normally these would be
handled by the internal Error exception:
Crpe1.ReportName := 'MyReport.rpt'
Crpe1.Execute;
if Crpe1.LastErrorNumber > 0 then
ShowMessage('Error ' + IntToStr(Crpe1.LastErrorNumber) +
': ' + Crpe1.LastErrorString);
end;
lastfrrurString
DccIaratiun
property LastErrorString: string;
Dcscriptiun
The LastErrorString property is a run-time only property which holds the text message of the last error that
occurred after calling the Execute method. There are two types of errors in the Crystal component:
1. Errors that occur in the Print Engine - these have Error Number values of 500 or greater.
2. Errors that occur in the Crystal component - these have Error Number values of 100 to 400.
When a Print Engine error occurs, the component raises an Error exception, which would normally display a
Dialog box with the Error Number and Error String displayed. By using the OnError event, this exception can
be by-passed, or a custom dialog box can be used instead. If the exception is by-passed, the internal procedure
that the error occurred in will either be exited, or if it is a loop, will proceed to the next iteration. See OnError
for more details.
LastErrrorNumber can also be used to obtain the Error Number of the Error.
VCI Re|etetce S1
fxampIc
This example shows how to display the LastErrorNumber and LastErrorString. Normally these would be
handled by the internal Error exception:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Execute;
if Crpe1.LastErrorNumber > 0 then
ShowMessage('Error ' + IntToStr(Crpe1.LastErrorNumber) +
': ' + Crpe1.LastErrorString);
end;
luadfngincOnUsc
DccIaratiun
property LoadEngineOnUse: boolean;
Dcscriptiun
The LoadEngineOnUse property determines if the Crystal Reports Print Engine DLL (CRPE32.DLL) is loaded
into memory when the component is created.
G If LoadEngineOnUse is set to True, the DLL will not be loaded until it is actually needed by the
component (such as when retrieving values from a Report, or when running the Report). This is useful
in applications where the user may not be using the Reports section of the application, and therefore
does not need the DLL loaded.
G If LoadEngineOnUse is set to False, the DLL is loaded into memory at the time that the component is
created.
NO7F: 7he DII can also be unloaded by callng lhe CloseFngne melhod, or by Deslroyng lhe comonenl,
allhough lhs wll also close any Reorls lhal are currenlly oen.
fxampIc
In this example, the CRPE32.DLL will not load until Execute is called:
Crpe1.LoadEngineOnUse := True;
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce S2
lugOnlnfu
DccIaratiun
property LogOnInfo: TCrpeLogOnInfo;
Typc
TCrpeLogOnInfo = class(TPersistent)
Dcscriptiun
The LogOnInfo object is used to set the LogOn information for each table in the Report. It applies to Reports
based on SQL tables or ODBC datasources, as does the Connect property, and LogOnServer.
The difference between LogOnInfo and Connect is that LogOnInfo allows different LogOn parameters for
each table, whereas Connect takes one set of parameters and applies them to all the tables in a Report.
Therefore, if a Report is designed with tables from more than one Server, LogOnInfo should be used instead
of Connect.
LogOnInfo contains the basic Server information properties:
ServerName
UserID
Password
DatabaseName
As well, it contains read-only properties that display information about the Table Type and Crystal Database
DLL used to access the Table:
TableType
DescriptiveName
DLLName
These properties will only have meaningful values if the Retrieve method is used to get the LogOn information
from the Report. Otherwise, if the manual Add method is used, these values will contain empty strings.
G The PromptForLogOn property can be used to bring up a dialog box prompting for LogOn information.
G The Table property contains the Table number as defined in the Report. This number represents the
order in which the Tables were added to the Report, and can be viewed by opening the Report in the
Crystal Reports Designer and going to the "Database | Set Location..." menu item. The Tables appear in
a list, and are numbered internally from top to bottom.
G If the Retrieve method has been used, the Count method will yield the number of SQL tables in the
Report, and is useful for looping constructs.
G The Test method provides a useful means of testing the Table connectivity after the desired parameters
have been changed. This will reveal if the LogOn information is correct or not.
NO7F: Imorlanl! In order lo use lhe IogOnInlo roerles, lhe Cre1.ConneclMelhod roerly musl be sel lo use
IogOnInlo. 7hs sellng lells lhe VCIs Fxeculemelhod whch class lo use lor conneclng: Connecl or IogOnInlo.
VCI Re|etetce S!
lugOnlnfu fxampIc
This example shows how to use the LogOnInfo object to supply a new UserID and Password for the SQL tables
in a Report. It is assumed that the ServerName and DatabaseName will remain the same as they were when
the Report was designed. Notice that the code tests each table to see if the LogOn information works:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.LogOnInfo.Retrieve;
for cnt := 0 to (Crpe1.LogOnInfo.Count - 1) do
begin
Crpe1.LogOnInfo[cnt];
Crpe1.LogOnInfo.UserID := 'Maxwell Smart';
Crpe1.LogOnInfo.Password := 'Agent86';
if Crpe1.LogOnInfo.Test then
ShowMessage('LogOn information is good')
else
ShowMessage('LogOn information is not good');
end;
lugOnlnfu Prupcrtics
LogOnInfo DatabaseName property, Page 398
LogOnInfo DescriptiveName property, Page 398
LogOnInfo DLLName property, Page 399
LogOnInfo Item property, Page 400
LogOnInfo ItemIndex property, Page 401
LogOnInfo Password property, Page 401
LogOnInfo ServerName property, Page 402
LogOnInfo Table property, Page 403
LogOnInfo TableType property, Page 404
LogOnInfo UserID property, Page 405
lugOnlnfu Mcthuds
LogOnInfo Add method, Page 405
LogOnInfo Clear method, Page 407
LogOnInfo CopyFrom method, Page 407
LogOnInfo Count method, Page 408
LogOnInfo Create method, Page 408
LogOnInfo Delete method, Page 409
VCI Re|etetce S4
LogOnInfo Destroy method, Page 410
LogOnInfo PromptForLogOn property, Page 410
LogOnInfo Retrieve method, Page 411
LogOnInfo Send method, Page 412
LogOnInfo Test method, Page 413
lugOnScrvcr
DccIaratiun
property LogOnServer: TCrpeLogOnServer;
Typc
TCrpeLogOnServer = class(TPersistent)
Dcscriptiun
The LogOnServer object is a run-time only object that contains properties that allow for Logging onto a Server.
The difference between this object and the Connect and LogOnInfo objects is that the latter work on a table by
table basis, setting the LogOn information for each table in a Report, whereas LogOnServer just opens a
connection to a SQL Server and if the Report has that Server specified in it, it will use the connection.
The advantage to LogOnServer is that it is simple, and only needs to be opened once for any Reports (and
Subreports) that use that particular Server, whereas the Connect and LogOnInfo properties need to be
specified on a report by report basis. The disadvantage is that it will not change the Server name that is
specified in a Report, therefore it is not possible to use LogOnServer if the Server name is going to be different
than when the Report was created.
The LogOn parameters for LogOnServer are similar to the other two objects:
ServerName
UserID
Password
DatabaseName
DLLName
DLLName specifies the name of the Seagate Crystal Reports DLL for the server or password-protected non-
SQL table you want to log on to, for example, 'PDSODBC.DLL'. DLL names have the following naming
convention: PDS*.DLL for SQL/ODBC databases.
G The Retrieve method will create an item in the LogOnServer object for each unique ServerName it finds
in the Report (including any Subreports), and fill all the properties of each item except for Password.
G The LogOn and LogOff methods create and terminate the actual connection.
VCI Re|etetce SS
G The Number property stores the connection number created by a successful LogOn.
G The IndexOf method can be used to locate a specific LogOnServer item by it's connection Number.
NO7F: IogOll wll nol normally be successlul unless lhe Reorl lhal uses lhe conneclon s lrsl closed, by
elher changng lhe ReorlName, or usng lhe comonenls Close)ob melhod.
lugOnScrvcr fxampIc
This example shows how to create a LogOnServer item manually, and fill the properties with values. Finally,
the LogOn method is called:
with Crpe1.LogOnServer do
begin
Add; {Create a LogOnServer item}
DLLName := 'PDSORA7.DLL'; {Crystal's Native Oracle Driver}
ServerName := 'oracleserver';
UserID := 'SCOTT';
Password := 'tiger';
DatabaseName := ''; {Not usually req'd for Oracle}
if LogOn then
ShowMessage('The LogOn ID is: ' + IntToStr(Number))
else
ShowMessage('Error Logging on to Server');
end;
This example shows how to create a LogOnServer item by retrieving the LogOn information from the Report.
This should only be done if the ServerName that the Report was created with is going to remain the same, since
LogOnServer cannot be used to change ServerName:
Crpe1.LogOnServer.Retrieve; {Retrieve LogOnServer info from Report}
if Crpe1.LogOnServer.Count > 0 then
begin
Crpe1.LogOnServer[1];
Crpe1.LogOnServer.Password := 'tiger';
if not Crpe1.LogOnServer.LogOn then
ShowMessage('Error Logging on to Server');
end;
This example shows how to log off a Server that has been Logged On using the LogOnServer property. First
the PrintJob must be closed, or the LogOff will fail. Then the LogOnServer object must be set to the item that
was used to LogOn (the IndexOf method can be used to search LogOnServer for a particular LogOn ID).
Finally an attempt is made to LogOff:
Crpe1.CloseJob;
Crpe1.LogOnServer[0];
if Crpe1.LogOnServer.LogOff then
ShowMessage('LogOff Server successful')
else
ShowMessage('LogOff Server failed');
VCI Re|etetce S6
lugOnScrvcr Prupcrtics
LogOnServer DatabaseName property, Page 413
LogOnServer DLLName property, Page 414
LogOnServer Item property, Page 415
LogOnServer ItemIndex property, Page 417
LogOnServer Number property, Page 417
LogOnServer Password property, Page 418
LogOnServer ServerName property, Page 419
LogOnServer UserID property, Page 419
lugOnScrvcr Mcthuds
LogOnServer Add method, Page 420
LogOnServer Clear method, Page 421
LogOnServer CopyFrom method, Page 421
LogOnServer Count method, Page 422
LogOnServer Create method, Page 422
LogOnServer Delete method, Page 423
LogOnServer Destroy method, Page 423
LogOnServer IndexOf method, Page 424
LogOnServer LogOff method, Page 424
LogOnServer LogOn method, Page 425
LogOnServer Retrieve method, Page 426
Margins
DccIaratiun
property Margins: TCrpeMargins;
Typc
TCrpeMargins = class(TPersistent)
VCI Re|etetce S7
Dcscriptiun
The Margins object contains the four properties: Top, Left, Right, and Bottom. These control the page margins
of the Report.
G The Retrieve method can be used to get the current margins from the Report.
G Margin values are defined in Twips (1440 twips = 1 inch).
The main four properties can be assigned any of the following values:
-1 : Use the current Margin value contained in the Report.
-2, 32768 : Use a default Margin value based on the current Printer.
0 to 32767 : Defines a new Margin value.
Margins fxampIc
The code below obtains the Margins from a Report and makes sure they are set to use Printer defaults:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Margins.Retrieve;
if Crpe1.Margins.Left <> 32768 then
Crpe1.Margins.Left := 32768;
if Crpe1.Margins.Top <> 32768 then
Crpe1.Margins.Top := 32768;
if Crpe1.Margins.Right <> 32768 then
Crpe1.Margins.Right := 32768;
if Crpe1.Margins.Bottom <> 32768 then
Crpe1.Margins.Bottom := 32768;
Crpe1.Execute;
Margins Prupcrtics
Margins Bottom property, Page 426
Margins Left property, Page 427
Margins Right property, Page 428
Margins Top property, Page 428
Margins Mcthuds
Margins Clear method, Page 429
Margins CopyFrom method, Page 430
Margins Create method, Page 430
Margins Retrieve method, Page 430
Margins Send method, Page 431
VCI Re|etetce S8
Output
DccIaratiun
property Output: TCrOutput;
Typc
TCrOutput = (toWindow, toPrinter, toExport);
Dcscriptiun
The Output property determines the destination of the Report when the Execute method is called. The three
possible values are:
tuWinduw
The following properties can be used to set the various Window options: WindowButtonBar, WindowSize,
WindowState, WindowStyle, WindowZoom, and WindowEvents.
tuPrintcr
The following properties can be used to set the various Printer options: Printer, PrintOptions, and
ProgressDialog.
tufxpurt
The following properties can be used to set the various Printer options: Export, and ProgressDialog. The
Destination property of the Export object determines whether the Report will go to disk File, or to Email, or to
Exchange Folder. The Export FileType property will determine the file format of the resulting exported Report.
Output fxampIc
In this example, the Output property is set toWindow. When the Execute method is called, the Report will
appear in a Preview Window:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
toWindow Sends the Report to a Preview Window (this is the default).
toPrinter Sends the Report to the Printer.
toExport Sends the Report to an Exported File, or to Email, or to an Exchange Folder.
VCI Re|etetce S0
Pagcs
DccIaratiun
property Pages: TCrpePages;
Typc
TCrpePages = class(TPersistent)
Dcscriptiun
The Pages property is run-time only, and allows the programmer to control paging of the Crystal Preview
Window, as well as determining what pages were printed when going to Printer. The Pages properties only
work after the Preview Window is open. These four properties simulate the use of the paging buttons on the
Crystal Button Bar:

G The GoToPage property can be used to navigate the Report to a specific page number.
G The default array property, Item, can also be used to go to a specific page, i.e. Pages[2] will cause the
Report to go to the second page.
G The ItemIndex property can also be used to do the same thing, or can be read to determine which page
the Report is currently displaying (which is the same as the GetDisplayed method).
There are three other properties: GetDisplayed, GetLatest, and GetStart, which retrieve paging values from the
Report.
G GetDisplayed returns the number of the current page.
G GetLatest returns the number of the last page that has been previewed thus far.
G GetStart returns the number of the first page that was displayed.
When going to Preview Window, GetStart will always return 1, but when going to Printer, if the StartPage of the
PrintOptions object has been set to something higher than 1, then GetStart will return a number higher than 1.
First Go to First page of Report.
Next Go to Next page of Report.
Previous Go to Previous page of Report.
Last Go to Last page of Report.
VCI Re|etetce 66
Tip
When using the Paging properties (Next, Previous, etc.) together with GetDisplayed, be sure to allow time for
the Page to finish drawing before checking GetDisplayed:
var
PageNum : Word;
begin
Crpe1.Pages.Previous;
{Loop until page is finished drawing}
while Crpe1.Status <> 3 do
Application.ProcessMessages;
PageNum := Crpe1.Pages.GetDisplayed;
end;
Pagcs fxampIc
This code sample was written to respond to the click of a NextPage button. Notice how we determine if the
Report is on the last page:
var
pg1, pg2 : integer;
begin
{Get the Displayed page number}
pg1 := Crpe1.Pages.GetDisplayed;
{Show the next page}
Crpe1.Pages.Next;
{Loop until page is drawn}
while Crpe1.Status <> 3 do
Application.ProcessMessages;
{Get the Displayed page number}
pg2 := Crpe1.Pages.GetDisplayed;
{if Page number stayed the same, it is the Last Page}
if pg2 = pg1 then
Label1.Caption := 'Last Page';
end;
Pagcs Prupcrtics
Pages Item property, Page 432
Pages ItemIndex property, Page 432
Pagcs Mcthuds
Pages Count method, Page 433
Pages First method, Page 433
Pages GetDisplayed method, Page 434
VCI Re|etetce 61
Pages GetLatest method, Page 434
Pages GetStart method, Page 435
Pages GoToPage method, Page 435
Pages Last method, Page 436
Pages Next method, Page 436
Pages Previous method, Page 437
ParamFicIds
DccIaratiun
property ParamFields: TCrpeParamFields;
Typc
TCrpeParamFields = class(TPersistent)
Dcscriptiun
The ParamFields object contains all the properties that apply to Parameter Fields. For Seagate Crystal Reports
7, ParamFields have been greatly expanded. The new features are documented at the bottom of this
description, in the section New Features for SCR 7, Page 62.
G The Name property specifies the actual Parameter name, as defined in the Report, and acts as a lookup
field.
G The default array property Item, and the ItemIndex property can be used to navigate through the
various ParamField items (assuming there is more than one Parameter in the Report).
G The Value property holds the actual parameter value that is to be passed to the Parameter Field. Values
are passed as strings, but are converted within the VCL to the correct Parameter Type required for the
particular Parameter field. There are six other properties that can be used to read and write the Value
property using native Delphi types:
AsNumber
AsCurrency
AsBoolean
AsDate
AsDateTime //SCR 7.0 and higher
AsTime //SCR 7.0 and higher
G If the Retrieve method is used to get Parameter Field information from the Report, the ParamType
property will show what type each Parameter is.
G The Prompt property specifies the prompting text that appears on the Crystal Reports Parameter
prompt dialog.
VCI Re|etetce 62
G The ShowDialog property specifies whether the Value passed in will bypass the Parameter prompt
dialog, or whether it will show up as the new default value in the Parameter prompt dialog.
G The ReportName property is read-only and specifies which Report the Parameter belongs to.
Parameters are handled slightly differently than other Report properties. When the ParamFields are
retrieved for the main Report, the resulting list contains all of the Parameter Fields in the Report,
including those in Subreports. This is because when the main Report is run, the prompt dialog contains
all of the Parameters (main & sub), and so they are considered as being partly "owned" by the main
Report. Therefore, ReportName indicates which Subreport the Parameter belongs to.
G The NeedsCurrentValue property is a read-only and specifies whether the Parameter actually requires a
value or not. If the Parameter is linked to a Subreport, or is not used in the Report, then
NeedsCurrentValue will be False.
Here are some examples which show how to pass each Parameter type:
NO7F: When runnng a reorl, always relreve and sel lhe ParamFelds lrom lhe man Reorl. 7he only lme l
s necessary lo relreve ParamFelds lor a Subreorl seclcally, s when lhal Subreorl s gong lo be run as a
searale reorl, aarl lrom lhe man Reorl (see Subreports, Page 112 lor more nlormalon on runnng a
Subreorl).
Ncw Fcaturcs fur SCR 7
For Seagate Crystal Reports 7, the following main features have been added to the ParamFields class:
1. Stored Procedure Parameters are now handled through the ParamFields class instead of the SQL.Params
class, as with the previous Crystal versions and the last VCL release. For this purpose, there is now a
ParamSource property which specifies the source of the Parameter, whether it is a Crystal Reports
Parameter Field, a Stored Procedure Parameter, or a Crystal Query Parameter.
2. ParamField prompts can now have a drop-down list of values, multiple values, a range of values,
multiple ranges of values:
G The DefaultValues property is a TCrpeString (descendant of TStringList) which contains the multiple
values that are to be presented in the Crystal Reports Parameter Field prompt dialog. If ShowDialog is
set to true, the DefaultValues data takes precedence over the data contained in the Value property (i.e.
DefaultValues[0] will over-ride Value if they are different).
Param7ye Value As[7ye] Delh 7ye
pfNumber '235' AsNumber := 235 double
pfCurrency '2.35' AsCurrency := 2.35 currency
pfBoolean 'True' AsBoolean := True boolean
pfDate '1999,01,30' AsDate := EncodeDate(1999,01,30) TDateTime
pfString 'Vancouver' Value := 'Vancouver' string
pfDateTime '1999,01,30 1:12:14' AsDateTime := StrToDateTime('01/30/99 1:12:14') TDateTime
pfTime '1:12:14' AsTime := EncodeTime(1,12,14,0) TDateTime
VCI Re|etetce 6!
G The CurrentValues property is a TCrpeString (descendant of TStringList) which contains the multiple
values that were entered in the Crystal Reports Parameter Field prompt dialog. This list will initially be
blank unless the Report has been run already once (and then Retrieve is called after running the
Report), or if the Report has Saved Data (see DiscardSavedData for more information). If ShowDialog
is set to true, CurrentValues will not be used. If ShowDialog is set to False, and Info.ValueType is
vtDiscrete, CurrentValues data will take precedence over the data contained in the Value property (i.e.
CurrentValues[0] will over-ride Value if they are different).
G A Ranges sub-class has been added under the ParamFields class. This sub-class contains the properties
that apply to Range Parameters (parameters that can take beginning and ending range values). This
object only comes into play if you are passing range values direct to the Report, bypassing Crystal's
Parameter prompt dialog, or if you wish to view the Range values that were either saved with the
Report (if the Report has Saved Data), or that were entered when the Report was just run. In order to
use Ranges, ShowDialog must be set to False, and Info.ValueType must be set to vtRanges. In this case,
the Ranges data will take precedence over the data contained in the Value property.
3. An EditMask can be specified to control the formatting of values that are entered into the Crystal Report
Parameter Field dialog box for a particular Parameter.
4. Limits can be set to the length or size of the value that can be entered into the Crystal Reports Parameter
Field dialog box for a particular Parameter. This is handled by three properties: ValueLimit, ValueMax, and
ValueMin. ValueLimit determines if the Limit feature is enabled or not. ValueMax and ValueMin determine
the upper and lower limits. If the Parameter is a string, the limits apply to the length of the string. If the
Parameter is any other type, the limits apply to the maximum and minimum values that can be entered.
Limits and EditMask are mutually exclusive. If you define an EditMask, Limits will be ignored.
5. A Parameter Fields Info sub-class has been added under the ParamFields class. This sub-class contains
various properties that specify whether the Parameter can be edited, whether it can have null values (for
Stored Procedure Parameters), whether it can contain multiple values, whether it is a Range Parameter,
and whether it belongs to a group (and if so, which group number).
ParamFicIds fxampIc
The following code fills a ListBox with all the ParamField Names for the current Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
for cnt := 0 to (Crpe1.ParamFields.Count - 1) do
ListBox1.Items.Add(Crpe1.ParamFields[cnt].Name);
This example illustrates the Value and AsDate, etc. properties to set Parameter Field values:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].Value := 'CA';
Crpe1.ParamFields[1].AsDate := Now;
Crpe1.ParamFields[2].AsNumber := 3;
Crpe1.ParamFields[3].AsBoolean := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 64
This example sets 3 default values for the first ParamField that will appear in the drop-down list when the
Crystal Parameter prompt dialog appears. The user will only be able to choose from these values; they cannot
enter new ones (AllowEditing is false):
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].DefaultValues.Clear;
Crpe1.ParamFields[0].DefaultValues[0] := 'AK';
Crpe1.ParamFields[0].DefaultValues[1] := 'CA';
Crpe1.ParamFields[0].DefaultValues[2] := 'WA';
Crpe1.ParamFields[0].ShowDialog := True;
Crpe1.ParamFields[0].Info.AllowEditing := False;
Crpe1.Output := toWindow;
Crpe1.Execute;
This example sets 2 Range values for the first ParamField. These will be passed directly into the report,
bypassing the Crystal Parameter prompt dialog:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].Info.ValueType := vtRanges;
Crpe1.ParamFields[0].ShowDialog := False;
Crpe1.ParamFields[0].Ranges.Clear;
Crpe1.ParamFields[0].Ranges.Add(0);
Crpe1.ParamFields[0].Ranges[0].RangeStart := 'Atkinson';
Crpe1.ParamFields[0].Ranges[0].RangeEnd := 'Jones';
Crpe1.ParamFields[0].Ranges[0].RangeBounds := IncludeStartAndEnd;
Crpe1.ParamFields[0].Ranges.Add(1);
Crpe1.ParamFields[0].Ranges[1].RangeStart := 'Smith';
Crpe1.ParamFields[0].Ranges[1].RangeEnd := 'Wilson';
Crpe1.ParamFields[0].Ranges[1].RangeBounds := IncludeStartAndEnd;
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds Prupcrtics
ParamFields AsBoolean property, Page 437
ParamFields AsCurrency property, Page 438
ParamFields AsDate property, Page 438
ParamFields AsDateTime property, Page 439
ParamFields AsNumber property, Page 439
ParamFields AsTime property, Page 440
ParamFields CurrentValue property, Page 440
ParamFields CurrentValues property, Page 441
ParamFields DefaultValue property, Page 442
ParamFields DefaultValues property, Page 443
VCI Re|etetce 6S
ParamFields EditMask property, Page 445
ParamFields Info property, Page 446
G Properties
G ParamFields Info AllowEditing property, Page 447
G ParamFields Info AllowMultipleValues property, Page 448
G ParamFields Info AllowNull property, Page 448
G ParamFields Info GroupNum property, Page 449
G ParamFields Info MutuallyExclusiveGroup property, Page 450
G ParamFields Info PartOfGroup property, Page 450
G ParamFields Info ValueType property, Page 451
G Methods
G ParamFields Info Clear method, Page 452
G ParamFields Info CopyFrom method, Page 453
G ParamFields Info Create method, Page 454
G ParamFields Info Retrieve method, Page 454
G ParamFields Info Send method, Page 455
ParamFields Item property, Page 455
ParamFields ItemIndex property, Page 456
ParamFields Name property, Page 456
ParamFields NeedsCurrentValue property, Page 457
ParamFields ParamSource property, Page 458
ParamFields ParamType property, Page 459
ParamFields Prompt property, Page 460
ParamFields Ranges property, Page 460
G Properties
G ParamFields Ranges Item property, Page 462
G ParamFields Ranges ItemIndex property, Page 462
G ParamFields Ranges Number property, Page 463
G ParamFields Ranges RangeBounds property, Page 464
G ParamFields Ranges RangeEnd property, Page 464
G ParamFields Ranges RangeStart property, Page 465
VCI Re|etetce 66
G Methods
G ParamFields Ranges Add method, Page 466
G ParamFields Ranges Clear method, Page 467
G ParamFields Ranges CopyFrom method, Page 467
G ParamFields Ranges Count method, Page 468
G ParamFields Ranges Create method, Page 468
G ParamFields Ranges Delete method, Page 469
G ParamFields Ranges Destroy method, Page 469
G ParamFields Ranges Retrieve method, Page 470
G ParamFields Ranges Send method, Page 470
ParamFields ReportName property, Page 471
ParamFields ShowDialog property, Page 472
ParamFields Value property, Page 472
ParamFields ValueLimit property, Page 474
ParamFields ValueMax property, Page 475
ParamFields ValueMin property, Page 476
ParamFicIds Mcthuds
ParamFields Add method, Page 477
ParamFields Clear method, Page 478
ParamFields CopyFrom method, Page 479
ParamFields Count method, Page 479
ParamFields Create method, Page 480
ParamFields Delete method, Page 480
ParamFields Destroy method, Page 480
ParamFields IndexOf method, Page 481
ParamFields Retrieve method, Page 482
ParamFields Send method, Page 483
VCI Re|etetce 67
PrintDatc
DccIaratiun
property PrintDate: TCrpePrintDate;
Typc
TCrpePrintDate = class(TPersistent)
Dcscriptiun
The PrintDate object contains the three properties that make up the print date: Year, Month, and Day.
G These properties can be used to set the Print Date of the report to something other than the current date,
so as to generate reports that appear to have been run a month ago, etc.
G The Retrieve method can be used to get the current PrintDate from the report.
PrintDatc fxampIc
The following sample sets the PrintDate to January 1, 1999:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.PrintDate.Day := 1;
Crpe1.PrintDate.Month := 1;
Crpe1.PrintDate.Year := 1999;
Crpe1.Execute;
PrintDatc Prupcrtics
PrintDate Day property, Page 484
PrintDate Month property, Page 484
PrintDate Year property, Page 485
PrintDatc Mcthuds
PrintDate Clear method, Page 485
PrintDate CopyFrom method, Page 486
PrintDate Retrieve method, Page 486
PrintDate Send method, Page 487
VCI Re|etetce 68
Printfndcd
DccIaratiun
property PrintEnded: Boolean;
Dcscriptiun
PrintEnded is a run-time, read-only property that indicates when the Print Job is finished processing. The value
of this property is True when the Engine is done running the report. When Output is set to go toWindow, this
property will not return True until you have gone to the last page of the Report (use Status instead in this case).
NO7F: You can also use lhe OnPrnlFnded evenl lo lhe same ellecl.
fxampIc
This example sends the Report to the Printer. It will not allow the program to close the current Form until the
printing is finished.
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toPrinter;
Crpe1.Execute;
while not Crpe1.PrintEnded do
Application.ProcessMessages;
Close;
Printcr
DccIaratiun
property Printer: TCrpePrinter;
Typc
TCrpePrinter = class(TPersistent)
Dcscriptiun
The Printer object contains all of the properties that relate to setting the Printer to be used for printing the
Report.
G The Name property takes the name of the Printer that is to be selected for the Report.
G The Driver property takes the Printer Driver associated with that printer.
VCI Re|etetce 60
G The Port property takes the Printer Port associated with that printer.
G The Mode property takes the Handle to the DevMode pointer for that printer.
G The PMode property (which is a pointer to the DevMode, rather than a handle) gives direct access to the
DevMode structure, which can be used to manipulate other printer-related settings. See DevMode
Structure, Page 70, for more info on the members of the DevMode structure. Mode and PMode are both
updated if either one is changed.
G The Retrieve method can be used to get the Printer and its settings from the Report and automatically
fill the Name, Driver, Port, and Mode properties with the values.
Traditionally we required all four of those properties to have values before the Printer could be changed. This
is no longer necessary. The only property that actually needs to be set now is the Name property, which can
be set directly:
Crpe1.Printer.Name := 'HP Laserjet 4';
or from the Printers object in Delphi:
Crpe1.Printer.Name := Printer.Printers[2];
Alternatively, the GetCurrent method can be called to retrieve the currently selected printer. If GetCurrent is
used after the PrintDialog is called, it will pick up the selected Printer and automatically fill the Name, Driver,
Port, Mode, and PMode properties.
G The Orientation property controls the orientation of the Report, and can be set to orDefault, orPortrait,
or orLandscape.
G The PreserveRptSettings set contains three properties that can be used to make sure certain settings are
preserved from the Report when the Printer is changed: prOrientation, prPaperSize, prPaperSource
(bin). If you desire the Orientation to be preserved as it was when the Report was designed, include the
prOrientation value as part of the PreserveRptSettings set. Likewise with the other two set properties.
G The ShowDialog property replaces the previous UserPrinterSetup property. If ShowDialog is true, a
PrintDialog is displayed when the Send method is called. This normally happens within the
component's Execute method; it is not normally necessary to call the Send method in code.
G Another way of invoking the PrintDialog at any time (not only when Send or Execute is called), is to use
the ShowPrintDlg method.
G The Clear method can be used to clear the string properties of the Printer object and to set the other
properties to default.
Printcr fxampIc
The following code example illustrates how to use some of the Printer object properties:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toPrinter;
with Crpe1.Printer do
VCI Re|etetce 76
begin
{Set Name to 3rd Printer in Printers list}
Name := Printer.Printers[2];
{Set Orientation to Landscape}
Orientation := orLandscape;
{Preserve PaperSize as set in Report}
PreserveRptSettings := [prPaperSize];
{Do not show the PrintDialog on Execute}
ShowDialog := False;
end;
Crpe1.Execute;
DcvMudc Structurc
The following information describes the 32-bit DevMode structure for Delphi. Note that dmDefaultSource
cannot be changed via the DevMode structure for WindowsNT 4.0. Different Windows API calls are required,
for which we do not have a sample at this time.
Typc
PDeviceMode = PDeviceModeA;
dmDeviceName: array[0..CCHDEVICENAME - 1] of AnsiChar;
dmSpecVersion: Word;
dmDriverVersion: Word;
dmSize: Word;
dmDriverExtra: Word;
dmFields: DWORD;
dmOrientation: SHORT;
dmPaperSize: SHORT;
dmPaperLength: SHORT;
dmPaperWidth: SHORT;
dmScale: SHORT;
dmCopies: SHORT;
dmDefaultSource: SHORT;
dmPrintQuality: SHORT;
dmColor: SHORT;
dmDuplex: SHORT;
dmYResolution: SHORT;
dmTTOption: SHORT;
dmCollate: SHORT;
dmFormName: array[0..CCHFORMNAME - 1] of AnsiChar;
dmLogPixels: Word;
dmBitsPerPel: DWORD;
dmPelsWidth: DWORD;
dmPelsHeight: DWORD;
dmDisplayFlags: DWORD;
VCI Re|etetce 71
dmDisplayFrequency: DWORD;
dmICMMethod: DWORD;
dmICMIntent: DWORD;
dmMediaType: DWORD;
dmDitherType: DWORD;
dmReserved1: DWORD;
dmReserved2: DWORD;
end;
dmDcviccNamc
Specifies the name of the device the driver supports: for example, "PCL/HP LaserJet" in the case of the
Hewlett-Packard LaserJet. Each driver has a unique string.
dmSpccVcrsiun
Specifies the version number of the DEVMODE structure. For Windows version 3.1, this value should be 0x30A.
dmDrivcrVcrsiun
Specifies the printer driver version number assigned by the printer driver developer.
dmSizc
Specifies the size, in bytes, of the DEVMODE structure. (This value does not include the optional
dmDriverData member for device-specific data, which can follow the structure.) If an application manipulates
only the driver-independent portion of the data, it can use this member to find out the length of the structure
without having to account for different versions.
dmDrivcrfxtra
Specifies the size, in bytes, of the optional dmDriverData member for device-specific data, which can follow
the structure. If an application does not use device-specific information, it should set this member to zero.
dmFicIds
Specifies a set of flags that indicate which of the remaining members in the DEVMODE structure have been
initialized. It can be any combination (or it can be none) of the following values:
Conslanl Value
DM_ORIENTATION 1
DM_PAPERSIZE 2
DM_PAPERLENGTH 4
DM_PAPERWIDTH 8
DM_SCALE $10
DM_COPIES $100
DM_DEFAULTSOURCE $200
DM_PRINTQUALITY $400
VCI Re|etetce 72
NO7F: A rnler drver suorls only lhose members lhal are arorale lor lhe rnler lechnology.
dmOricntatiun
Specifies the orientation of the paper. It can be either of the following:
dmPapcrSizc
Specifies the size of the paper to print on. This member may be set to zero if the length and width of the paper
are specified by the dmPaperLength and dmPaperWidth members, respectively. Otherwise, the dmPaperSize
member can be set to one of the following predefined values:
DM_COLOR $800
DM_DUPLEX $1000
DM_YRESOLUTION $2000
DM_TTOPTION $4000
DM_COLLATE $8000
DM_FORMNAME $10000
DM_LOGPIXELS $20000
DM_BITSPERPEL $40000
DM_PELSWIDTH $80000
DM_PELSHEIGHT $100000
DM_DISPLAYFLAGS $200000
DM_DISPLAYFREQUENCY $400000
DM_RESERVED1 $800000
DM_RESERVED2 $1000000
DM_ICMMETHOD $2000000
DM_ICMINTENT $4000000
DM_MEDIATYPE $8000000
DM_DITHERTYPE $10000000
Conslanl Value
DMORIENT_PORTRAIT 1
DMORIENT_LANDSCAPE 2
Conslanl Value Descrlon
DMPAPER_LETTER 1 {Letter 8 12 x 11 in}
DMPAPER_FIRST DMPAPER_LETTER
DMPAPER_LETTERSMALL 2 {Letter Small 8 12 x 11 in}
Conslanl Value
VCI Re|etetce 7!
DMPAPER_TABLOID 3 {Tabloid 11 x 17 in}
DMPAPER_LEDGER 4 {Ledger 17 x 11 in
DMPAPER_LEGAL 5 {Legal 8 12 x 14 in}
DMPAPER_STATEMENT 6 {Statement 5 12 x 8 12 in}
DMPAPER_EXECUTIVE 7 {Executive 7 14 x 10 12 in}
DMPAPER_A3 8 {A3 297 x 420 mm
DMPAPER_A4 9 {A4 210 x 297 mm
DMPAPER_A4SMALL 10 {A4 Small 210 x 297 mm}
DMPAPER_A5 11 {A5 148 x 210 mm}
DMPAPER_B4 12 {B4 (JIS) 250 x 354}
DMPAPER_B5 13 {B5 (JIS) 182 x 257 mm}
DMPAPER_FOLIO 14 {Folio 8 12 x 13 in}
DMPAPER_QUARTO 15 {Quarto 215 x 275 mm}
DMPAPER_10X14 16 {10x14 in}
DMPAPER_11X17 17 {11x17 in}
DMPAPER_NOTE 18 {Note 8 12 x 11 in}
DMPAPER_ENV_9 19 {Envelope #9 3 78 x 8 78}
DMPAPER_ENV_10 20 {Envelope #10 4 18 x 9 12}
DMPAPER_ENV_11 21 {Envelope #11 4 12 x 10 38}
DMPAPER_ENV_12 22 {Envelope #12 4 \276 x 11}
DMPAPER_ENV_14 23 {Envelope #14 5 x 11 12}
DMPAPER_CSHEET 24 {C size sheet}
DMPAPER_DSHEET 25 {D size sheet}
DMPAPER_ESHEET 26 {E size sheet}
DMPAPER_ENV_DL 27 {Envelope DL 110 x 220mm}
DMPAPER_ENV_C5 28 {Envelope C5 162 x 229 mm}
DMPAPER_ENV_C3 29 {Envelope C3 324 x 458 mm}
DMPAPER_ENV_C4 30 {Envelope C4 229 x 324 mm}
DMPAPER_ENV_C6 31 {Envelope C6 114 x 162 mm}
DMPAPER_ENV_C65 32 {Envelope C65 114 x 229 mm}
DMPAPER_ENV_B4 33 {Envelope B4 250 x 353 mm}
DMPAPER_ENV_B5 34 {Envelope B5 176 x 250 mm}
DMPAPER_ENV_B6 35 {Envelope B6 176 x 125 mm}
DMPAPER_ENV_ITALY 36 {Envelope 110 x 230 mm}
Conslanl Value Descrlon
VCI Re|etetce 74
DMPAPER_ENV_MONARCH 37 {Envelope Monarch 3.875 x 7.5 in}
DMPAPER_ENV_PERSONAL 38 {6 34 Envelope 3 58 x 6 12 in}
DMPAPER_FANFOLD_US 39 {S Std Fanfold 14 78 x 11 in}
DMPAPER_FANFOLD_STD_GERMAN 40 {German Std Fanfold 8 12 x 12 in}
DMPAPER_FANFOLD_LGL_GERMAN 41 {German Legal Fanfold 8 12 x 13 in}
DMPAPER_ISO_B4 42 {B4 (ISO) 250 x 353 mm}
DMPAPER_JAPANESE_POSTCARD 43 {Japanese Postcard 100 x 148 mm}
DMPAPER_9X11 44 {9 x 11 in}
DMPAPER_10X11 45 {10 x 11 in}
DMPAPER_15X11 46 {15 x 11 in}
DMPAPER_ENV_INVITE 47 {Envelope Invite 220 x 220 mm}
DMPAPER_RESERVED_48 48 {RESERVED--DO NOT USE}
DMPAPER_RESERVED_49 49 {RESERVED--DO NOT USE}
DMPAPER_LETTER_EXTRA 50 {Letter Extra 9 \275 x 12 in}
DMPAPER_LEGAL_EXTRA 51 {Legal Extra 9 \275 x 15 in}
DMPAPER_TABLOID_EXTRA 52 {Tabloid Extra 11.69 x 18 in}
DMPAPER_A4_EXTRA 53 {A4 Extra 9.27 x 12.69 in}
DMPAPER_LETTER_TRANSVERSE 54 {Letter Transverse 8 \275 x 11 in}
DMPAPER_A4_TRANSVERSE 55 {A4 Transverse 210 x 297 mm}
DMPAPER_LETTER_EXTRA_TRANSVERSE 56 {Letter Extra Transverse 9\275x12 in}
DMPAPER_A_PLUS 57 {SuperASuperAA4 227 x 356 mm}
DMPAPER_B_PLUS 58 {SuperBSuperBA3 305 x 487 mm}
DMPAPER_LETTER_PLUS 59 {Letter Plus 8.5 x 12.69 in}
DMPAPER_A4_PLUS 60 {A4 Plus 210 x 330 mm}
DMPAPER_A5_TRANSVERSE 61 {A5 Transverse 148 x 210 mm}
DMPAPER_B5_TRANSVERSE 62 {B5 (JIS) Transverse 182 x 257 mm}
DMPAPER_A3_EXTRA 63 {A3 Extra 322 x 445 mm}
DMPAPER_A5_EXTRA $40 {A5 Extra 174 x 235 mm}
DMPAPER_B5_EXTRA 65 {B5 (ISO) Extra 201 x 276 mm}
DMPAPER_A2 66 {A2 420 x 594 mm}
DMPAPER_A3_TRANSVERSE 67 {A3 Transverse 297 x 420 mm}
DMPAPER_A3_EXTRA_TRANSVERSE 68 {A3 Extra Transverse 322 x 445 mm}
DMPAPER_LAST DMPAPER_A3_EXTRA_TRANSVERSE
DMPAPER_USER $100
Conslanl Value Descrlon
VCI Re|etetce 7S
dmOricntatiun
Specifies the orientation of the paper. It can be either of the following: DMORIENT_PORTRAIT (1) or
DMORIENT_LANDSCAPE (2).
dmPapcrlcngth
Specifies a paper length in tenths of a millimeter. This parameter overrides the paper length specified by the
dmPaperSize member either for custom paper sizes or for such devices as dot-matrix printers that can print
on a variety of page sizes.
dmPapcrWidth
Specifies a paper width in tenths of a millimeter. This parameter overrides the paper width specified by the
dmPaperSize member.
dmScaIc
Specifies the factor by which the printed output is to be scaled. The apparent page size is scaled from the
physical page size by a factor of dmScale/100. For example, a letter-size paper with a dmScale value of 50
would contain as much data as a page of size 17 by 22 inches, because the output text and graphics would be
half their original height and width.
dmCupics
Specifies the number of copies printed if the device supports multiple-page copies.
dmDcfauItSuurcc
Specifies the default bin from which the paper is fed. The application can override this value by using the
GETSETPAPERBINS escape. This member can be one of the following values:
Conslanl Value
DMBIN_UPPER 1
DMBIN_FIRST DMBIN_UPPER
DMBIN_ONLYONE 1
DMBIN_LOWER 2
DMBIN_MIDDLE 3
DMBIN_MANUAL 4
DMBIN_ENVELOPE 5
DMBIN_ENVMANUAL 6
DMBIN_AUTO 7
DMBIN_TRACTOR 8
DMBIN_SMALLFMT 9
DMBIN_LARGEFMT 10
VCI Re|etetce 76
NO7F: A range ol values s reserved lor devce-seclc bns. 7o be consslenl wlh nlalzalon nlormalon,
lhe GF7SF7PAPFRBINS and FNUMPAPFRBINS escaes use lhese values.
dmPrintQuaIity
Specifies the printer resolution. Following are the four predefined device-independent values:
NO7F: Il a oslve value s gven, l secles lhe number ol dols er nch (DPI) and s lherelore devce-
deendenl.
NO7F: Il lhe rnler nlalzes lhe dmYResolulon member, lhe dmPrnlQually member secles lhe x-
resolulon ol lhe rnler n dols er nch.
dmCuIur
Specifies whether a color printer is to render color or monochrome output. Possible values are:
dmDupIcx
Specifies duplex (double-sided) printing for printers capable of duplex printing. This member can be one of
the following values:
DMBIN_LARGECAPACITY 11
DMBIN_CASSETTE 14
DMBIN_FORMSOURCE 15
DMBIN_LAST DMBIN_FORMSOURCE
DMBIN_USER $100 {device specific bins start here}
Conslanl Value
DMRES_DRAFT (-1)
DMRES_LOW (-2)
DMRES_MEDIUM (-3)
DMRES_HIGH (-4)
Conslanl Value
DMCOLOR_MONOCHROME 1
DMCOLOR_COLOR 2
Conslanl Value
DMDUP_SIMPLEX (1)
DMDUP_VERTICAL (2)
DMDUP_HORIZONTAL (3)
Conslanl Value
VCI Re|etetce 77
dmYRcsuIutiun
Specifies the y-resolution of the printer, in dots per inch. If the printer initializes this member, the
dmPrintQuality member specifies the x-resolution of the printer, in dots per inch.
dmTTOptiun
Specifies how TrueType fonts should be printed. It can be one of the following values:
dmCuIIatc
Specifies whether collation should be used when printing multiple copies. (This member is ignored unless the
printer driver indicates support for collation by setting the dmFields member to DM_COLLATE.) This
member can be one of the following values:
NO7F: Usng DMCOIIA7F_7RUF rovdes lasler, more ellcenl oulul lor collalon, snce lhe dala s senl lo
lhe devce drver jusl once, no maller how many coes are requred. 7he rnler s lold lo smly rnl lhe
age agan.
dmFurmNamc
Windows NT: Specifies the name of the form to use; for example, "Letter" or "Legal". A complete set of names
can be retrieved by using the EnumForms function. Windows 95: Printer drivers do not use this member.
dmlugPixcIs
Specifies the number of pixels per logical inch.
dmBitsPcrPcI
Windows NT: Specifies the color resolution, in bits per pixel, of the display device (for example: 4 bits for 16
colors, 8 bits for 256colors, or 16 bits for 65536 colors). Windows 95: Display drivers use this member, for
example, in the ChangeDisplaySettings function. Printer drivers do not use this member.
dmPcIsWidth
Windows NT: Specifies the width, in pixels, of the visible device surface. Windows 95: Display drivers use this
member, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.
Conslanl Value Descrlon
DMTT_BITMAP 1 {print TT fonts as graphics}
DMTT_DOWNLOAD 2 {download TT fonts as soft fonts}
DMTT_SUBDEV 3 {substitute device fonts for TT fonts}
DMTT_DOWNLOAD_OUTLINE 4 {download TT fonts as outline soft fonts}
Conslanl Value
DMCOLLATE_FALSE 0
DMCOLLATE_TRUE 1
VCI Re|etetce 78
dmPcIsHcight
Windows NT: Specifies the height, in pixels, of the visible device surface. Windows 95: Display drivers use this
member, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.
dmDispIayFIags
Windows NT: Specifies the device's display mode. This member can be one of the following values:
l
dmDispIayFrcqucncy
Windows NT: Specifies the frequency, in hertz (cycles per second), of the display device in a particular mode.
Windows 95: Display drivers use this member, for example, in the ChangeDisplaySettings function. Printer
drivers do not use this member.
dmlCMMcthud
Windows 95: Specifies how ICM is handled. For a non-ICM application, this member determines if ICM is
enabled or disabled. For ICM applications, Windows examines this member to determine how to handle ICM
support. This member can be one of the following predefined values, or a driver-defined value greater than
the value of DMICMMETHOD_USER:Windows NT: This member is not supported on Windows NT.
Conslanl Value Descrlon
DM_GRAYSCALE 1 Specifies that the display is a NON-color device. If this flag is not set,
color is assumed.
DM_INTERLACED 2 Specifies that the display mode is interlaced. If the flag is not set,
NON-interlaced is assumed. Windows 95: Display drivers use this
member, for example, in the ChangeDisplaySettings function. Printer
drivers do not use this member.
Conslanl Value Descrlon
DMICMMETHOD_NONE 1 Windows 95 only: Specifies that ICM is disabled.
DMICMMETHOD_SYSTEM 2 Windows 95 only: Specifies that ICM is handled by Windows.
DMICMMETHOD_DRIVER 3 Windows 95 only: Specifies that ICM is handled by the device
driver.
DMICMMETHOD_DEVICE 4 Windows 95 only: Specifies that ICM is handled by the
destination device. The printer driver must provide a user
interface for setting this member. Most printer drivers
support only the DMICMMETHOD_SYSTEM or
DMICMMETHOD_NONE value. Drivers for PostScript
printers support all values.
DMICMMETHOD_USER $100 Device-specific methods start here
VCI Re|etetce 70
dmlCMlntcnt
Windows 95: Specifies which of the three possible color matching methods, or intents, should be used by
default. This member is primarily for non-ICM applications. ICM applications can establish intents by using
the ICM functions. This member can be one of the following predefined values, or a driver defined value
greater than the value of DMICM_USER:Windows NT: This member is not supported on Windows NT.
dmMcdiaTypc
Windows 95: Specifies the type of media being printed on. The member can be one of the following predefined
values, or a driver-defined value greater than the value of DMMEDIA_USER:Windows NT: This member is
not supported on Windows NT.
dmDithcrTypc
Windows 95: Specifies how dithering is to be done. The member can be one of the following predefined values,
or a driver-defined value greater than the value of DMDITHER_USER: Windows NT: This member is not
supported on Windows NT.
DMICM_SATURATE 1 {Maximize color saturation}
DMICM_CONTRAST 2 {Maximize color contrast}
DMICM_COLORMETRIC 3 {Use specific color metric}
DMICM_USER $100 {Device-specific intents start here}
Conslanl Value Descrlon
DMMEDIA_STANDARD 1 Standard paper
DMMEDIA_TRANSPARENCY 2 Transparency
DMMEDIA_GLOSSY 3 Glossy paper
Conslanl Value Descrlon
DMDITHER_NONE 1 No dithering
DMDITHER_COARSE 2 Dither with a coarse brush
DMDITHER_FINE 3 Dither with a fine brush
DMDITHER_LINEART 4 LineArt dithering
DMDITHER_ERRORDIFFUSION 5 LineArt dithering
DMDITHER_RESERVED6 6 LineArt dithering
DMDITHER_RESERVED7 7 LineArt dithering
DMDITHER_RESERVED8 8 LineArt dithering
DMDITHER_RESERVED9 9 LineArt dithering
DMDITHER_GRAYSCALE 10 Device does gray-scaling
DMDITHER_USER 256 Device-specific dithers start here
VCI Re|etetce 86
dmRcscrvcd1
Windows 95: Not used; must be zero.Windows NT: This member is not supported on Windows NT.
dmRcscrvcd2
Windows 95: Not used; must be zero.Windows NT: This member is not supported on Windows NT.
Rcmarks
A device driver's private data follows the public portion of the DEVMODE structure. The size of the public
data can vary for different versions of the structure. The dmSize member specifies the number of bytes of
public data, and the dmDriverExtra member specifies the number of bytes of private data.
Sctting Purt tu Fllf
A request we get quite often is that developers would like to set the Port to something other than what is
specified in the Printer driver. The most common use of this is to set the output to FILE. This used to work
with earlier Crystal versions, but in 5.x.x.108 and 6.0 of the Print Engine this no longer works. The reason for
the change is that the previous method was not reliable. This issue has been addressed in Seagate Crystal
Reports 7, by the addition of an OutputFileName property to the PrintOptions object.
For users of Crystal 5.0 and 6.0, the only work-around is to create another Printer Driver in Windows that is
set to go to the desired Port, and then switch to that Driver when a different Port setting is desired. This
however raises another question. When a Report is printed to FILE, a prompt dialog box appears requesting
the user to enter the destination Filename. This is not always convenient, especially in cases where Reports
must be run in batches, and possibly overnight when there is no one around to enter the destination Filenames.
This problem can be worked around by using Windows API calls to obtain the handle to the prompting dialog
box and then using that handle to pass the Filename in via code. Here is an example of how this could be done
in Delphi:
{SendFilename is called after "Print To File" dialog appears}
procedure SendFilename;
var
aFile: array[0..255] of char;
hDlg : Hwnd;
begin
{Get the "Print To File" Dialog handle}
hDlg := FindWindow(nil, 'Print To File');
{If it was found...}
if hDlg > 0 then
begin
{Copy the new Filename to the buffer}
StrCopy(aFile, 'C:\Reports\Report1.prn');
{Send the Text to the Edit field of the Dialog}
SendDlgItemMessage(hDlg, 1152, WM_SETTEXT, 0, LongInt(@aFile));
{Show the Dialog: If this isn't done, WM_LBUTTONDOWN needs to be sent
twice}
SendMessage(hDlg, WM_SHOWWINDOW,0,0);
{Send a Button Down to the OK button of the Dialog}
VCI Re|etetce 81
SendDlgItemMessage(hDlg,1,WM_LBUTTONDOWN,0,0);
{Send a Button Up to the OK button of the Dialog}
SendDlgItemMessage(hDlg,1,WM_LBUTTONUP,0,0);
end;
end;
NO7F: 7he above code was lesled on Wndows9S and s ollered as a ossble work-around. Il s nol guaranleed
lo work on all lallorms and wll robably need lo be modled lor WndowsN7. Il lhe Prnl7oFle dalog box
dllers lhe edl leld ID number lor lhe llename wll also robably be dllerenl. Donl alleml lhs unless you
have a reasonable knowledge ol Wndows API calls, or avod lhe roblem by ugradng lo Cryslal Reorls 7.
Printcr Prupcrtics
Printer Driver property, Page 488
Printer Mode property, Page 490
Printer Name Property, Page 491
Printer Orientation Property, Page 494
Printer PMode Property, Page 494
Printer Port Property, Page 495
Printer PreserveRptSettings property, Page 498
Printer ShowDialog property, Page 500
Printcr Mcthuds
Printer Clear Method, Page 501
Printer CopyFrom Method, Page 502
Printer Create Method, Page 502
Printer GetCurrent Method, Page 503
Printer Retrieve Method, Page 504
Printer Send Method, Page 504
Printer ShowPrintDlg Method, Page 505
PrintOptiuns
DccIaratiun
property PrintOptions: TCrpePrintOptions;
Typc
TCrpePrintOptions = class(TPersistent)
VCI Re|etetce 82
Dcscriptiun
The PrintOptions object, along with the Printer object, contains the properties that apply when setting the
Output property to go to Printer:
G The Collation property refers to the printing of multiple copies of a Report and to whether they will
print out as page 1,2,3, etc. or they will print out as 1,1,2,2,3,3, etc.
G The Copies property specifies the number of copies of the Report.
G The StartPage property specifies the first page that will be printed.
G The StopPage property specifies the last page that will be printed.
G The OutputFileName property specifies a filename that the Report will be printed to (optional).
G The Retrieve method can be used to get the current Report values for these properties.
G The Clear method can be used to set them back to default.
G The PromptForOptions property can be used to bring up a prompt dialog box to allow the user to select
the values for the PrintOptions properties.
PrintOptiuns fxampIc
This code example changes the PrintOption properties to print out two copies of pages 2 & 3 from the Report,
collated:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toPrinter;
with Crpe1.PrintOptions do
begin
Collation := Collated;
Copies := 2;
StartPage := 2;
StopPage := 3;
end;
Crpe1.Execute;
PrintOptiuns Prupcrtics
PrintOptions Collation property, Page 506
PrintOptions Copies property, Page 507
PrintOptions OutputFileName property, Page 508
PrintOptions PromptForOptions property, Page 508
PrintOptions StartPage property, Page 510
PrintOptions StopPage property, Page 510
VCI Re|etetce 8!
PrintOptiuns Mcthuds
PrintOptions Clear method, Page 511
PrintOptions CopyFrom method, Page 512
PrintOptions Create method, Page 512
PrintOptions Retrieve method, Page 512
PrintOptions Send method, Page 513
PrugrcssDiaIug
DccIaratiun
property ProgressDialog: boolean;
Dcscriptiun
The ProgressDialog property determines if the Crystal Reports Print Engine internal Progress dialog box is
displayed when a Report is run to Printer or to Export. The Progress Dialog does not apply to Reports being
run to Preview Window. The default setting for this property is True. The Progress dialog box looks like this:
fxampIc
This example sets the ProgressDialog to True. The dialog box will appear when the Report is being printed:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ProgressDialog := True;
Crpe1.Output := toPrinter;
Crpe1.Execute;
VCI Re|etetce 84
Crcating a Uscr-Dcfincd Prugrcss DiaIug
The ProgressDialog can be replaced with a User-Defined dialog by setting ProgressDialog property to False
and creating a dialog that displays the values of the Records object after the Report has been started (Execute
was called).
Step 1 : Create a Dialog form with a TTimer component and 3 labels.
Step 2 : In the OnCreate Event, enable the TTimer.
procedure TForm1.FormCreate(Sender: TObject);
begin
Timer1.Enabled := True;
end;
Step 3 : In the OnShow Event, SetFocus to the Form (or ShowModal, or set FormStyle to AlwaysOnTop).
procedure TForm1.FormShow(Sender: TObject);
begin
Form1.SetFocus;
end;
Step 4 : In the Timer's OnTimer Event, update the display.
procedure TfrmParentWindow.Timer1Timer(Sender: TObject);
var
temp1,temp2,temp3: string;
begin
{Update Status Display}
Str(frmMain.Crpe1.Records.Printed, temp1);
Str(frmMain.Crpe1.Records.Read, temp2);
Str(frmMain.Crpe1.Records.Selected, temp3);
labelRecordsPrinted.Caption := temp1 + ' ';
labelRecordsRead.Caption := temp2 + ' ';
labelRecordsSelected.Caption := temp3 + ' ';
end;
Rccurds
DccIaratiun
property Records: TCrpeRecords;
Typc
TCrpeRecords = class(TPersistent)
VCI Re|etetce 8S
Dcscriptiun
The Records object contains 3 methods that can be used after the Execute method to determine how many
records have been Read, how many have been Selected, and how many have been Printed.
These properties are usually used to build a custom dialog or display which counts the Records as the Report
is being processed.
Rccurds Mcthuds
Records Printed method, Page 514
Records Read method, Page 514
Records Selected method, Page 515
RcpurtNamc
DccIaratiun
property ReportName: TCrFileName;
Typc
TCrFileName = string[TCRPE_FILENAME_LEN];
Cunstant
TCRPE_FILENAME_LEN = 255
Dcscriptiun
The ReportName property determines which Report is currently loaded.
G ReportName should be the first property set in code, since it causes most of the others to be cleared.
G Changing the ReportName will cause any currently open Report to be cleared from the VCL and closed
in the Crystal Reports Print Engine.
G After a new name has been assigned to ReportName, any previous Report that may still be displayed in
a Preview Window will still be active in the Window until the Window is closed. However, it can not
be accessed via VCL code.
VCI Re|etetce 86
NO7F: A change n ReorlName wll normally cause lhe VCI roerles alyng lo lhal Reorl lo be cleared.
Bul l lhe same Reorl wll be loaded lwce n a row, lhere wll nol be a recognzable change n ReorlName.
Under lhese crcumslances, l l s desred lhal lhe currenl Prnl )ob wlh ls aramelers be cleared, lwo
dllerenl melhods can be used lo close lhe currenl Prnl )ob:
1. Sel ReorlName lo a blank slrng belween Reorls:
Crpe1.ReportName := '';
2. Use lhe Close)ob melhod:
Crpe1.CloseJob;
Spccifying Rcpurt Dircctury at Runtimc
There are a number of ways of specifying the directory that the Reports will be located in at runtime, which
could change depending on the installation directory chosen by the user. If the Reports will be located in the
Application directory, this code will obtain the path:
var
RptDir: string;
begin
RptDir := ExtractFilePath(Application.ExeName);
Crpe1.ReportName := RptDir + 'Company.rpt';
end;
Another way of getting around the problem is to set up a BDE Alias to the Reports directory. Then the
GetPathFromAlias method can be used to obtain the Report path:
var
RptDir: string;
begin
RptDir := Crpe1.GetPathFromAlias(':RPTAlias:');
Crpe1.ReportName := RptDir + 'Company.rpt';
end;
fxampIc
In this example, the ReportName property is directly assigned a new Report name complete with path:
Crpe1.ReportName := 'C:\Reports\MyNewReport.rpt';
In this example, an OpenDialog is executed and the ReportName property is assigned the value of the file
chosen from the dialog:
if OpenDialog1.Execute then
Crpe1.ReportName := OpenDialog1.FileName;
VCI Re|etetce 87
RcpurtOptiuns
DccIaratiun
property ReportOptions : TCrpeReportOptions;
Typc
TCrpeReportOptions = class(TPersistent)
Dcscriptiun
Only available with SCR 7.0 and higher. ReportOptions contains all the properties that reside in the "File |
Report Options" dialog in Seagate Crystal Reports Designer. These are options which are specific to a
particular Report. The ReportOptions object allows you to retrieve, modify, and send back the properties that
belong to this class.
G The CaseInsensitiveSQLData property specifies whether or not the SQL field names used in the Report
will be treated with case-sensitivity or not.
G The ConvertDateTimeType property specifies how DateTime fields will be treated in a Report: as
DateTime values, as DateTime String values, or just as Date (no Time).
G The ConvertNullFieldToDefault property specifies how Null field values will be treated in a Report: as they
are (null), or as a default value (empty string for string fields, zero for numeric fields, etc.). If Null fields are
not converted to default, extra care must be taken in Formulas and Selection Formulas to test for Null
values, otherwise a null value can cause a formula to stop processing as soon as the null is encountered.
G The CreateGroupTree property determines if the GroupTree panel on the Preview Window will be
available or not.
G The PrintEngineErrorMessages property determines if the Print Engine will put up it's own error
dialogs, on top of the VCL's error handling. The built-in Print Engine error messages are often more
descriptive than the standard error messages returned by the Print Engine to an application. It may be
desirable to turn this option on when doing development, but it normally should be turned off when
the application is finally deployed.
G The SaveDataWithReport property determines if a Report will save the actual data used from the
database with the Report when the Report is saved. Since saving is not possible at runtime, this
property is not particularly useful at this time. It is possible to export a Report to RPT format, but the
exported RPT will have Saved Data by default anyway.
G The SaveSummariesWithReport property determines if the data calculated from summary fields in the
Report is stored in the RPT file when the Report is saved. Since saving is not possible at run-time, this
property is not particularly useful at this time. It is possible to export a Report to RPT format, but the
exported RPT will have Saved Data by default anyway.
G The TranslateDOSMemos property determines how dBase memo fields with upper ASCII characters are
handled, whether they are translated to corresponding ANSI character values or not.
VCI Re|etetce 88
G The TranslateDOSStrings property determines how dBase string fields with upper ASCII characters are
handled, whether they are translated to corresponding ANSI character values, or not.
G The UseIndexForSpeed property specifies if an index or a SQL Server will be used to speed up processing
of a Record Selection. Usually it is desirable to leave this option on, but it can cause problems with dBase
indexes that use expressions or functions (which are not supported by Crystal's xBase driver).
G The VerifyOnEveryPrint property determines whether the database structure will be re-read every time
the Report runs. It is useful to have this option turned on during development, where database field-
types or lengths may change frequently. If the database structure is fixed, and will not change, this
option can be turned off for slightly faster processing of the Report.
G The ZoomMode property determines which zoom level the Report will first appear in within the
Preview Window.
G The PerformGroupingOnServer property specifies whether the grouping of data for a Report will take
place on the Server or not. This option only applies to Reports based off an SQL or ODBC datasource.
G The NoDataForHiddenObjects property determines whether data will be saved for parts of the Report
that are in hidden sections.
G The CopyFrom method can be used to store the ReportOptions settings to a temporary ReportOptions
object.
G The Retrieve method is used to retrieve the ReportOptions settings from a Report.
G The Clear method can be used to set all the ReportOptions properties back to their default settings.
RcpurtOptiuns fxampIc
This example sets the ReportOptions ZoomMode setting so that the Report will appear in the specified zoom
when the Preview window appears:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ReportOptions.ZoomMode := pwWholePage;
Crpe1.Output := toWindow;
Crpe1.Execute;
RcpurtOptiuns Prupcrtics
ReportOptions CaseInsensitiveSQLData property, Page 515
ReportOptions ConvertDateTimeType property, Page 516
ReportOptions ConvertNullFieldToDefault property, Page 516
ReportOptions CreateGroupTree property, Page 517
ReportOptions NoDataForHiddenObjects property, Page 517
ReportOptions PerformGroupingOnServer property, Page 518
ReportOptions PrintEngineErrorMessages property, Page 519
VCI Re|etetce 80
ReportOptions SaveDataWithReport property, Page 519
ReportOptions SaveSummariesWithReport property, Page 520
ReportOptions TranslateDOSMemos property, Page 521
ReportOptions TranslateDOSStrings property, Page 522
ReportOptions UseIndexForSpeed property, Page 522
ReportOptions VerifyOnEveryPrint property, Page 523
ReportOptions ZoomMode property, Page 523
RcpurtOptiuns Mcthuds
ReportOptions Clear method, Page 524
ReportOptions CopyFrom method, Page 525
ReportOptions Create method, Page 526
ReportOptions Retrieve method, Page 526
ReportOptions Send method, Page 527
RcpurtTitIc
DccIaratiun
property ReportTitle: string;
Dcscriptiun
The ReportTitle is an internal name by which the Report is named. In Seagate Crystal Reports designer, the
ReportTitle is one of the Special Fields in the Crystal Reports Designer, which can be inserted into a Report
and displayed. For the main Report, this value can also be changed in the SummaryInfo Title property.
Take care when changing the ReportTitle for Subreports, since the ReportTitle is also used in two other objects:
1. The Subreports object has a Name property which corresponds to the same value as ReportTitle, in the
Crystal Reports Print Engine.
2. The ParamFields object has a ReportName property which also corresponds to the same value as
ReportTitle.
Therefore, it is recommended that if a Subreport ReportTitle is changed, be sure to re-load the Report before
attempting to run it twice in a row.
One interesting feature of this property is that Subreports can be renamed, which cannot be done within the
Crystal Designer. If the ReportTitle for a Subreport is changed, and then the Subreport is exported to
CrystalReportsRPT format, the exported Report will have the Subreport names changed to match the values
passed in the ReportTitle property.
VCI Re|etetce 06
fxampIc
The code below shows how to change the ReportTitle property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ReportTitle := 'Summary Report';
Crpe1.Output := toWindow;
Crpe1.Execute;
ScctiunFunt
DccIaratiun
property SectionFont: TCrpeSectionFont;
Typc
TCrpeSectionFont = class(TPersistent)
Dcscriptiun
The SectionFont object contains the properties that can be used to change the Font used in a Report section.
Font styles can not be changed on a field by field basis, but only for a complete section at a time, although you
can specify whether the changes should affect database fields, text fields, or both.
The Section naming format has been adopted from the Crystal Reports "short" section naming convention, so
RHa means ReportHeader "a", GH3b means GroupHeader 3b, etc. See About Section Names, Volume 1, Chapter
7, for more information.
G The Retrieve method can be used to fill the SectionFont object with the Report sections. It is not actually
possible to retrieve Font information, so the Retrieve method simply gathers the Section names, and
sets the other SectionFont properties to default.
G The Count method yields the number of SectionFont items contained in the SectionFont object.
G The default array property, Item, or the ItemIndex property can be used to navigate through the
sections (as well as the Section property).
G The Font name can be set using the Name property, which is a property of the Delphi type: TFontName.
G The size of the Font is controlled by the Size property.
G The three attributes Italic, StrikeThrough, and Underlined can be set through those properties.
G Bold is controlled by the Weight property.
G The Pitch property determines if the Font spacing is fixed or variable.
G The CharSet property determines which character set is used for the upper ASCII characters.
VCI Re|etetce 01
G The Family property specifies the Font family.
G The Scope property specifies whether the Font changes are to affect database fields, or text fields, or both.
G The SectionAsCode property offers the ability to treat the Section name as a Section Code Number,
which can be useful for doing mathematical expressions to filter out certain sections.
G The SectionType method returns just the first characters of the Section name, so for GH1 (Group Header
1), the SectionType would be GH (Group Header).
ScctiunFunt fxampIc
The code below retrieves the SectionFont settings from the Report, then loops through looking for the Details
"a" section and sets various options for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFont.Retrieve;
for cnt := 0 to (Crpe1.SectionFont.Count - 1) do
begin
{Look for Details area}
if Crpe1.SectionFont[cnt].Section = 'Da' then
begin
Crpe1.SectionFont[cnt].Name := 'Times New Roman';
Crpe1.SectionFont[cnt].Size := 10;
Crpe1.SectionFont[cnt].Pitch := fpDefault;
Crpe1.SectionFont[cnt].Scope := Both;
Crpe1.SectionFont[cnt].CharSet := fcDefault;
Crpe1.SectionFont[cnt].Family := ffDefault;
Crpe1.SectionFont[cnt].Italic := cTrue;
Crpe1.SectionFont[cnt].StrikeThrough := cFalse;
Crpe1.SectionFont[cnt].Underlined := cFalse;
Crpe1.SectionFont[cnt].Weight := fwBold;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
The following sample retrieves the SectionFont sections from the Report, and then changes the Text fields in
the Group Header to Times New Roman font, 12 point size:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.SectionFont.Retrieve;
Crpe1.SectionFont.Section := 'GH1';
Crpe1.SectionFont.Name := 'Times New Roman';
Crpe1.SectionFont.Size := 12;
Crpe1.SectionFont.Scope := Text;
Crpe1.Execute;
VCI Re|etetce 02
ScctiunFunt Prupcrtics
SectionFont CharSet property, Page 527
SectionFont Family property, Page 528
SectionFont Italic property, Page 529
SectionFont Item property, Page 530
SectionFont ItemIndex property, Page 531
SectionFont Name property, Page 531
SectionFont Pitch property, Page 532
SectionFont Scope property, Page 533
SectionFont Section property, Page 534
SectionFont SectionAsCode property, Page 535
SectionFont Size property, Page 536
SectionFont StrikeThrough property, Page 537
SectionFont Underlined property, Page 538
SectionFont Weight property, Page 539
ScctiunFunt Mcthuds
SectionFont Add method, Page 540
SectionFont Clear method, Page 541
SectionFont CopyFrom method, Page 541
SectionFont Count method, Page 542
SectionFont Create method, Page 542
SectionFont Delete method, Page 543
SectionFont Destroy method, Page 543
SectionFont Retrieve method, Page 543
SectionFont SectionType method, Page 544
SectionFont Send method, Page 545
VCI Re|etetce 0!
ScctiunFurmat
DccIaratiun
property SectionFormat: TCrpeSectionFormat;
Typc
TCrpeSectionFormat = class(TPersistent)
Dcscriptiun
SectionFormat controls how the sections of a Report behave. It is similar to AreaFormat, except that
AreaFormat applies to all of the sections of the same type, whereas SectionFormat works on every sub-section
individually. Since Crystal Reports 5.0, each section of a Report can be split into sub-sections, for example,
Details a, Details b, etc. SectionFormat can be used to control each sub-section.
The Section naming format has been adopted from the Crystal Reports "short" section naming convention, so
RHa means ReportHeader a, GH3b means GroupHeader 3b, etc. See About Section Names, Volume 1, Chapter 7,
for more information.
G If the Retrieve method is used to get the Section information from the Report, the SectionFormat object
will be automatically populated with valid Section names, which appear in the Section property.
G If the manual Add method is used instead, the programmer will have to specify which section to add to
the object.
G The Count, Item, and ItemIndex properties can be used to navigate through the different Section items
in the SectionFormat object.
G The BackgroundColor property can be used to change the color of a Section. It is a Delphi TColor type,
and so the Delphi color constants can be used, or the Color value from the ColorDialog.
G The FreeFormPlacement property determines whether the fields in a section are snapped to grid or not.
G The Suppress property will cause a Section to be hidden so that it is not processed. Drill-down is not
possible on a suppressed Section (to Hide a Section so that drill-down is still available, use the
AreaFormat property, Hide).
G The KeepTogether property will prevent a Section from splitting on a page break. This is not the same as
Keep Group Together, which is available via the GroupOptions property, KeepTogether.
G The NewPageAfter and NewPageBefore properties determine if a page break will happen after or
before a particular Section.
G The PrintAtBottomOfPage property will cause the Section to appear at the bottom of the page.
G The ResetPageNAfter property will cause the Page Number to be reset after a particular Section.
G The SuppressBlankSection property will cause a Section that has no data to be suppressed. If any of the
fields in the Section have spaces in them, the Section will not be considered blank.
VCI Re|etetce 04
G The UnderlaySection property will cause the Section to be displayed under the next Section, like
layering two transparencies on top of each other.
G The SectionAsCode property offers the ability to treat the Section name as a Section Code Number,
which can be useful for doing mathematical expressions to filter out certain sections.
G The SectionType method returns just the first characters of the Section name, so for GH1 (Group Header
1), the SectionType would be GH (Group Header).
limitatiuns
Main Report - For Page Header (PH) and Page Footer (PF) sections, the following options do not apply (setting
them will have no effect on the Report):
KeepTogether
NewPageAfter
NewPageBefore
PrintAtBottomOfPage
Subreports - For Report Header b (RHb) and Report Footer b (RFb) sections, the following options do not
apply (setting them will have no effect on the Report):
KeepTogether
NewPageAfter
NewPageBefore
PrintAtBottomOfPage
ScctiunFurmat fxampIc
The code below retrieves the SectionFormat settings from the Report, then loops through looking for the
Details "a" section, and sets various options for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormat.Retrieve;
for cnt := 0 to (Crpe1.SectionFormat.Count - 1) do
begin
{Look for Details "a" section}
if Crpe1.SectionFormat[cnt].Section = 'Da' then
begin
Crpe1.SectionFormat[cnt].BackgroundColor := clRed;
Crpe1.SectionFormat[cnt].FreeFormPlacement := cTrue;
Crpe1.SectionFormat[cnt].KeepTogether := cTrue;
Crpe1.SectionFormat[cnt].NewPageAfter := cFalse;
VCI Re|etetce 0S
Crpe1.SectionFormat[cnt].NewPageBefore := cFalse;
Crpe1.SectionFormat[cnt].PrintAtBottomOfPage := cDefault;
Crpe1.SectionFormat[cnt].ResetPageNAfter := cFalse;
Crpe1.SectionFormat[cnt].Suppress := cTrue;
Crpe1.SectionFormat[cnt].SuppressBlankSection := cTrue;
Crpe1.SectionFormat[cnt].UnderlaySection := cDefault;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFurmat Prupcrtics
SectionFormat BackgroundColor property, Page 546
SectionFormat FreeFormPlacement property, Page 546
SectionFormat Hide property, Page 547
SectionFormat Item property, Page 548
SectionFormat ItemIndex property, Page 549
SectionFormat KeepTogether property, Page 549
SectionFormat NewPageAfter property, Page 550
SectionFormat NewPageBefore property, Page 551
SectionFormat PrintAtBottomOfPage property, Page 552
SectionFormat ResetPageNAfter property, Page 553
SectionFormat Section property, Page 553
SectionFormat Suppress property, Page 555
SectionFormat SuppressBlankSection property, Page 556
SectionFormat UnderlaySection property, Page 556
SectionFormat SectionAsCode property, Page 557
ScctiunFurmat Mcthuds
SectionFormat Add method, Page 558
SectionFormat Clear method, Page 559
SectionFormat CopyFrom method, Page 560
SectionFormat Count property, Page 560
SectionFormat Create method, Page 561
SectionFormat Delete method, Page 561
SectionFormat Destroy method, Page 562
VCI Re|etetce 06
SectionFormat Retrieve method, Page 562
SectionFormat SectionType method, Page 563
SectionFormat Send method, Page 564
ScctiunFurmatFurmuIas
DccIaratiun
property SectionFormatFormulas: TCrpeSectionFormatFormulas;
Typc
TCrpeSectionFormatFormulas = class(TPersistent)
Dcscriptiun
SectionFormatFormulas encapsulates the formula control over Section Formatting that is available in the
Format Section dialog of Crystal Reports designer.
The Section naming format has been adopted from the Crystal Reports "short" section naming convention, so
RH means ReportHeader, GH3 means GroupHeader 3, etc. See About Section Names, Volume 1, Chapter 7, for
more information.
G The Name property specifies which Format option the SectionFormatFormula will act on. Names,
NameCount, IndexOfName and NameIndex can also be used to manipulate the Formula names list.
G The Section property specifies which section of the Report that the formula will apply to.
G The Retrieve method will obtain the SectionFormatFormula information from the Report.
G The Count method returns the number of items currently contained in the SectionFormatFormulas
object.
G The Item and ItemIndex properties can be used to navigate through the different Section items in the
SectionFormatFormulas object.
G The Add and Delete methods can be used instead of Retrieve/Clear, to manually add items to the
SectionFormatFormulas object.
G The SectionAsCode property offers the ability to treat the Section name as a Section Code Number,
which can be useful for doing mathematical expressions to filter out certain sections.
G The SectionType method returns just the first characters of the Section name, so for GH1 (Group Header
1), the SectionType would be GH (Group Header).
VCI Re|etetce 07
limitatiuns
SectionFormatFormulas has similar limitations to SectionFormat:
Main Report - For Page Header (PH) and Page Footer (PF) sections, the following Formula names do not apply:
sfKeepTogether
sfNewPageAfter
sfNewPageBefore
sfPrintAtBottomOfPage
Subreports - For Report Header b (RHb) and Report Footer b (RFb) sections, the following Formula names do
not apply:
sfKeepTogether
sfNewPageAfter
sfNewPageBefore
sfPrintAtBottomOfPage
Attempting to set Formulas for non-applicable Sections will cause errors when the Report is run.
ScctiunFurmatFurmuIas fxampIc
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;
VCI Re|etetce 08
ScctiunFurmatFurmuIas Prupcrtics
SectionFormatFormulas Formula property, Page 564
SectionFormatFormulas Item property, Page 565
SectionFormatFormulas ItemIndex property, Page 566
SectionFormatFormulas Name property, Page 567
SectionFormatFormulas NameIndex property, Page 570
SectionFormatFormulas Names property, Page 571
SectionFormatFormulas Section property, Page 572
SectionFormatFormulas SectionAsCode property, Page 573
ScctiunFurmatFurmuIas Mcthuds
SectionFormatFormulas Add method, Page 574
SectionFormatFormulas Check method, Page 575
SectionFormatFormulas Clear method, Page 575
SectionFormatFormulas CopyFrom method, Page 576
SectionFormatFormulas Count method, Page 577
SectionFormatFormulas Create method, Page 577
SectionFormatFormulas Delete method, Page 578
SectionFormatFormulas Destroy method, Page 578
SectionFormatFormulas IndexOf method, Page 579
SectionFormatFormulas IndexOfName method, Page 580
SectionFormatFormulas NameCount method, Page 582
SectionFormatFormulas Retrieve method, Page 583
SectionFormatFormulas SectionType method, Page 584
SectionFormatFormulas Send method, Page 585
ScctiunHcight
DccIaratiun
property SectionHeight: TCrpeSectionHeight;
Typc
TCrpeSectionHeight = class(TPersistent)
VCI Re|etetce 00
Dcscriptiun
SectionHeight controls the minimum height of each section in the Report. It can be used to expand the size of
a Section. Its main properties and methods are as follows:
G The Retrieve method can be used to obtain the SectionHeight information from a Report.
G The Height property specifies the minimum Section height. The height is in twips, but these can be
converted to inches by the following formula: Inches := Twips / 1440;
G As on most of the other Crystal component objects, the default array property, Item, or the ItemIndex
property can be used to navigate the object through the Sections.
G The SectionAsCode property offers the ability to treat the Section name as a Section Code Number,
which can be useful for doing mathematical expressions to filter out certain sections.
G The SectionType method returns just the first characters of the Section name, so for GH1 (Group Header
1), the SectionType would be GH (Group Header).
G The Section naming format has been adopted from the Crystal Reports "short" section naming
convention, so RHa means ReportHeader a, GH3b means GroupHeader 3b, etc. See About Section
Names, Volume 1, Chapter 7, for more information.
NO7F: Il a SeclonHeghl value s secled whch s less lhan lhe aclual Seclon heghl, l wll be gnored when
lhe Reorl s run. SeclonHeghl checks lhe currenl heghl ol each Seclon, and lhen sends n lhe
SeclonHeghl values only l lhey are larger lhan lhe currenl heghl ol lhe Seclon.
ScctiunHcight fxampIc
The code below retrieves the SectionHeight settings from the Report, then loops through looking for the
Details "a" section and sets the Height for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionHeight.Retrieve;
for cnt := 0 to (Crpe1.SectionHeight.Count - 1) do
begin
{Look for Details area}
if Crpe1.SectionHeight[cnt].Section = 'Da' then
Crpe1.SectionHeight[cnt].Height := 400;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
The following example sets the Section height for the first section of the Report to 400 twips:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.SectionHeight.Retrieve;
Crpe1.SectionHeight[0].Height := 400;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 166
ScctiunHcight Prupcrtics
SectionHeight Height property, Page 585
SectionHeight Item property, Page 586
SectionHeight ItemIndex property, Page 587
SectionHeight Section property, Page 587
SectionHeight SectionAsCode property, Page 589
ScctiunHcight Mcthuds
SectionHeight Add method, Page 589
SectionHeight Clear method, Page 590
SectionHeight CopyFrom method, Page 591
SectionHeight Count method, Page 591
SectionHeight Create method, Page 592
SectionHeight Delete method, Page 592
SectionHeight Destroy method, Page 593
SectionHeight Retrieve method, Page 593
SectionHeight SectionType method, Page 594
SectionHeight Send method, Page 595
ScIcctiun
DccIaratiun
property Selection: TCrpeSelectionFormula;
Typc
TCrpeSelectionFormula = class(TPersistent)
Dcscriptiun
The Selection object deals with the Selection Formula of a Report. It's main properties and methods are:
G The Formula property is used to hold the text of the Selection Formula.
G The Replace property is a boolean property that specifies if the text in the Formula property will replace
the Selection that is already in the Report, or whether it will be ANDed on to the end of it.
VCI Re|etetce 161
G The Retrieve method will fetch the Selection Formula that is currently in the Report, and place it in the
Formula property.
G The Check method can be used to determine whether the Formula syntax is correct.
ScIcctiun fxampIc
This code sample passes a new Selection formula into the Report, replacing the one that was currently there:
Crpe1.ReportName := 'Report1.rpt';
Crpe1.Selection.Formula.Assign('{company.STATE} = "CA"');
{or Crpe1.Selection.Formula.Text := '{company.STATE} = "CA"';}
Crpe1.Selection.Replace := True;
Crpe1.Execute;
Since one line in the Crystal Reports Formula Editor is limited to 255 characters, Selections built with a large
number of items must be split onto more than one line. The code below handles this type of case. Items are
read from a ListBox, and after every 4, a new line is added to the Selection Formula:
procedure RunReport;
var
cnt1,cnt2 : integer;
sTmp : string;
begin
Crpe1.ReportName := 'D:\Company.rpt';
Crpe1.Selection.Formula.Clear;
{This Memo shows the syntax of the final Formula}
Memo1.Clear;
cnt1 := 0;
cnt2 := 0;
{If the ListBox contains items to add to the Selection}
if ListBox1.Items.Count > 0 then
begin
{Store the beginning of the Selection}
sTmp := '{company.CONAME} in [';
{Loop through the ListBox items}
while cnt1 < ListBox1.Items.Count do
begin
{Take 4 items per SelectionFormula line}
while cnt2 < 4 do
begin
{If it's the last item, add a close bracket}
if cnt1 = (ListBox1.Items.Count - 1) then
begin
sTmp := sTmp + '"' + Listbox1.Items[cnt1] + '"]';
cnt2 := 3;
end
VCI Re|etetce 162
{If it's not the last item, add a comma}
else
sTmp := sTmp + '"' + Listbox1.Items[cnt1] + '"' + ',';
{Increment the counters}
Inc(cnt2);
Inc(cnt1)
end;
{Reset the item counter}
cnt2 := 0;
{Add the line to the Selection}
Crpe1.Selection.Formula.Add(sTmp);
sTmp := '';
end;
end;
{Write the Formula to a Memo so we can view it}
Memo1.Lines.AddStrings(Crpe1.SelectionFormula);
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
Using VariabIcs with ScIcctiun FurmuIa
Delphi variables can be used with the Selection Formula if they are declared as string or converted to string
(regardless of the actual data type) before being passed to Crystal Reports. Remember also, that string values
require extra quotes for Crystal Reports, as well as the usual single quotes that Delphi requires. The following
examples cover some of the ways in which variables can be used:
1. Passing a String variable with extra quotes included:
var
sTmp : string
begin
sTmp := '"CA"';
Crpe1.Selection.Formula[0] := '{company.STATE} = ' + sTmp;
2. Passing a String variable without extra quotes included:
var
sTmp : string;
begin
sTmp := 'CA';
Crpe1.Selection.Formula[0] := '{company.STATE} = "' + sTmp + '"';
3. Passing a String variable from an Edit box without extra quotes included:
var
sTmp : string;
begin
sTmp := Edit1.Text;
Crpe1.Selection.Formula[0] := '{company.STATE} = "' + sTmp + '"';
VCI Re|etetce 16!
4. Passing Integer values from Edit boxes:
var
nStart : string;
nEnd : string;
begin
nStart := Edit1.Text;
nEnd := Edit2.Text;
Crpe1.Selection.Formula[0] := '{company.SALES} >= ' + nStart + 'AND
{company.SALES} <= ' + nEnd;
5. Passing Integer variables:
var
nSales : integer;
begin
nSales := 12345;
Crpe1.Selection.Formula[0] := '{company.SALES} > ' + IntToStr(nSales);
6. Passing Date variables (Crystal Reports accepts dates only as a string data type in the
Date(YYYY,MM,DD) format):
var
dStart : string;
dEnd : string;
begin
dStart := '1998,01,31';
dEnd := '1998,06,30';
Crpe1.Selection.Formula[0] := '{company.STARTDATE} in Date(' + dStart + ')
to Date(' + dEnd + ')';
7. Passing Date variables divided into Day, Month, Year:
var
dYear : string;
dMonth : string;
dDay : string;
begin
dYear := '1998';
dMonth := '06';
dDay := '31';
Crpe1.Selection.Formula[0] := '{company.STARTDATE} = Date(' + dYear + ',' +
dMonth + ',' + dDay + ')';
VCI Re|etetce 164
8. Passing Date variables entered in Edit boxes:
var
dYear : string;
dMonth : string;
dDay : string;
dWhole : string;
begin
dYear := Edit1.Text;
dMonth := Edit2.Text;
dDay := Edit3.Text;
dWhole := 'Date(' + dYear + ',' + dMonth + ',' + dDay + ')';
Crpe1.Selection.Formula[0] := '{company.STARTDATE} = ' + dWhole;
ScIcctiun Prupcrtics
Selection Formula property, Page 595
Selection Replace property, Page 596
ScIcctiun Mcthuds
Selection Check method, Page 597
Selection Clear method, Page 598
Selection CopyFrom method, Page 599
Selection Create method, Page 599
Selection Destroy method, Page 600
Selection Retrieve method, Page 600
Selection Send method, Page 601
ScndOnfxccutc
DccIaratiun
property SendOnExecute: Boolean;
Dcscriptiun
The SendOnExecute property determines if the settings stored in the Crystal Reports component are sent to
the Crystal Reports Print Engine when the Execute method is called. Normally this property should be left at
it's default, which is True.
VCI Re|etetce 16S
If SendOnExecute is set to False, each Sub-class property, and each property that does not belong to a Sub-
class, must be sent manually to the Print Engine using the Send method before the Execute method is called.
This feature is provided mainly for debugging purposes.
ScndOnfxccutc fxampIc
The code below illustrates the SendOnExecute property, although setting it to True is not normally necessary
as this is it's default state:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SendOnExecute := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
Scssiunlnfu
DccIaratiun
property SessionInfo: TCrpeSessionInfo;
Typc
TCrpeSessionInfo = class(TPersistent)
Dcscriptiun
SessionInfo contains the properties that set the specified Session Information when opening a Microsoft Access
Table that has security. In Microsoft Access 95 and later, an Access database can have Session security (also
known as User-Level security), Database-Level security, or both.
SessionInfo works on a table-by-table basis, so after the Retrieve method is called, there is one SessionInfo item
in the SessionInfo object for each table in the Report.
G The Propagate property can be used to apply the property values from the first item to the other items in
the SessionInfo object, so it is not necessary to set each one with UserID and Password.
G The UserID property specifies the user ID value needed for logging on to the system.
G If the Access database contains only Session security, simply pass the Session Password to the
UserPassword property.
G If the Access database contains database-level security, put the Session Password in the UserPassword
property, and the Database-Level Password in the DBPassword property.
G The Handle property specifies the handle to the current MS Access session. If the Handle property is not
set (the default value is 0), the Crystal Report Engine uses the UserID and UserPassword settings. In all
other cases it uses the Handle value.
G The default array property, Item, or the ItemIndex property, can be used to navigate through the
SessionInfo object.
VCI Re|etetce 166
Scssiunlnfu fxampIc
The code example below shows how to retrieve the SessionInfo and then loop through the items to set the
UserID and UserPassword before running the Report:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SessionInfo.Retrieve;
for cnt := 0 to (Crpe1.SessionInfo.Count - 1) do
begin
Crpe1.SessionInfo[cnt].UserID := 'Bond';
Crpe1.SessionInfo[cnt].UserPassword := '007';
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
Scssiunlnfu Prupcrtics
SessionInfo DBPassword property, Page 602
SessionInfo Handle property, Page 602
SessionInfo Item property, Page 603
SessionInfo ItemIndex property, Page 603
SessionInfo Propagate property, Page 604
SessionInfo Table property, Page 605
SessionInfo UserID property, Page 605
SessionInfo UserPassword property, Page 606
Scssiunlnfu Mcthuds
SessionInfo Add method, Page 607
SessionInfo Clear method, Page 607
SessionInfo CopyFrom method, Page 608
SessionInfo Count method, Page 609
SessionInfo Create method, Page 609
SessionInfo Delete method, Page 610
SessionInfo Destroy method, Page 610
SessionInfo Retrieve method, Page 610
SessionInfo Send method, Page 611
VCI Re|etetce 167
SurtFicIds
DccIaratiun
property SortFields: TCrpeSortFields;
Typc
TCrpeSortFields = class(TPersistent);
Dcscriptiun
The SortFields object contains the properties needed to set and modify the Record Sort Order for a Report. The
main properties are:
G The Number property contains the SortField number, which is zero-based.
G The Field property contains the actual SortField string. Remember to enclose field names in braces:
{company.STATE}. If you sort on a formula field, use the @ sign before the formula name:
{@FORMULANAME}.
G The Direction property specifies the sorting direction, either sdDescending, sdAscending, or sdDefault.
G The DeleteSF property can be used to delete a SortField. Remember that when a SortField is set to be
deleted, it is removed from the Report in memory, when the Report is run. To reference it again, the Report
would have to be loaded again, or the SortField would have to be added back using the Add method.
G The Retrieve method will load the Crystal component with the SortFields currently in the Report.
G The Count method will return the number of SortFields items stored in the SortFields object.
G The Item and ItemIndex properties can be used to navigate through the items in the SortFields object.
SurtFicIds fxampIc
The code below loops through all the SortFields, changing the sort direction to descending:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SortFields.Retrieve;
for cnt := 0 to (Crpe1.SortFields.Count - 1) do
Crpe1.SortFields[cnt].Direction := sdDescending;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
VCI Re|etetce 168
SurtFicIds Prupcrtics
SortFields DeleteSF property, Page 612
SortFields Direction property, Page 612
SortFields Field property, Page 613
SortFields Item property, Page 613
SortFields ItemIndex property, Page 614
SortFields Number property, Page 615
SurtFicIds Mcthuds
SortFields Add method, Page 615
SortFields Clear method, Page 617
SortFields CopyFrom method, Page 618
SortFields Count method, Page 618
SortFields Create method, Page 619
SortFields Delete method, Page 619
SortFields Destroy method, Page 620
SortFields Retrieve method, Page 620
SortFields Send method, Page 621
SQl
DccIaratiun
property SQL: TCrpeSQL;
Typc
TCrpeSQL = class(TPersistent)
VCI Re|etetce 160
Dcscriptiun
The SQL object is only applicable to a Report created from an ODBC Data Source or from a native SQL
database connection and contains the SQL Query property and the Params object, which pertains to Stored
Procedure Parameters.
G The Query property contains the text of an SQL Query. The Query property can be used to update the
SQL Query that will be used to print the Report, typically to add optimizations to the WHERE clause.
This property is particularly useful for reports with SQL Queries that were explicitly edited in the
Show SQL Query dialog box in Crystal Reports (i.e., those reports that needed database-specific
selection criteria or joins). Otherwise it is usually best to continue using other properties such as
Selection and let Crystal Reports build the SQL Query automatically.
G The Retrieve method can be used to retrieve the SQL Query from a Report and fill the Query property.
Note that before using Retrieve, the necessary LogOn information should be set via the Connect or
LogOnInfo properties, otherwise the Query may be empty.
The SQL Query has the same restrictions as editing in the Show SQL Query dialog box in Crystal Reports. In
particular, changes are accepted in the FROM, WHERE, and ORDER BY clauses but they are ignored in the
SELECT part of the Query. The reason for this is that the SELECT is determined by the database fields that are
placed on the Report, and there is no way to remove or place new fields at runtime.
SQl fxampIc
Crpe1.ReportName := 'C:\Company.rpt';
{Set the Connect before attempting to retrieve the Query}
Crpe1.Connect.Retrieve;
Crpe1.Connect.Password := 'Aesop';
{Retrieve the Query}
Crpe1.SQL.Retrieve;
{Edit the WHERE clause, assuming in this case that it is line 5}
Crpe1.SQL.Query[4] := 'WHERE DEPT."LOC" = '''BOSTON'''';
Crpe1.Execute;
SQl Prupcrtics
SQL Expressions property, Page 622
G Properties
G SQL Expressions Expression property, Page 623
G SQL Expressions Item property, Page 623
G SQL Expressions ItemIndex property, Page 624
G SQL Expressions Name property, Page 625
G Methods
G SQL Expressions Add method, Page 626
G SQL Expressions Check method, Page 626
VCI Re|etetce 116
G SQL Expressions Clear method, Page 627
G SQL Expressions CopyFrom method, Page 628
G SQL Expressions Count method, Page 628
G SQL Expressions Delete method, Page 629
G SQL Expressions Destroy method, Page 630
G SQL Expressions IndexOf method, Page 630
G SQL Expressions Retrieve method, Page 631
G SQL Expressions Send method, Page 632
SQL Params property, Page 632
G Properties
G SQL Params AsBoolean property, Page 634
G SQL Params AsDate property, Page 634
G SQL Params AsDateTime property, Page 635
G SQL Params AsFloat property, Page 635
G SQL Params AsInteger property, Page 636
G SQL Params Item property, Page 636
G SQL Params ItemIndex property, Page 637
G SQL Params Name property, Page 638
G SQL Params ParamType property, Page 639
G SQL Params Value property, Page 640
G Methods
G SQL Params Add method, Page 641
G SQL Params Clear method, Page 641
G SQL Params CopyFrom method, Page 642
G SQL Params Count method, Page 643
G SQL Params Create method, Page 643
G SQL Params Delete method, Page 643
G SQL Params Destroy method, Page 644
G SQL Params Retrieve method, Page 644
G SQL Params Send method, Page 645
SQL Query property, Page 646
VCI Re|etetce 111
SQl Mcthuds
SQL Clear method, Page 647
SQL CopyFrom method, Page 647
SQL Create method, Page 648
SQL Destroy method, Page 648
SQL Retrieve method, Page 649
SQL Send method, Page 650
Status
DccIaratiun
property Status: integer;
Dcscriptiun
Status is a run-time, read-only property that can be used after the Execute method to indicate the processing
status of the Report. It will return an integer value from the following list:
0 - The Print Engine or the PrintJob are not open.
1 - The Job has not started yet.
2 - The Job is in progress.
3 - The Job has completed successfully.
4 - The Job has failed.
5 - The Job has been canceled by the user.
6 - The Report has exceeded the record or time governors.
You can use this function in a number of programming situations, for example:
G to trigger error messages, i.e., when a print job fails (due to insufficient memory, insufficient disk space,
etc.),
G to trigger screen displays (hourglass, series of graphics, etc.) that confirm to the user that work is in
progress,
G to find out whether a job was canceled by the user after Execute.
VCI Re|etetce 112
Status fxampIc
The code below illustrates the use of Status to determine when the Job has completed:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
{Loop until the Job is finished processing}
while Crpe1.Status <> 3 do
Application.ProcessMessages;
Crpe1.CloseJob;
Subrcpurts
DccIaratiun
property Subreports: TCrpeSubreports;
Typc
TCrpeSubreports = class(TPersistent)
Dcscriptiun
Many of the properties and sub-class objects on the VCL can apply to the main Report, or any Subreports as
well. When Subreports are involved, the Subreports object is used to distinguish which Report the VCL
properties are currently pointing to. Since the first item in the Subreports object (Subreports[0]) is always a
reference to the main Report, the Subreports object should probably have been called Reports, but for now just
bear in mind that Subreports[0] actually refers to the main Report.
The Subreports object maintains a list of Report names, including the Main Report, and any associated
Subreports, via the Name property.
The associated section the Subreports are located in is available via the Section property.
The Subreports object can be filled automatically, by using Retrieve, or it can be filled/emptied manually using
the Add and Delete methods. Note that Retrieve will not retrieve all of the information about a Report, such as
Formulas, Tables, etc. Retrieve for the Subreports object simply gathers the Subreport names and sections, opens
a printjob for each Subreport, and creates sub-class objects (Formulas, Tables, etc.) for each Subreport. These sub-
class objects still need to have their information retrieved using their own Retrieve methods.
The Count method returns the number of items in the Subreports object, and includes the Main Report.
The Clear method is used to remove the Subreport information, which includes the information set for the
main Report as well.
Navigating through the Subreports can be accomplished via the default array property: Item, the ItemIndex
property, or the Name property. Since Item is a default array index property, it does not need to be specified
when making the call: Subreports[1] sets the Crystal component to the first Subreport.
VCI Re|etetce 11!
The SubExecute property determines whether Subreports can be run as stand-alone Reports or not. If it is set
to True, and the Subreports object is pointing to a Subreport when the Execute method is called, the Subreport
will run instead of the main Report.
The NLinks and OnDemand properties are new to SCR 7. They are read-only properties which give further
information about the Subreport.
NO7F: Il s morlanl lo remember lhal lhe Subreorls objecl allecls almosl every olher roerly n lhe
Cryslal comonenl. Il lhe Subreorls objecl s changed lrom lhe man Reorl (Subreorls[0]) lo a Subreorl
(Subreorls[1]), lhen all ol lhe roerles lhal can aly lo Subreorls wll now be onlng lo lhal Subreorl
also.
Subrcpurts fxampIc
To obtain the names of the Subreports, read the Name property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
doListBox1.Items.Add(Crpe1.Subreports.Name);
This example shows how to set properties on the main Report and first Subreport, and then run the main
Report:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the Subreports}
Crpe1.Subreports.Retrieve;
{Retrieve the main Report Tables}
Crpe1.Tables.Retrieve;
{Set the Path for the first Table}
Crpe1.Tables[0].Path := 'C:\Reports\';
{Propagate Path for all main & sub tables}
Crpe1.Tables.Propagate := True;
{Point to first Subreport}
Crpe1.Subreports[1];
{Set Subreport Selection Formula}
Crpe1.Selection.Formula.Text := '{company.STATE} = "CA"';
{Set Output}
Crpe1.Output := toWindow;
{Run the Report - As long as the Subreports.SubExecute is set to False, the
main Report will run on Execute, regardless of which Subreport is currently
selected}
Crpe1.Execute;
Subrcpurts Prupcrtics
Subreports Item property, Page 650
Subreports ItemIndex property, Page 651
VCI Re|etetce 114
Subreports Name property, Page 651
Subreports NLinks property, Page 653
Subreports OnDemand property, Page 653
Subreports Section property, Page 654
Subreports SubExecute property, Page 654
Subrcpurts Mcthuds
Subreports Add method, Page 655
Subreports Clear method, Page 656
Subreports CopyFrom method, Page 657
Subreports Count method, Page 658
Subreports Create method, Page 658
Subreports Delete method, Page 658
Subreports Destroy method, Page 659
Subreports IndexOf method, Page 659
Subreports Retrieve method, Page 660
Summarylnfu
DccIaratiun
property SummaryInfo: TCrpeSummaryInfo;
Typc
TCrpeSummaryInfo = class(TPersistent)
Dcscriptiun
The SummaryInfo object contains properties that hold Summary Information about the Report. Summary
Information is made up of various fields that describe the Report and are useful for entering more detailed
descriptions about the Report than can be specified in the filename itself:
G Summary Information consists of the Title of the Report, it's Author, Subject, Template, Keywords, and
Comments.
G The Title property holds the same information as the ReportTitle property, or the Report Title field in
Crystal Reports Designer.
VCI Re|etetce 11S
G The Comments property holds the same information as the Report Comments field in Crystal Reports
Designer.
G If Summary Information has been entered when the Report was designed, it can be retrieved using the
Retrieve method.
NO7F: You musl have Cryslal 6.0 or hgher lo use SummaryInlo.
Summarylnfu fxampIc
The following code sets two properties of the SummaryInfo object, and then exports the Report to a new
Crystal Report:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.SummaryInfo.Title := 'My New Report';
Crpe1.SummaryInfo.Comments.Text := 'A new Report.';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := CrystalReportsRPT;
Crpe1.Export.FileName := 'c:\NewReport.rpt';
Crpe1.Execute;
Summarylnfu Prupcrtics
SummaryInfo AppName property, Page 661
SummaryInfo Author property, Page 662
SummaryInfo Comments property, Page 662
SummaryInfo Keywords property, Page 663
SummaryInfo Subject property, Page 663
SummaryInfo Template property, Page 664
SummaryInfo Title property, Page 664
Summarylnfu Mcthuds
SummaryInfo Clear method, Page 665
SummaryInfo CopyFrom method, Page 665
SummaryInfo Create method, Page 666
SummaryInfo Destroy method, Page 666
SummaryInfo Retrieve method, Page 667
SummaryInfo Send method, Page 667
VCI Re|etetce 116
TabIcs
DccIaratiun
property Tables: TCrpeTables;
Typc
TCrpeTables = class(TPersistent)
Dcscriptiun
The Tables object maintains a list of Table information. The Name property is the Name of the Table. There are
three general types of tables:
1. Native PC-type databases such as dBase, FoxPro, or Paradox, in which the Table Name is usually the
same as the actual filename, and the Path is the actual DOS directory to the file. In these cases, the Name
property can be used to change which Table is being used by the Report, the Path property can be used to
change the directory in which the Table is located, and the Propagate property can be used to set all
Tables to the same directory. The Password property applies to Paradox password-protected Tables.
2. Native PC-type databases such as Access, where the Table Name is the name of a table within the Database.
In these cases, the Name property is the Name of the Database (or Access MDB file) which contains the
Tables and the Path is the directory to the Database, not to the individual Table. It is possible to use the
Tables object to change to a different MDB file, but it is not possible to change to a different Table within the
same MDB. That must be done within the Crystal Reports Designer. For Access Password-protected Tables,
use the SessionInfo object instead of the Password property of the Tables object.
3. SQL-type tables such as Oracle, Sybase, Informix, MS SQL Server, or ODBC Datasources. In these cases,
Path and Propagate are not used. The Name property contains the name of the Table (and sometimes
Database or User names as well) and can be used to point the Report to a different Table within the
currently logged on Server.
G The TableType, DLLName, and DescriptiveName properties are read-only properties which contain
descriptive information about the Table, and are filled with values when the Retrieve method is used.
G The ItemIndex property or the default array property, Item, can be used to navigate through the Tables.
G The Count method returns the number of Tables in the current Report.
G The Clear method can be used to clear the Tables object of all information, although this is normally
handled automatically in the VCL whenever the ReportName is changed.
G The Add and Delete properties are manual methods of maintaining the Tables object internal lists and
are not needed if the Retrieve method is used.
G The Send method sends the Table information from the VCL to the Crystal Reports Print Engine. This is
normally handled in the Execute method of the VCL.
VCI Re|etetce 117
TabIcs fxampIc
In this example, the Tables are retrieved, and then a loop is set up to change the Path for all the tables:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Tables.Retrieve;
for cnt := 0 to (Crpe1.Tables.Count - 1) do
Crpe1.Tables[cnt].Path := 'c:\MyNewPath\';
Crpe1.Execute;
In the above scenario, the Propagate property could also be used, so that it would only be necessary to set the
path for the first table:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Tables.Retrieve;
Crpe1.Tables[0].Path := 'c:\MyNewPath\';
Crpe1.Tables.Propagate := True;
Crpe1.Execute;
TabIcs Prupcrtics
Tables DescriptiveName property, Page 668
Tables DLLName property, Page 668
Tables Item property, Page 669
Tables ItemIndex property, Page 670
Tables Name property, Page 670
Tables Number property, Page 671
Tables Password property, Page 672
Tables Path property, Page 672
Tables Propagate property, Page 673
Tables TableType property, Page 674
TabIcs Mcthuds
Tables Clear method, Page 676
Tables CopyFrom method, Page 677
Tables Count method, Page 677
Tables Create method, Page 678
Table Delete method, Page 678
Tables Destroy method, Page 679
Tables Retrieve method, Page 679
Tables Send method, Page 680
VCI Re|etetce 118
Vcrsiun
DccIaratiun
property Version: TCrpeVersion;
Typc
TCrpeVersion = class(TPersistent)
Dcscriptiun
The Version property is a Sub-class that contains properties which display the version numbers of the
CRPE32.DLL, the Crystal Reports Print Engine, and the Operating System:
G The DLL property contains the CRPE32.DLL internal version number.
G The Engine property contains the CRPE32.DLL internal engine number.
G The Windowsproperty contains the current Windows operating system version.
G The FileVersion property contains the full CRPE32.DLL file version number (as a string).
G The Major property contains the first number sequence of the file version string (as an integer).
G The Minor property contains the last number sequence of the file version string (as an integer).
The Version properties are useful for checking to make sure the proper DLL/Engine is loaded. They are also
used internally in the VCL for:
G The ParamFields object, which requires Crystal 5.0 (108 release) or later.
G The WindowButtonBar (except for the Visible property, which applies to Crystal 5 and up).
G The SummaryInfo, WindowEvents, and GroupOptions, which only apply to Crystal 6.0.
G The Excel5Ext Export options, the new ParamFields properties and ParamFields Info and Ranges
objects, the SQL Expressions object, the ReportOptions object, the wOnRightMouseClick event, the
VerifyDatabase method and FieldMapping property, the OnFieldMapping event, and the
OutputFileName property of PrintOptions, all of which only apply to Crystal 7.0.
NO7F: Allhough nol normally recommended, lhe Major and Mnor verson numbers can be over-rdden n lhe
OnGelVerson evenl.
Vcrsiun fxampIc
The following example checks to see if the version of the CRPE32.DLL is greater than 5. If it is, the
WindowButtonBar buttons can be made visible/invisible.
if StrToInt(Crpe1.Version.DLL[1]) > 5 then
Crpe1.WindowButtonBar.AllowDrillDown := True;
VCI Re|etetce 110
Vcrsiun Prupcrtics
Version DLL property, Page 681
Version Engine property, Page 681
Version Major property, Page 682
Version Minor property, Page 682
Version Windows property, Page 683
Vcrsiun Mcthuds
Version Clear method, Page 683
Version CopyFrom method, Page 684
Version Create method, Page 684
Version Retrieve method, Page 685
WinduwButtunBar
DccIaratiun
property WindowButtonBar: TCrpeWindowButtonBar;
Typc
TCrpeWindowButtonBar = class(TPersistent)
Dcscriptiun
The WindowButtonBar object contains 13 properties that relate to the Button Bar that appears on the Crystal
Reports Preview Window.
G The Visible property determines if the Button Bar is visible or not. This is the only property that can be
used with Crystal Reports 5.0. The rest of the properties apply to Crystal 6.0 and higher.
Crystal Reports 6.0 introduced 6 new buttons and one new option to the Button Bar/Preview Window and
provided the capability of specifying which of the buttons should appear. The new features are:
G AllowDrillDown
G CancelBtn
G CloseBtn
G GroupTree
G PrintSetup
G RefreshBtn
G SearchBtn
VCI Re|etetce 126
If the Preview Window is made a Child of a Delphi Form by attaching the WindowParentHandle property to
the Form's Handle. A custom button bar can then be designed; it may be desirable to turn off the Crystal
Button Bar by setting the Visible property to False. Bear in mind, though, that not all the buttons currently on
the Crystal Reports Preview Window can be mimicked in code.
The following buttons can be simulated in code:
G CancelBtn - CancelJob
G CloseBtn - CloseWindow
G ExportBtn - ExportWindow
G NavigationCtls - Pages
G PrintBtn - PrintOptions.PromptForOptions and PrintWindow
G ProgressCtls - Records
G ZoomCtl - WindowZoom
The following buttons cannot be reproduced in code yet:
G AllowDrillDown
G GroupTree
G PrintSetupBtn
G RefreshBtn
G SearchBtn
The PrintSetupBtn can be partly reproduced by calling a PrinterSetup dialog and then using the GetCurrent
method of the Printer object (or just using the ShowPrintDlg method of the Printer object), but this will not
affect the current Preview Window or the PrintWindow method, as it will if the PrinterSetup button is called
from the Crystal Button Bar.
WinduwButtunBar fxampIc
This code example sets the WindowButtonBar properties so that Drill-Down is possible and the Cancel button
is hidden:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowButtonBar do
begin
Visible := True;
AllowDrillDown := True;
CancelBtn := False;
end;
Crpe1.Execute;
VCI Re|etetce 121
WinduwButtunBar Prupcrtics
WindowButtonBar AllowDrillDown property, Page 685
WindowButtonBar CancelBtn property, Page 686
WindowButtonBar CloseBtn property, Page 686
WindowButtonBar ExportBtn property, Page 687
WindowButtonBar GroupTree property, Page 688
WindowButtonBar NavigationCtls property, Page 688
WindowButtonBar PrintBtn property, Page 689
WindowButtonBar PrintSetupBtn property, Page 690
WindowButtonBar ProgressCtls property, Page 690
WindowButtonBar RefreshBtn property, Page 691
WindowButtonBar SearchBtn property, Page 692
WindowButtonBar Visible property, Page 692
WindowButtonBar ZoomCtl property, Page 693
WinduwButtunBar Mcthuds
WindowButtonBar Clear method, Page 693
WindowButtonBar CopyFrom method, Page 694
WindowButtonBar Create method, Page 695
WindowButtonBar Retrieve method, Page 695
WindowButtonBar Send method, Page 695
WinduwCursur
DccIaratiun
property WindowCursor : TCrpeWindowCursor;
Typc
TCrpeWindowCursor = class(TPersistent)
VCI Re|etetce 122
Dcscriptiun
The WindowCursor properties can be used to change the shape of the Mouse Cursor when it passes over
certain areas of the Preview Window. The specific areas that can be affected are:

The Mouse Cursor shapes available are:
WindowCursor would normally be used in conjunction with WindowEvents, to trigger some action in
response to a user-event on the Preview Window. The change in Cursor shape would be an indication to the
user that a special action is to occur when that area of the Window is clicked.
GroupArea Any Group section
GroupAreaField Any Field in a Group section
DetailArea Any Detail section
DetailAreaField Any Field in a Detail section
Graph Any Graph
wcDefault No change in cursor shape. The cursor shape will be either according to Crystal
Reports standard behavior if the Report has not been run yet, or whatever the last
chosen cursor shape was if the Report was run just previously.
Cursor Name Shae Cursor Name Shae
wcArrow wcSizeWE
wcCross wcSizeNS
wcIBeam wcNo
wcUpArrow wcWait
wcSizeAll wcAppStart
wcSizeNWSE wcHelp
wcSizeNESW wcMagnify
VCI Re|etetce 12!
WinduwCursur fxampIc
The example below sets the Mouse Cursor to a Magnifying Glass when it passes over a Group Area on the
Preview Window:
Crpe1.ReportName := 'C:\Company.rpt;
Crpe1.WindowCursor.GroupArea := wcMagnify;
Crpe1.Output := toWindow;
Crpe1.Execute;
WinduwCursur Prupcrtics
WindowCursor DetailArea property, Page 696
WindowCursor DetailAreaField property, Page 697
WindowCursor Graph property, Page 697
WindowCursor GroupArea property, Page 698
WindowCursor GroupAreaField property, Page 698
WinduwCursur Mcthuds
WindowCursor Clear method, Page 699
WindowCursor CopyFrom method, Page 700
WindowCursor Create method, Page 700
WindowCursor Retrieve method, Page 700
WindowCursor Send method, Page 701
Winduwfvcnts
DccIaratiun
property WindowEvents: boolean;
Dcscriptiun
The WindowEvents property activates the Preview Window callback events. These callback events allow Delphi
to respond to actions that take place on the Crystal Reports Preview Window, such as button clicks and drill-
down events. The various events listed on the Events page of the Object Inspector, and are prefixed with "w":
wOnActivateWindow
wOnCancelBtnClick
wOnCloseBtnClick
wOnCloseWindow
VCI Re|etetce 124
wOnDeActivateWindow
wOnDrillDetail
wOnDrillGroup
wOnExportBtnClick
wOnFirstPageBtnClick
wOnGroupTreeBtnClick
wOnLastPageBtnClick
wOnNextPageBtnClick
wOnPreviousPageBtnClick
wOnPrintBtnClick
wOnPrintSetupBtnClick
wOnReadingRecords
wOnRefreshBtnClick
wOnRightMouseClick
wOnSearchBtnClick
wOnShowGroup
wOnStartEvent
wOnStopEvent
wOnZoomLevelChange
The WindowEvents property should be set before Execute is called.
NO7F: WndowFvenls are only avalable wlh SCR 6 or hgher.
Winduwfvcnts fxampIc
This code activates the Preview Window callback events:
Crpe1.ReportName := 'Report1.rpt';
Crpe1.Output := toWindow;
Crpe1.WindowEvents := True;
Crpe1.Execute;
WinduwParcnt
DccIaratiun
property WindowParent: TCrWinControl;
Typc
TCrWinControl = TWinControl;
Dcscriptiun
WindowParent is a run-time only property that can be used to attach the Crystal Preview Window to a Delphi
Form. This is useful when you want to create a custom button bar, or make the Crystal window an MDI child.
VCI Re|etetce 12S
DcaIing with MDl Furms
There are two options when using an MDI Form:
1. With version 7.x of the VCL, the WindowParent property now has built-in support for MDI forms. If it
detects that the Form specified in the WindowParent property is an MDI Form (FormStyle = fsMDIForm),
it will create a Delphi MDI Child Form, and attach the Crystal Preview Window to that child. In this way,
Delphi's built-in support for MDI child windows is preserved. Resizing of the Crystal Preview Window
with the MDI Child is automatically handled inside the Crystal VCL. The child form is freed when the
MDI Child window is closed.
2. Programmer's may want more control over the appearance and behavior of their MDI Child forms,
beyond what is offered via option 1. In that case, we recommend that you make the Parent and Child
Forms in Delphi, attach the Crystal component to the Child Form, and set the WindowParent of the
component to the Child Form. To set the WindowParent property, simply pass it the name of the Form or
Panel desired. The resize event will have to be coded, so that the Crystal Preview Window resizes with
the Child form:
procedure TChildForm1.OnResize(Sender: TObject);
begin
SetWindowPos(Crpe1.ReportWindowHandle, HWND_TOP, 0, 0,
ChildForm1.ClientWidth, ChildForm1.ClientHeight, SWP_NOZORDER);
end;
For a working example of option 2, see our MDI32 Sample Application.
NO7F: Imorlanl! When allachng lhe Cryslal Prevew wndow lo anolher Form va lhe WndowParenl
roerly, be carelul lo make sure lhe Cryslal Wndow s closed belore lhe Form l s allached lo s deslroyed.
7hs wll nol be a roblem l lhe VCI s allached lo lhe Chld Form, snce l wll be deslroyed wlh lhe Chld.
Bul l lhe VCI comonenl s slll n exslence when lhe Chld Form s deslroyed, an Access Volalon wll occur
when lhe VCI s lnally lreed, or ossbly when lhe Prnl )ob closes. One way lo avod lhe error s lo ul a
Cre1.CloseWndow call n lhe Chld Forms OnClose evenl:
procedure TChildForm1.OnClose(Sender: TObject; var Action: TCloseAction);
begin
Crpe1.CloseWindow;
Release;
end;
WinduwParcnt fxampIc
The code below makes the Crystal Preview Window a child of Form1:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.WindowState := wsNormal;
Crpe1.Output := toWindow;
Crpe1.WindowStyle.BorderStyle := bsNone;
VCI Re|etetce 126
{Attach Crystal Window to Parent Window}
Crpe1.WindowParent := Form1;
{Crystal Window Size Settings}
Crpe1.WindowSize.Top := 0;
Crpe1.WindowSize.Left := 0;
Crpe1.WindowSize.Height := Form1.Height - 30;
Crpe1.WindowSize.Width := Form1.Width - 8;
{Run the Report}
Crpe1.Execute;
{On Form Resize}
procedure TForm1.FormResize(Sender: TObject);
var
WinHandle: hWnd;
begin
WinHandle := Crpe1.ReportWindowHandle;
SetWindowPos(WinHandle, HWND_TOP, 0, 0, Self.ClientWidth, Self.ClientHeight,
SWP_NOZORDER);
end;
WinduwSizc
DccIaratiun
property WindowSize: TCrpeWindowSize;
Typc
TCrpeWindowSize = class(TPersistent)
Dcscriptiun
WindowSize contains four properties that determine the position and size of the Crystal Reports runtime
Preview Window.
G The Top and Left properties determine the position of the Window, starting with the top
left corner.
G The Height and Width properties determine the size of the window.
G The coordinates are in pixels.
G Use -1 for default Window size and placement.
G Values less than -1 will generate an error.
VCI Re|etetce 127
WinduwSizc fxampIc
The following example displays a Report in a Preview Window. The window will appear in the upper left
corner of the screen and will be 300 pixels high, and 500 pixels wide:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowSize do
begin
Left := 0;
Top := 0;
Height := 300;
Width := 500;
end;
Crpe1.Execute;
WinduwSizc Prupcrtics
WindowSize Height property, Page 701
WindowSize Left property, Page 702
WindowSize Top property, Page 703
WindowSize Width property, Page 703
WinduwSizc Mcthuds
WindowSize Clear method, Page 704
WindowSize CopyFrom method, Page 705
WindowSize Create method, Page 705
WindowSize Retrieve method, Page 705
WindowSize Send method, Page 706
WinduwStatc
DccIaratiun
property WindowState: TWindowState;
Typc
TWindowState = (wsNormal, wsMinimized, wsMaximized);
VCI Re|etetce 128
Dcscriptiun
WindowState determines the state in which the Preview Window will appear. This property is only applicable
when Output is set to go toWindow.
G WindowState is now an active property; setting it while the Crystal Preview Window is open will cause
it to change the WindowState of the open window.
G When the Crystal Preview Window is open, it is also possible to update the WindowState setting by
calling RetrieveWindowState.
WinduwStatc fxampIc
Sets the Preview Window state to minimized:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.WindowState := wsMinimized;
Crpe1.Execute;
WinduwStyIc
DccIaratiun
property WindowStyle: TCrpeWindowStyle;
Typc
TCrpeWindowStyle = class(TPersistent)
Dcscriptiun
The WindowStyle property contains the properties which determine the Style of the Crystal Preview Window:
BorderStyle Window Border Style: sizeable, dialog, etc.
Disabled Determines if the Window is enabled or disabled.
SystemMenu The Windows menu that appears in the upper left corner of a Window.
MaxButton The Maximize button.
MinButton The Minimize button.
Title The Window Caption.
VCI Re|etetce 120
Depending on what BorderStyle is chosen, certain of the other options may or may not appear:
WinduwStyIc fxampIc
This code sample shows how to set the WindowStyle options:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
{Set the WindowStyle options}
with Crpe1.WindowStyle do
begin
BorderStyle := Sizeable;
SystemMenu := True;
MaxButton := True;
MinButton := True;
Title := 'MyReport';
end;
Crpe1.Execute;
WinduwStyIc Prupcrtics
WindowStyle BorderStyle property, Page 707
WindowStyle Disabled property, Page 707
WindowStyle MaxButton property, Page 708
WindowStyle MinButton property, Page 708
WindowStyle SystemMenu property, Page 709
WindowStyle Title property, Page 710
WinduwStyIc Mcthuds
WindowStyle Clear method, Page 710
WindowStyle CopyFrom method, Page 711
WindowStyle Create method, Page 712
BorderSlyle SyslemMenu MaxBullon MnBullon 7lle
bsNone n/a n/a n/a n/a
bsSingle Possible Possible Possible Possible
bsSizeable Possible Possible Possible Possible
bsDialog Possible n/a n/a Possible
VCI Re|etetce 1!6
WinduwZuum
DccIaratiun
property WindowZoom: TCrpeWindowZoom;
Typc
TCrpeWindowZoom = class(TPersistent)
Dcscriptiun
WindowZoom controls the zoom level of the Preview Window when sending a Report to window.
G The Preview property can be set to one of four pre-defined levels: pwNormal, pwPageWidth,
pwWholePage, or pwDefault.
G The Magnification property can be set to a Zoom percentage from 25 to 400 percent.
G The two properties are mutually exclusive, that is, assigning a value other than default to one of the
properties, will cause the other to be set to default.
G The WindowZoom properties can be set in code before or after the Execute method. If they are set after
Execute, and the Output property was set toWindow, they will change the zoom level of the current
Report window.
WinduwZuum fxampIc
This example sets the zoom magnification level of the Preview Window to 50 percent:
Crpe1.WindowZoom.Magnification := 50;
This example sets the Preview Window zoom level so that the Report will be sized to the width and height of
the window:
Crpe1.WindowZoom.Preview := pwWholePage;
WinduwZuum Prupcrtics
WindowZoom Magnification property, Page 712
WindowZoom Preview property, Page 713
WinduwZuum Mcthuds
WindowZoom CopyFrom method, Page 714
WindowZoom Create method, Page 714
WindowZoom NextLevel method, Page 714
WindowZoom Send method, Page 715
VCI Re|etetce 1!1
Mcthuds
These are the Methods that belong specifically to the TCrpe class. Each Sub-class also has its own Methods
which can be viewed by going to the section for that particular Sub-class.
BooleanToStr method, Page 132
CancelJob method, Page 133
Clear method, Page 133
Create method, Page 135
CloseEngine method, Page 136
CloseJob method, Page 137
CloseWindow method, Page 137
CopyFrom method, Page 138
DateTimeToStr method, Page 138
DateToStr method, Page 139
Destroy method, Page 139
ExportWindow method, Page 140
ExDateStr method, Page 140
ExDateTimeStr method, Page 141
Execute method, Page 142
ExTimeStr method, Page 144
FloatingToStr method, Page 144
Focused method, Page 145
GetPathFromAlias method, Page 145
GetToken method, Page 146
GetVersionInfo method, Page 147
HideWindow method, Page 147
IsStrEmpty method, Page 148
LogOnPrivateInfo method, Page 148
OpenEngine method, Page 151
OpenJob method, Page 151
PrintWindow method, Page 152
ReportWindowHandle method, Page 153
VCI Re|etetce 1!2
RetrieveDetailCopies method, Page 153
RetrieveFieldMapping method, Page 154
RetrieveReportTitle method, Page 154
RetrieveWindowState method, Page 154
SectionCodeToStr method, Page 155
SendDetailCopies method, Page 156
SendDialogParent method, Page 156
SendDiscardSavedData method, Page 157
SendFieldMapping method, Page 157
SendOutput method, Page 158
SendProgressDialog method, Page 158
SendReportTitle method, Page 159
SetFocus method, Page 159
ShowWindow method, Page 160
StrToBoolean method, Page 160
StrToDate method, Page 161
StrToDateTime method, Page 161
StrToFloating method, Page 162
StrToSectionCode method, Page 162
StrToTCrBoolean method, Page 163
StrToTime method, Page 163
TCrBooleanToStr method, Page 164
TimeToStr method, Page 164
TruncStr method, Page 165
VerifyDatabase method, Page 165
BuuIcanTuStr mcthud
DccIaratiun
function BooleanToStr(const bValue: boolean; ResultAsNum: boolean): string;
VCI Re|etetce 1!!
Dcscriptiun
BooleanToStr is used internally in the Crystal component, but has been exposed for general purpose use. It
takes a Boolean value and returns either a string ('True' or 'False') or a numeric string equivalent of the Boolean
value ('1' or '0'), if the ResultAsNum parameter is True.
str1 := Crpe1.BooleanToStr(True, False);
{str1 is now 'True'}
str1 := Crpe1.BooleanToStr(True, True);
{str1 is now '1'}
CanccI|ub mcthud
DccIaratiun
procedure CancelJob;
Dcscriptiun
CancelJob can be used to stop the processing of a Report. It can be called after the Execute method has been
called. Normally the CancelJob method would be associated with a button click, or some other user event,
therefore it is particularly useful when building a custom button bar to replace the standard Crystal Preview
Window button bar.
fxampIc
The following code cancels the running of the Report right after Execute. Normally the CancelJob call would
be associated with a button click, or some other user event:
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Execute;
Crpe1.CancelJob;
CIcar mcthud
DccIaratiun
procedure Clear;
VCI Re|etetce 1!4
Dcscriptiun
The Clear method for the Crystal component invokes the following Sub-class Clear methods for the main
Report as well as any subreports:
AreaFormat.Clear;
AreaFormatFormulas.Clear;
Connect.Clear;
Formulas.Clear;
GraphData.Clear
GraphOptions.Clear;
GraphText.Clear;
GraphType.Clear;
GroupCondition.Clear;
GroupOptions.Clear;
GroupSelection.Clear;
GroupSortFields.Clear;
LogOnInfo.Clear;
Margins.Clear;
ParamFields.Clear;
PrintDate.Clear;
SectionFont.Clear;
SectionFormat.Clear;
SectionFormatFormulas.Clear;
SectionHeight.Clear;
Selection.Clear;
SessionInfo.Clear;
SortFields.Clear;
SQL.Clear;
SQL.Params.Clear;
SQL.Expressions.Clear;
Tables.Clear;
DetailCopies := TCRPE_DEFAULT_DETAILCOPIES;
FieldMapping := fmAuto;
ReportTitle := '';
It then clears the following component Sub-class objects:
Export.Clear;
LogOnServer.Clear;
Printer.Clear;
PrintOptions.Clear;
ReportOptions.Clear;
Subreports.Clear;
SummaryInfo.Clear;
WindowButtonBar.Clear;
WindowCursor.Clear;
WindowSize.Clear;
WindowStyle.Clear;
WindowZoom.Clear;
VCI Re|etetce 1!S
It also sets the following properties to default:
CanCloseEngine := True;
DiscardSavedData := False;
HasSavedData := False;
IsJobFinished := True;
Output := toWindow;
ProgressDialog := True;
ReportName := '';
SendOnExecute := True;
WindowEvents := False;
WindowState := wsNormal;
Finally, it de-allocates any memory associated with the above classes and then closes the PrintJob. There are
some alternatives if the programmer does not want to clear all of these properties:
1. To clear just the Subreport structures, while leaving the main Report information intact, use
Subreports.Clear.
2. To clear the Subreport and main Report structures, while leaving the Window, Printer, and Export related
classes as they are, use CloseJob.
When a new Report is assigned to the ReportName property, a CloseJob call is invoked, not a Clear. Thus the
Window, Printer, and Export related settings are preserved. The only time the Clear method is called
internally in the component is when it is destroyed. However, if it is desired to have all the settings of the
component returned to default, the Clear method can be called before setting a new ReportName.
fxampIc
The following example loads a Report and runs it. When the Report has finished, the Crystal component is
cleared to set everything back to default, and another Report is loaded:
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Output := toPrinter;
Crpe1.Execute;
while not Crpe1.PrintEnded do
Application.ProcessMessages;
Crpe1.Clear;
Crpe1.ReportName := 'C:\NewReport.rpt';
Crcatc mcthud
DccIaratiun
constructor Create(AOwner: TComponent); override;
Dcscriptiun
The Create method is called when the Crystal component is created.
G If the component is attached to a Form, the Create method is called automatically when the Form is created.
G If the component is being created dynamically, then the Create method must be called in code (see Example).
VCI Re|etetce 1!6
fxampIc
The following code illustrates how to create the Crystal component dynamically:
uses Ucrpe32;
procedure RunReport;
var
Crpe1: TCrpe;
begin
{Create the Crpe instance}
Crpe1 := TCrpe.Create(Self);
{Set the ReportName}
Crpe1.ReportName := 'MyReport.rpt';
{Run the Report}
Crpe1.Execute;
{Go into a loop until the window is closed}
while Crpe1.ReportWindowHandle <> 0 do
Application.ProcessMessages;
{Remove the Crpe instance from memory}
Crpe1.Free;
end;
CIuscfnginc mcthud
DccIaratiun
procedure CloseEngine;
Dcscriptiun
CloseEngine causes any open Print Job to be closed, closes the Crystal Reports Print Engine DLL, and removes
it from memory. It usually happens automatically when the component is destroyed, or the Form on which
the component is attached is destroyed, but can also be called in code if desired.
fxampIc
The following example uses the CloseEngine method to unload the CRPE32.DLL after running a Report:
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Output := toPrinter;
Crpe1.Execute;
while not Crpe1.PrintEnded do
Application.ProcessMessages;
if Crpe1.CanCloseEngine then
Crpe1.CloseEngine;
VCI Re|etetce 1!7
CIusc|ub mcthud
DccIaratiun
procedure CloseJob;
Dcscriptiun
CloseJob closes the currently open Report in the Print Engine, and clears any memory allocated for it in the
Crystal component. This will not close a currently open Preview Window, but no further calls can be made
from the component to the window. If you want to close the Window, see the CloseWindow method.
CloseJob automatically takes place when the ReportName property is assigned a different Report name, or
when the Crystal component is destroyed, but can also be called in code if desired.
fxampIc
The following example uses the CloseJob method to close the Print Job after running a Report:
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Output := toPrinter;
Crpe1.Execute;
while not Crpe1.PrintEnded do
Application.ProcessMessages;
Crpe1.CloseJob;
CIuscWinduw mcthud
DccIaratiun
procedure CloseWindow;
Dcscriptiun
The CloseWindow method closes an open Preview Window. It does not Close the PrintJob, nor does it clear
the component. If you are customizing Preview Window controls, implement this method to allow the user to
close the Preview Window when finished viewing the Report.
Although it is possible to open up more than one Preview Window for the same PrintJob, the VCL can only
access the last one opened, hence CloseWindow will only work on the last window opened. If you need to
close more than one open Preview Window, consider storing the Window Handles to variables and using the
Windows API call "CloseWindow" to close these.
VCI Re|etetce 1!8
fxampIc
The following example runs a Report to Window. When a button on the application is pressed, the Window
is closed:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute
{When a close button is pressed do...}
if Crpe1.ReportWindowHandle > 0 then
Crpe1.CloseWindow;
CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpe): boolean;
Dcscriptiun
The CopyFrom method copies the Component values from another TCrpe object. It is similar to Delphi's
Assign method and is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the Component values to a temporary TCrpe object:
var
tempCrpe : TCrpe;
begin
tempCrpe := TCrpe.Create;
tempCrpe.CopyFrom(Crpe1);
{...later, when finished with the temp object...}
tempCrpe.Free;
end;
DatcTimcTuStr mcthud
DccIaratiun
function DateTimeToStr(const dtValue: TDateTime; bMSec: Boolean): string;
VCI Re|etetce 1!0
Dcscriptiun
DateTimeToStr is used internally in the Crystal component but has been exposed for general purpose use. It
takes a DateTime value and returns a string ('YYYY,MM,DD HH:NN:SS'). If the "bMSec" parameter is true,
milliseconds are added to the end of the Time part of the string.
str1 := Crpe1.DateTimeToStr(Now, False);
{str1 now looks something like this: '1999,01,01 12:02:31'}
str1 := Crpe1.DateTimeToStr(Now, True);
{str1 now looks something like this: '1999,01,01 12:02:31.000'}
DatcTuStr mcthud
DccIaratiun
function DateToStr(const dValue: TDateTime): string;
Dcscriptiun
DateToStr is used internally in the Crystal component but has been exposed for general purpose use. It takes
a DateTime value and returns a string ('YYYY,MM,DD').
str1 := Crpe1.DateToStr(Now);
{str1 now looks something like this: '1999,01,01'}
Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method frees the Crystal component. It is used internally in the VCL component and should not
be called outside of the component. If you are creating the component dynamically at run-time, use the Free
method to release the component from memory.
VCI Re|etetce 146
fxpurtWinduw mcthud
DccIaratiun
procedure ExportWindow(const bMail: Boolean);
Dcscriptiun
The ExportWindow procedure sends the Report that is displayed in the current Preview Window to an Export
destination. This procedure will not use the Export settings of the component but will instead prompt the user
for the Export Options (FileType, FileName, etc.), in the same way as when the Export button on the Crystal
Button Bar is clicked.
The "bMail" boolean determines if the first prompt will come up defaulted to Email as the Destination:
G If bMail is True, Email will come up as default.
G If bMail is False, Diskfile will appear as the default.
This method is particularly useful when building a custom button bar to simulate the Export Button that
appears on the Preview Window button bar.
fxampIc
The following example runs a Report to Window. When a button on the application is pressed, the Window
is exported:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
{When an Export button is pressed do...}
Crpe1.ExportWindow;
fxDatcStr mcthud
DccIaratiun
function ExDateStr(sValue: string; var sYear, sMonth, sDay: string): boolean;
VCI Re|etetce 141
Dcscriptiun
ExDateStr is used internally in the Crystal component but has been exposed for general purpose use. It takes
a Date string value and passes the individual parts into the Year/Month/Day var parameters.
var
sDate : string;
sY,sM,sD : string;
begin
sDate := '1998,02,03';
if Crpe1.ExDateStr(sDate, sY, sM, sD) then
ShowMessage('Y/M/D strings extracted successfully!');
end;
{sY = '1998'; sM = '02'; sD = '03'}
fxDatcTimcStr mcthud
DccIaratiun
function ExDateTimeStr(sValue: string; var sYear, sMonth, sDay, sHour, sMin,
sSec: string): boolean;
Dcscriptiun
ExDateTimeStr is used internally in the Crystal component, but has been exposed for general purpose use. It takes
a DateTime string value and passes the individual parts into the Year/Month/Day Hour/Min/Sec var parameters.
var
sDateTime : string;
sY,sM,sD,
sH,sN,sS : string;
begin
sDateTime := '1998,02,03 12:22:23';
if Crpe1.ExDateTimeStr(sDateTime, sY, sM, sD, sH, sN, sS) b
ShowMessage('Y/M/D H/M/S strings extracted successfully!');
end;
{sY = '1998'; sM = '02'; sD = '03';
sH = '12'; sN = '22'; sS = '23'}
VCI Re|etetce 142
fxccutc mcthud
DccIaratiun
function Execute: Boolean;
Dcscriptiun
The Execute method starts running the Report. Internally it runs through a number of steps:
1 Checks to see if it is being called from OnExecuteBegin, OnExecuteDoneSend, OnExecuteEnd,
OnPrintEnded, OnWindowClose events. If so, it exits since you cannot call Execute from an event inside
the Execute method.
2 If Output is set to go toExport, and the Export property, PromptOnOverwrite, is set to True, check to see
if the Export FileName exists. If it does, throw up a warning dialog box.
3 Make sure the Print Job is open.
4 Store the current Report number (in case we are on a Subreport), so we can restore it when finished.
S Check to see if the Subreports SubExecute property is True. If we are currently on a Subreport, and
SubExecute is True, the Subreport will be run. Otherwise, the main Report will be run.
6 Do the OnExecuteBegin event (if there is one).
7 If SendOnExecute is True, loop through the Subreports, starting from highest number down to main
Report and make the following calls (if SubExecute is True, we only loop once, making the calls to the
current Subreport):
SendDiscardSavedData;
{Sends either Connect or LogOnInfo}
Tables.Send;
SessionInfo.Send;
SQL.FParams.Send;
ParamFields.Send;
SQL.Expressions.Send;
SQL.Send; {SQL Query}
{if FieldMapping is not fmAuto, do VerifyDatabase}
Formulas.Send;
SortFields.Send;
GroupSortFields.Send;
GroupCondition.Send;
GroupOptions.Send;
Selection.Send;
GroupSelection.Send;
SectionHeight.Send;
SectionFont.Send;
VCI Re|etetce 14!
SectionFormat.Send;
SectionFormatFormulas.Send;
AreaFormat.Send;
AreaFormatFormulas.Send;
GraphType.Send;
GraphText.Send;
GraphOptions.Send;
GraphData.Send;
PrintDate.Send;
Margins.Send;
SendDetailCopies;
{These properties are set only once: either for the Main Report,
or for the Subreport if SubExecute is True}
SummaryInfo.Send;
ReportOptions.Send;
PrintOptions.Send;
Printer.Send;
SendProgressDialog;
SendDialogParent;
if (Output = toWindow) then
begin
WindowButtonBar.Send;
WindowCursor.Send
end;
SendOutput;
SendReportTitle;
8 Do the OnExecuteDoneSend Event, if there is one.
9 Set up the WindowEvents callback function for any assigned Window Events.
10 Run the Report.
11 If the Output is set to go toWindow, send in the WindowZoom settings:
if (Output = toWindow) then
WindowZoom.Send;
12 Check the OnExecuteEnd event, if there is one.
13 Check the OnWindowClose event, if there is one.
14 Check the OnPrintEnded event, if there is one.
1S Restore the internal pointer to the current Subreport.
VCI Re|etetce 144
fxampIc
The following code illustrates a simple use of the Execute method to run a Report to Window:
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute
fxTimcStr mcthud
DccIaratiun
function ExTimeStr(sValue: string; var sHour, sMin, sSec: string
): Boolean;
Dcscriptiun
ExTimeStr is used internally in the Crystal component but has been exposed for general purpose use. It takes
a Time string value and passes the individual parts into the Hour/Min/Sec var parameters.
var
sTime : string;
sH,sN,sS : string;
begin
sTime := '12:22:23';
if Crpe1.ExTimeStr(sTime, sH, sN, sS) then
ShowMessage('H/M/S strings extracted successfully!');
end;
{sH = '12'; sN = '22'; sS = '23'}
FIuatingTuStr mcthud
DccIaratiun
function FloatingToStr(const fValue: double): string;
Dcscriptiun
FloatingToStr is used internally in the Crystal component but has been exposed for general purpose use. It
takes a Floating point numeric value and returns the value as a string.
fValue := 1.23;
str1 := Crpe1.FloatingToStr(fValue);
{str1 now looks like this: '1.23'}
VCI Re|etetce 14S
Fucuscd mcthud
DccIaratiun
function Focused: boolean;
Dcscriptiun
Determines if the Crystal Preview window has focus or not (i.e. is it the uppermost window on the screen, the
one that receives keyboard and mouse input). This method can be used in concert with the SetFocus method.
fxampIc
This code example checks to see if the Crystal Preview Window is the topmost window. If not, it makes it the
topmost:
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
if not Crpe1.Focused then
Crpe1.SetFocus;
GctPathFrumAIias mcthud
DccIaratiun
function GetPathFromAlias(const Value: string): string;
Dcscriptiun
The GetPathFromAlias function is used internally in the Crystal component for converting BDE Aliases that
are passed into the Path property of the Tables object. It has been made available as a general purpose function
because some developers use BDE Aliases to store other path information, such as the directory that Reports
are stored in. The BDE Alias must be passed in with colons on each side, i.e.: ':MyAlias:' and will return a
standard pathname string with trailing backslash.
VCI Re|etetce 146
fxampIc
The following code illustrates the use of the GetPathFromAlias function to retrieve the path that the Reports
are stored in:
var
sPath: string;
begin
sPath := Crpe1.GetPathFromAlias(':MyReportsAlias:');
Crpe1.ReportName := sPath + 'Report1.rpt';
Crpe1.Execute;
end;
GctTukcn mcthud
DccIaratiun
function GetToken(var s: string; const sDelimiter: string): string;
Dcscriptiun
The GetToken function is used internally in the Crystal component, mostly for parsing date strings. It has been
made available as a general purpose function and will take a string, search for a delimiter character or string
of characters, and return the string up to the delimiter. Since the original string is passed as var it will be
modified in the function: the returned string and delimiter will be removed from the original string. Because
of this, GetToken can be used multiple times on the same string to obtain the various delimited parts.
fxampIc
The following code illustrates the use of the GetToken function to parse a date string (YYYY-MM-DD):
function GetDate(DateStr: string): TDateTime;
var
wYear,
wMonth,
wDay : Word;
begin
{Extract Year, Month, Day}
wYear := StrToInt(Crpe1.GetToken(DateStr, '-'));
{The DateStr now has MM-DD; wYear has YY}
wMonth := StrToInt(Crpe1.GetToken(DateStr, '-'));
{The DateStr now has DD; wMonth has MM}
wDay := StrToInt(DateStr);
Result := EncodeDate(wYear, wMonth, wDay);
end;
VCI Re|etetce 147
GctVcrsiunlnfu mcthud
DccIaratiun
function GetVersionInfo(const Filename: string; const Key: string
): string;
Dcscriptiun
GetVersionInfo is used internally in the Crystal component but has been exposed for general purpose use. It
takes a Filename (usually EXE or DLL) and a Key value to look for and returns a string with the actual value.
Key values can be things like:
FileVersion
FileDescription
LegalCopyright
Comments
CompanyName
InternalName
OriginalFilename
ProductName
ProductVersion
str1 := Crpe1.GetVersionInfo('CRPE32.DLL', 'FileVersion');
{str1 now looks something like this: '7.0.1.192'}
HidcWinduw mcthud
DccIaratiun
procedure HideWindow;
Dcscriptiun
The HideWindow method makes the Preview Window invisible. Use ShowWindow to make it appear again.
fxampIc
The following example illustrates the HideWindow method:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.HideWindow;
{...after a while...}
Crpe1.ShowWindow;
VCI Re|etetce 148
lsStrfmpty mcthud
DccIaratiun
function IsStrEmpty(const sValue: string): boolean;
Dcscriptiun
IsStrEmpty is used internally in the Crystal component but has been exposed for general purpose use. It takes
a string numeric value and returns a Boolean of either True (the string is empty) or False (the string is not
empty). The function will ignore leading or trailing spaces.
str1 := ' ';
if Crpe1.IsStrEmpty(str1) then
ShowMessage('str1 is empty!');
{str1 will be considered empty because spaces are ignored}
lugOnPrivatclnfu mcthud
DccIaratiun
function LogOnPrivateInfo(DllName: string; PrivateInfo: pointer): boolean;
Dcscriptiun
LogOnPrivateInfo can be used to "piggyback" the Crystal Reports database connection on your application's
existing connection to a Server. If you are already logged on, this function lowers the number of connections
established by a workstation, thus reducing application time and network traffic. It also prevents a Crystal
Reports Log Off call from disconnecting an application's existing connection to the Server. Note that this call
only works with ODBC connections.
The LogOnPrivateInfo call returns True if the call is successful; False if the call fails.
NO7F: Al lhe lme ol lhs wrlng, lhe relurn value s always 7rue. 7hs s nol a laull ol lhe Cryslal comonenl,
bul ralher lhe Prnl Fngne. Il wll hoelully be lxed n a lulure release ol lhe Prnl Fngne DII.
Parameler Descrlon
DllName Currently, this can only be 'PDSODBC.DLL'. Even though 32bit Crystal actually uses the
P2SODBC.DLL, we use PDSODBC.DLL to refer to either, in this call.
PrivateInfo In the application, a connection to the server has to have been established and this in
turn generates a Handle to a Database Connection (HDBC). This parameter specifies the
application's handle to the connection. This makes Seagate Crystal Reports aware of the
existing connection so it can use it instead of establishing a new one. Since the report
with which this function works are based on ODBC, this parameter is actually an ODBC
HDBC.
VCI Re|etetce 140
Rcmarks
This function can only be used with database connections established by ODBC or Q+E Library 2.0. Any other
database connections can not be accessed by this function.
If the application uses the Q+E Library to connect, get the ODBC HDBC by using the following function calls:
See the Intersolv DataDirect Developer's Toolkit for more information.
If the application uses ODBC to connect, get the ODBC HDBC by using the following function calls:
See the ODBC SDK documentation for more information.
fxampIc
The following code samples show how to prompt for an ODBC datasource, connect to it, and then piggyback
the Report on that connection. Note that the database connection used in the Report must be based off the same
datasource as the LogOnPrivateInfo call is connecting to:
uses
ODBC32;
implementation
{$R *.DFM}
var
henv : Pointer;
hdbc : Pointer;
hstmt : Pointer;
procedure TForm1.Connect;
var
ConIn, ConOut : MyUChar;
LenIn, LenOut : smallint;
RetCode : smallint;
TotOut : Pointer;
x, I : integer;
Flag : BOOL;
TempStr : string;
Temp, Temp2 : PChar;
begin
Flag:= False;
LenIn := 256;
LenOut := 256;
henv := nil;
hdbc := nil;
hstmt := nil;
qeConnect Opens a connection to the server.
qeGetODBCHdbc Returns the ODBC hdbc.
SQLAllocEnv Initializes the ODBC call level interface and allocates memory for an
environment handle.
SQLAllocConnect Returns an ODBC HDBC.
VCI Re|etetce 1S6
RetCode := SQLAllocEnv(henv);
if Retcode <> SQL_SUCCESS then
ShowMessage('SQLAllocEnv Failed');
RetCode := SQLAllocConnect(henv, hdbc);
if Retcode <> SQL_SUCCESS then
ShowMessage('SQLAllocConnect Failed');
FillChar(ConIn, 256, ' ');
RetCode := SQLDriverConnect(hdbc, Form1.Handle, ConIn,
LenIn, ConOut, LenOut,
TotOut, SQL_DRIVER_PROMPT);
if ((Retcode <> SQL_SUCCESS) and (Retcode <> SQL_SUCCESS_WITH_INFO)) then
begin
ShowMessage('SQLDriverConnect Failed');
Flag := True
end
else
begin
ShowMessage('SQLDriverConnect Successful');
EdtConnection.Text := StrPas(ConOut);
if RetCode = SQL_SUCCESS_WITH_INFO then
end;
RetCode := SQLAllocStmt(hdbc, hstmt);
if Retcode <> SQL_SUCCESS then
ShowMessage('SQLAllocStmt Failed');
end;
procedure TForm1.Disconnect;
var
RetCode : ShortInt;
begin
Crpe1.CloseJob;
RetCode := SQLFreeStmt(hstmt, SQL_CLOSE);
if Retcode <> SQL_SUCCESS then
ShowMessage('SQLFreeStmt Failed');
RetCode := SQLDisconnect(hdbc);
if Retcode <> SQL_SUCCESS then
ShowMessage('SQLDisconnect Failed');
RetCode := SQLFreeConnect(hdbc);
if Retcode <> SQL_SUCCESS then
ShowMessage('SQLFreeConnect Failed');
VCI Re|etetce 1S1
RetCode := SQLFreeEnv(henv);
if Retcode <> SQL_SUCCESS then
ShowMessage('SQLFreeEnv Failed');
end;
procedure TForm1.RunReport;
begin
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
Crpe1.OpenJob;
if not Crpe1.LogOnServerPrivateInfo('PDSODBC.DLL', hdbc) then
begin
ShowMessage('LogOnServerPrivateInfo Failed');
Exit;
end;
Crpe1.Execute;
end;
Opcnfnginc mcthud
DccIaratiun
procedure OpenEngine;
Dcscriptiun
OpenEngine forces the Crystal Reports Print Engine DLL to be loaded into memory and opened for use. It is
called automatically within the Crystal component but may be called in code if desired.
fxampIc
The following example uses the OpenEngine method to load the CRPE32.DLL (this is not normally necessary):
Crpe1.OpenEngine;
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Output := toPrinter;
Crpe1.Execute;
Opcn|ub mcthud
DccIaratiun
function OpenJob: boolean;
VCI Re|etetce 1S2
Dcscriptiun
The PrintJob is automatically opened as required by the Crystal component. If you want to force the Job to
open at an earlier time, such as right after the ReportName is assigned, it can be done through this method.
What du yuu mcan by "Opcn thc Print|ub"!
What this means is that the Crystal Reports Print Engine DLL loads the Report file into memory. Initially when
the ReportName property of the Crystal component is assigned a value, space is allocated internally in the
component, but the Print Engine does not yet need to load the Report, so the Print Job is not opened. As soon
as one of the Retrieve methods, or the Execute method is called, then the Print Engine loads the Report, and
processes it accordingly.
In the case of a Retrieve call, the Print Engine passes the desired values back to the Crystal component. In the
case of an Execute call, the Crystal component values are passed to the Print Engine, and then the Print Engine
runs the Report with those new values.
fxampIc
The OpenJob method is used to force the PrintJob open after the ReportName is set. Otherwise, OpenJob
would occur automatically when Execute is called, or any of the Retrieve methods:
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.OpenJob;
Crpe1.Output := toWindow;
Crpe1.Execute;
PrintWinduw mcthud
DccIaratiun
procedure PrintWindow;
Dcscriptiun
The PrintWindow procedure sends the Report that is displayed in the current Preview Window to printer. It
is particularly useful when building a custom button bar to simulate the Print Button that appears on the
Preview Window button bar.
fxampIc
The following example runs a Report to Window. When a button on the application is pressed, the Window
is printed:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
{When an Print button is pressed do...}
Crpe1.PrintWindow;
VCI Re|etetce 1S!
RcpurtWinduwHandIc mcthud
DccIaratiun
function ReportWindowHandle: integer;
Dcscriptiun
The ReportWindowHandle property returns the current Window Handle number of an open Preview
Window. It is useful for determining when the window is closed. For this purpose, the OnWindowClose event
can also be used.
fxampIc
The following example checks the ReportWindowHandle property to see when the Preview Window is
closed. When the window is closed, the application Form closes also:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
while Crpe1.ReportWindowHandle > 0 do
Application.ProcessMessages;
Close;
RctricvcDctaiICupics mcthud
DccIaratiun
function RetrieveDetailCopies: boolean;
Dcscriptiun
RetrieveDetailCopies returns the number of Detail Copies specified in the currently open Report and
populates the DetailCopies property with the value. This call can also be made to a Subreport.
fxampIc
The following example retrieves the Detail Copies from a Report:
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.RetrieveDetailCopies;
ShowMessage(IntToStr(Crpe1.DetailCopies));
VCI Re|etetce 1S4
RctricvcFicIdMapping mcthud
DccIaratiun
function RetrieveFieldMapping: boolean;
Dcscriptiun
This function returns the current FieldMapping setting from a Report and updates the FieldMapping property
accordingly.
RctricvcRcpurtTitIc mcthud
DccIaratiun
function RetrieveReportTitle: boolean;
Dcscriptiun
RetrieveReportTitle returns the Report Title from the currently open Report and populates the ReportTitle
property with the value. This call can also be made to a Subreport.
fxampIc
The following example retrieves the Report Title from a Report:
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.RetrieveReportTitle;
ShowMessage(Crpe1.ReportTitle);
RctricvcWinduwStatc mcthud
DccIaratiun
procedure RetrieveWindowState;
Dcscriptiun
RetrieveWindowState retrieves the current state of the open Preview Window and updates the WindowState
property with this value.
VCI Re|etetce 1SS
fxampIc
The following example uses the RetrieveWindowState call to obtain the state of the open Preview Window:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
{...after a while...}
Crpe1.RetrieveWindowState;
ScctiunCudcTuStr mcthud
DccIaratiun
function SectionCodeToStr(const Value: smallint): string;
Dcscriptiun
The SectionCodeToStr function is used internally in the Crystal component for the SectionAsCode properties
of the following objects:
AreaFormat
AreaFormatFormulas
SectionFormat
SectionFormatFormulas
SectionFont
SectionHeight
GraphType
GraphText
GraphOptions
GraphData
It takes a Print Engine Section Code number (i.e. 3026) and converts it to the Section naming convention that
the component uses (GH1b). It is mainly included as a public function for testing purposes. The
StrToSectionCode method does the opposite conversion.
See: About Section Names, Volume 1, Chapter 7, for more details.
fxampIc
The following example shows the syntax of the SectionCodeToStr function:
var
sTmp: string;
begin
sTmp := Crpe1.SectionCodeToStr(3000);
{sTmp will equal 'GH1a'}
end;
VCI Re|etetce 1S6
ScndDctaiICupics mcthud
DccIaratiun
procedure SendDetailCopies;
Dcscriptiun
SendDetailCopies sends the value of the DetailCopies property to the Crystal Reports Print Engine. This
procedure is called automatically when the Execute method is called, provided that the SendOnExecute
property is set to True. It does not normally need to be called in code.
If SendOnExecute is set to False, then all of the information sent from the Crystal component to the Print
Engine must be done manually. This feature is provided for debugging purposes. We recommend that you
leave SendOnExecute to True.
fxampIc
In this example, the DetailCopies settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.SendDetailCopies;
ScndDiaIugParcnt mcthud
DccIaratiun
procedure SendDialogParent;
Dcscriptiun
The SendDialogParent method sends the VCL's DialogParent property settings to the Crystal Reports Print
Engine. This is automatically called during the Execute method (provided that SendOnExecute is set to True),
so does not normally need to be called in code.
fxampIc
In this example, the DialogParent settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.SendDialogParent;
VCI Re|etetce 1S7
ScndDiscardSavcdData mcthud
DccIaratiun
procedure SendDiscardSavedData;
Dcscriptiun
SendDiscardSavedData sends the value of the DiscardSavedData property to the Crystal Reports Print Engine.
This procedure is called automatically when the Execute method is called, provided that the SendOnExecute
property is set to True. It does not normally need to be called in code.
If SendOnExecute is set to False, then all of the information sent from the Crystal component to the Print
Engine must be done manually. This feature is provided for debugging purposes. We recommend that you
leave SendOnExecute to True.
fxampIc
In this example, the DiscardSavedData settings are sent from the Crystal component to the Crystal Reports
Print Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.SendDiscardSavedData;
ScndFicIdMapping mcthud
DccIaratiun
function SendFieldMapping: boolean;
Dcscriptiun
The SendFieldMapping method sends the FieldMapping property settings to the Print Engine. This method is
called internally in the VCL whenever VerifyDatabase is called, therefore it should not be necessary to make
this call directly.
Also, if FieldMapping is set to something other than "fmAuto", and VerifyDatabase is not called directly in
code, VerifyDatabase will be automatically called in the Execute method of the main class (Crpe1.Execute).
VCI Re|etetce 1S8
ScndOutput mcthud
DccIaratiun
procedure SendOutput;
Dcscriptiun
SendOutput sends the value of the Output property to the Crystal Reports Print Engine. This procedure is
called automatically when the Execute method is called, provided that the SendOnExecute property is set to
True. It does not normally need to be called in code.
If SendOnExecute is set to False, then all of the information sent from the Crystal component to the Print
Engine must be done manually. This feature is provided for debugging purposes. We recommend that you
leave SendOnExecute to True.
fxampIc
In this example, the Output settings are sent from the Crystal component to the Crystal Reports Print Engine
DLL. This is normally handled automatically in the Execute method:
Crpe1.SendOutput;
ScndPrugrcssDiaIug mcthud
DccIaratiun
procedure SendProgressDialog;
Dcscriptiun
SendProgressDialog sends the value of the ProgressDialog property to the Crystal Reports Print Engine. This
procedure is called automatically when the Execute method is called, provided that the SendOnExecute
property is set to True. It does not normally need to be called in code.
If SendOnExecute is set to False, then all of the information sent from the Crystal component to the Print
Engine must be done manually. This feature is provided for debugging purposes. We recommend that you
leave SendOnExecute to True.
fxampIc
In this example, the ProgressDialog settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.SendProgressDialog;
VCI Re|etetce 1S0
ScndRcpurtTitIc mcthud
DccIaratiun
procedure SendReportTitle;
Dcscriptiun
SendReportTitle sends the value of the ReportTitle property to the Crystal Reports Print Engine. This
procedure is called automatically when the Execute method is called, provided that the SendOnExecute
property is set to True. It does not normally need to be called in code.
If SendOnExecute is set to False, then all of the information sent from the Crystal component to the Print
Engine must be done manually. This feature is provided for debugging purposes. We recommend that you
leave SendOnExecute to True.
fxampIc
In this example, the ReportTitle settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.SendReportTitle;
SctFucus mcthud
DccIaratiun
procedure SetFocus;
Dcscriptiun
This procedure sets the focus of the Windows desktop to the Crystal Preview Window. Therefore it should
only be called after the Execute method, and can be used in concert with the Focused method.
Normally SetFocus does not need to be called, but if you find that your application Form keeps coming to the
front after the Preview Window opens, then this call can be used to prevent that.
fxampIc
This code example checks to see if the Crystal Preview Window is the topmost window. If not, it makes it the
topmost:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
if not Crpe1.Focused then
Crpe1.SetFocus;
VCI Re|etetce 166
ShuwWinduw mcthud
DccIaratiun
procedure ShowWindow;
Dcscriptiun
The ShowWindow method makes a hidden Preview Window visible again. Use HideWindow to make it
invisible again.
fxampIc
The following example illustrates the ShowWindow method:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.HideWindow;
{...after a while...}
Crpe1.ShowWindow;
StrTuBuuIcan mcthud
DccIaratiun
function StrToBoolean(const sValue: string): boolean;
Dcscriptiun
StrToBoolean is used internally in the Crystal component, but has been exposed for general purpose use. It
takes a string value and returns a corresponding boolean. Using the "True" value as an example, the string
value should be formatted in one of these ways:
'True', 'T', 't','Yes', 'Y', 'y', '1'
bTmp := Crpe1.StrToBoolean('Y');
{bTmp is now set to True}
VCI Re|etetce 161
StrTuDatc mcthud
DccIaratiun
function StrToDate(const sValue: string; var dValue: TDateTime): boolean;
Dcscriptiun
StrToDate is used internally in the Crystal component, but has been exposed for general purpose use. It takes
a Date string value and passes the equivalent DateTime value back into the dValue var parameter.
var
dValue: TDateTime;
begin
if not Crpe1.StrToDate('1999,02,03', dValue) then
ShowMessage('An error occured during conversion');
end;
StrTuDatcTimc mcthud
DccIaratiun
function StrToDateTime(const sValue: string; var dtValue: TDateTime): boolean;
Dcscriptiun
StrToDateTime is used internally in the Crystal component, but has been exposed for general purpose use. It
takes a DateTime string value and passes the equivalent DateTime value back into the dValue var parameter.
var
dtValue: TDateTime;
begin
if not Crpe1.StrToDateTime('1999,02,03 12:22:23', dtValue) then
ShowMessage('An error occured during conversion');
end;
VCI Re|etetce 162
StrTuFIuating mcthud
DccIaratiun
function StrToFloating(const sValue: string): double;
Dcscriptiun
StrToFloating is used internally in the Crystal component, but has been exposed for general purpose use. It
takes a Floating point string value and returns the equivalent Floating point numeric value.
var
str1 : string;
dTmp : double;
begin
str1 := '1.23';
dTmp := Crpe1.StrToFloating(str1);
end;
{dTmp is now: 1.23}
StrTuScctiunCudc mcthud
DccIaratiun
function StrToSectionCode(const Value: string): smallint;
Dcscriptiun
The StrToSectionCode function is used internally in the Crystal component. It takes the Section naming
convention that the component uses (for properties like SectionFormat.Section), and converts it to a Print
Engine Section Code number. It is mainly included as a public function for testing purposes.
See About Section Names, Volume 1, Chapter 7, for more details
fxampIc
The following example shows the syntax of the StrToSectionCode function:
var
nTmp: integer;
begin
nTmp := Crpe1.StrToSectionCode('GH1a');
{nTmp will equal 3000}
end;.
VCI Re|etetce 16!
StrTuTCrBuuIcan mcthud
DccIaratiun
function StrToTCrBoolean(const sValue: string): TCrBoolean;
Dcscriptiun
StrToTCrBoolean is used internally in the Crystal component, but has been exposed for general purpose use.
It takes a string value ('0', '1', '2') representing a TCrBoolean value (cFalse, cTrue, cDefault) and returns the
equivalent TCrBoolean type.
var
sTmp : string;
crBool : TCrBoolean;
begin
sTmp := '0';
str1 := Crpe1.StrToTCrBoolean(Now);
{sTmp is now '-1'}
end;
This numeric string can easily be converted back into a TCrBoolean value by either using the StrToTCrBoolean
function:
crBool := Crpe1.StrToTCrBoolean(sTmp);
{crBool is now cFalse}
...or a line of code similar to this:
crBool := TCrBoolean(StrToInt(sTmp));
StrTuTimc mcthud
DccIaratiun
function StrToTime(const sValue: string; var tValue: TDateTime): boolean;
Dcscriptiun
StrToTime is used internally in the Crystal component, but has been exposed for general purpose use. It takes
a Time string value and passes the equivalent DateTime value back into the "tValue" parameter.
var
sTime : string;
dtTime : TDateTime;
begin
sTime := '12:01:23';
if Crpe1.StrToTime(sTime, dtTime) then
ShowMessage('String converted to Time successfully!');
end;
VCI Re|etetce 164
TCrBuuIcanTuStr mcthud
DccIaratiun
function TCrBooleanToStr(const crbValue: TCrBoolean): string;
Dcscriptiun
TCrBooleanToStr is used internally in the Crystal component, but has been exposed for general purpose use. It
takes a TCrBoolean type value and returns the type formatted as numeric string representing the ordinal value.
var
sTmp : string;
crBool : TCrBoolean;
begin
crBool := cFalse;
sTmp := Crpe1.TCrBooleanToStr(crBool);
{sTmp is now '-1'}
end;
This numeric string can easily be converted back into a TCrBoolean value by either using the StrToTCrBoolean
function:
crBool := Crpe1.StrToTCrBoolean(sTmp);
{crBool is now cFalse}
...or a line of code similar to this:
crBool := TCrBoolean(StrToInt(sTmp));
TimcTuStr mcthud
DccIaratiun
function TimeToStr(const tValue: TDateTime): string;
Dcscriptiun
TimeToStr is used internally in the Crystal component, but has been exposed for general purpose use. It takes
a DateTime value and returns the equivalent Time value formatted as a string.
str1 := Crpe1.TimeToStr(Now);
{str1 now looks something like this: '12:02:31'}
VCI Re|etetce 16S
TruncStr mcthud
DccIaratiun
function TruncStr(sValue: string): string;
Dcscriptiun
TruncStr is used internally in the Crystal component, but has been exposed for general purpose use. It takes a
Floating point value formatted as a string, and removes the floating point values.
str1 := Crpe1.TruncStr('12.34');
{str1 is now '12'}
VcrifyDatabasc mcthud
DccIaratiun
function VerifyDatabase: boolean;
Dcscriptiun
This method requires Seagate Crystal Reports 7.0 or higher. The VerifyDatabase method causes the Crystal
Reports Print Engine to re-read the structure of the database tables used in a Report, and update the Report
accordingly. Since the Report stores the structure information for every table it uses, this should be updated if
the structure (field names, sizes and types) has changed.
This method checks the FieldMapping setting, and if any of the field names have changed, it will cause the
Print Engine to do one of three things, depending on the setting of the FieldMapping property:
1. FieldMapping set to fmAuto
Any fields in the Report that no longer have the same field names will be removed from the Report.
2. FieldMapping set to fmPrompt
If any field names have changed, the Print Engine will show a Mapping Dialog that can be used to map the
fields to fields from the current database table.
3. FieldMapping set to fmEvent
If any field names have changed, an OnFieldMapping event will be triggered. This event is on the events
page of the Object Inspector, and allows the developer to either design their own Mapping Dialog, or
bypass the dialog by doing the mapping in code.
VCI Re|etetce 166
NO7F: 7he aclual sequence ol calls made lo nvoke FeldMang should lollow lhs order:
G Sel lhe ReorlName roerly.
G Sel any IogOn Inlormalon (l usng ODBC or SQI lables) va elher Connecl, IogOnInlo, or
IogOnServer.
G Sel any new 7able localon nlormalon va lhe 7ables objecl.
G Sel lhe FeldMang roerly.
G Call VerlyDalabase.
fxampIc
The following example sets the FieldMapping property and then calls VerifyDatabase. If the Database has
changed, a Field Mapping dialog will appear:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.FieldMapping := fmPrompt;
Crpe1.VerifyDatabase;
fvcnts
The following are the events of the Tcrpe VCL component.
OnError event, Page 166
OnExecuteBegin event, Page 168
OnExecuteDoneSend event, Page 169
OnExecuteEnd event, Page 169
OnFieldMapping event, Page 170
OnGetVersion event, Page 172
OnJobOpened event, Page 173
OnPrintEnded event, Page 174
OnPrinterSend event, Page 175
OnWindowClose event, Page 175
Onfrrur cvcnt
DccIaratiun
property OnError: TCrpeErrorEvent;
Typc
TCrpeErrorEvent = procedure(Sender: TObject; const ErrorNum: smallint; const
ErrorString: string; var IgnoreError: boolean) of object;
VCI Re|etetce 167
Dcscriptiun
The OnError event occurs in two instances:
1. When an error is returned from the Crystal Reports Print Engine. The error can be related to the
functioning of the Print Engine, but more often it is related to invalid values passed in.
2. When an error is generated within the component's internal code. This can be caused by problems
allocating memory, values being passed that are invalid, specifying subscripts that are out-of-range, etc.
There are three ways in which an Error will be handled:
1. There is no OnError Event defined. In this case, the built-in Exception will be raised, showing the default
Error Dialog, with the Error Number and Error String.
2. An OnError Event is defined, but the IgnoreError flag is set to False. In this case, the VCL will raise a
silent Abort exception, but no Error dialog will be shown.
3. An OnError Event is defined, and the IgnoreError flag is set to True. In this case, the VCL will assume that
the Error has been handled in the OnError event, and will proceed program execution, either continuing
to the next iteration of a loop, or continuing to the next procedure (if there are any more to be run). Care
must be taken in suppressing errors which would otherwise indicate a problem.
G The ErrorNum parameter passed in the OnEngineError event contains the number of the current Error,
and the ErrorString parameter contains the Print Engine description of the current Error. These are also
available via the LastErrorNumber and LastErrorString properties.
G The OnError event allows the programmer to handle the errors raised in a way that will suit the
interface of the application. For example, a custom dialog could be built to display the ErrorString
instead of the built-in one.
For a complete list of possible Errors, see: Error Codes - VCL Component, Page 207 or Error Codes - Crystal Reports
Print Engine, Page 210.
fxampIc
This procedure which is placed in the OnError event, causes a user-defined Dialog to appear with two buttons,
one for Cancel, and one for Continue (ignore the error). If Continue is pressed, the IgnoreError flag is set to True:
procedure TForm1.Crpe1Error(const ErrorNum: Smallint; const ErrorString:
string; var IgnoreError: Boolean);
begin
dlgError := TdlgError.Create(Application);
{Dialog Title}
if ErrorNum < 500 then
dlgError.lblTitle.Caption := 'Crystal Reports Component Error'
else
dlgError.lblTitle.Caption := 'Crystal Reports Engine Error';
{Error Number}
if ErrorNum > 0 then
dlgError.lblErrorNumber.Caption := 'Error #: ' + IntToStr(ErrorNum)
else
dlgError.lblErrorNumber.Caption := 'Error Number Undefined';
VCI Re|etetce 168
{Error String}
dlgError.lblErrorString.Caption := ErrorString;
{Show Dialog}
dlgError.ShowModal;
if dlgError.ModalResult = mrOk then
IgnoreError := True;
end;
OnfxccutcBcgin cvcnt
DccIaratiun
property OnExecuteBegin: TCrpeCancelEvent;
Typc
TCrpeCancelEvent = procedure(Sender: TObject; var Cancel: Boolean) of object;
Dcscriptiun
The OnExecuteBegin event takes place at the start of the Execute method, before the Crystal component values
have been sent to the Crystal Reports Print Engine.
See Execute method, Page 142, for a fuller explanation of the order of events.
fxampIc
The following example runs a Report to Window. When the Execute method begins, a message is shown:
procedure TForm1.RunReport;
begin
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
procedure TForm1.Crpe1OnExecuteBegin(Sender: TObject; var Cancel: Boolean);
begin
ShowMessage('Starting Execute');
end;
VCI Re|etetce 160
OnfxccutcDuncScnd cvcnt
DccIaratiun
property OnExecuteDoneSend: TCrpeCancelEvent;
Typc
TCrpeCancelEvent = procedure(Sender: TObject; var Cancel: Boolean) of object;
Dcscriptiun
The OnExecuteDoneSend event takes place within the Execute method, after the Crystal component values
have been sent to the Crystal Reports Print Engine, but before the Report is actually run.
See Execute method, Page 142, for a fuller explanation of the order of events.
fxampIc
The following example runs a Report to Window. When the Execute method has completed sending all the
VCL settings to the Print Engine, a message is shown:
procedure TForm1.RunReport;
begin
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
procedure TForm1.Crpe1OnExecuteDoneSend(Sender: TObject; var Cancel:
Boolean);
begin
ShowMessage('Finished Sending to Print Engine');
end;
Onfxccutcfnd cvcnt
DccIaratiun
property OnExecuteEnd: TNotifyEvent;
Typc
TNotifyEvent = procedure(Sender: TObject) of object;
VCI Re|etetce 176
Dcscriptiun
The OnExecuteEnd event takes place within the Execute method, after the Crystal component values have
been sent to the Crystal Reports Print Engine, and after the Report has been run.
See Execute method, Page 142, for a fuller explanation of the order of events.
fxampIc
The following example runs a Report to Window. When the Execute method has finished running the Report,
a message is shown:
procedure TForm1.RunReport;
begin
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
procedure TForm1.Crpe1OnExecuteEnd(Sender: TObject);
begin
ShowMessage('Report was run successfully');
end;
OnFicIdMapping cvcnt
DccIaratiun
property OnFieldMapping : TCrpeFieldMappingEvent;
Typc
TCrpeFieldMappingEvent = procedure(var ReportFields: TList; var
DatabaseFields: TList; var Cancel: Boolean) of object;
TCrFieldValueType = (fvUnknown, fvInt8s, fvInt8u, fvInt16s, fvInt16u,
fvInt32s, fvInt32u, fvNumber, fvCurrency, fvBoolean, fvDate, fvTime, fvString,
fvTransientMemo, fvPersistentMemo, fvBlob, fvDateTime, fvBitmap, fvIcon,
fvPicture, fvOle, fvGraph);
TCrFieldMappingInfo = class(TPersistent)
public
property TableName : string
property FieldName : string
property FieldType : TCrFieldValueType
property MapTo : integer
end;
VCI Re|etetce 171
Dcscriptiun
The OnFieldMapping event can be used at runtime to handle remapping of Database Fields whose names
have changed since the Report was designed. This event will only be invoked if the FieldMapping property is
set to fmEvent, and the VerifyDatabase method has been called. This event passes two TList objects as
parameters, and a boolean Cancel parameter.
The two TList objects contain TCrFieldMappingInfo classes, one item in the ReportFields list for each database
field used in the Report, and one item in each DatabaseFields list for each database field in the physical table(s).
The MapTo property of the TCrFieldMappingInfo class is used to set which ReportField goes with which
DatabaseField. Any unmapped ReportFields and DatabaseFields have a MapTo value of -1.
See the Example for more details.
NO7F: 7he Cancel arameler s nol workng roerly al lhs lme. 7hs s nol a roblem wlh lhe VCI bul
ralher lhe CRPF32.DII.
fxampIc
The following example shows how to read the Report and Database fields passed in the OnFieldMapping
event. The Table and Field name are attached to the String part of a TStringList, and the Object part of the
TStringList contains a pointer to the original TCrFieldMappingInfo class. This kind of handling makes it easy
to pass the Table.FieldName strings into a ListBox or ComboBox, if you plan to make your own Mapping
Dialog (See the Sample App included with the VCL for a working demonstration of this).
procedure TForm.Crpe1OnFieldMapping(var ReportFields,
DatabaseFields: TList; var Cancel: Boolean);
var
RptFields : TCrFieldMappingInfo;
DBFields : TCrFieldMappingInfo;
slRptFields : TStringList;
slDBFields : TStringList;
cnt : integer;
begin
slRptFields := TStringList.Create;
slDBFields := TStringList.Create;
{Get unmapped ReportFields}
for cnt := 0 to ReportFields.Count - 1 do
begin
RptFields := TCrFieldMappingInfo(ReportFields[cnt]);
if RptFields.MapTo = -1 then
begin
slRptFields.Add(RptFields.TableName + '.' + RptFields.FieldName);
slRptFields.Objects[slRptFields.Count - 1] := ReportFields[cnt];
end;
end;
{Get unmapped DatabaseFields}
for cnt := 0 to DatabaseFields.Count - 1 do
VCI Re|etetce 172
begin
DBFields := TCrFieldMappingInfo(DatabaseFields[cnt]);
if DBFields.MapTo = -1 then
begin
slDBFields.Add(DBFields.TableName + '.' + DBFields.FieldName);
slDBFields.Objects[slDBFields.Count - 1] := DatabaseFields1[cnt];
DBFields.MapTo := cnt;
end;
end;
{When you want to map a ReportField to a DatabaseField, you can simply cast
the StringList Object back into the TCrFieldMappingInfo variable, and then set
the MapTo property}
RptFields := TCrFieldMappingInfo(slRptFields.Objects[x]);
DBFields := TCrFieldMappingInfo(slDBFields.Objects[y]);
{Set the MapTo number to the Database field item number}
RptFields.MapTo := DBFields.MapTo;
{Remember to free the StringLists when done}
slRptFields.Free;
slDBFields.Free;
end;
OnGctVcrsiun cvcnt
DccIaratiun
property OnGetVersion : TCrpeVersionEvent;
Typc
TCrpeVersionEvent = procedure(Sender: TObject; var Major, Minor : integer) of
object;
Dcscriptiun
The OnGetVersion event allows the developer to over-ride the VCL's built-in version check of the
CRPE32.DLL. The VCL does a File Version check on CRPE32.DLL and will not run with anything less than
5.x.x.108 or higher. Normally, over-riding this safety feature would not be a wise thing to do, but we have
come across a few variant versions of CRPE32 that have odd version numbers, so this event can be used to
handle such circumstances.
The two important parameters are the Major and Minor integers. Major refers to the first number sequence in
the File Version, such as 5, 6, or 7. Minor refers to the last number sequence, such as 108, 135, 151, etc. These
can be set as desired, and the VCL will then assume that it is dealing with that particular version of
CRPE32.DLL.
NO7F: Be carelul aboul sellng lhe Major verson loo hgh. Il lhe VCI does nol lnd cerlan rocedures n
CRPF32.DII lhal l execls lo lnd n a arlcular verson, errors wll resull.
VCI Re|etetce 17!
fxampIc
The following example shows how to over-ride the VCL's version check on CRPE32.DLL using the
OnGetVersion event:
procedure TForm.Crpe1OnGetVersion(Sender: TObject; var Major, Minor :
integer);
begin
Major := 5;
Minor := 108;
end;
On|ubOpcncd cvcnt
DccIaratiun
property OnJobOpened: TCrpeJobNumEvent;
Typc
TCrpeJobNumEvent = procedure(Sender: TObject; const JobNum: Word) of object;
Dcscriptiun
The OnJobOpened event occurs when the PrintJob for a Report is opened. The PrintJob is opened when a
Report is loaded into the Crystal Reports Print Engine (CRPE32.DLL). This does not occur initially when the
ReportName property is set, but happens when any call is made that requires the Report to be loaded into the
Print Engine. An example of this type of call would be any of the Retrieve methods, such as
Subreports.Retrieve, ParamFields.Retrieve, etc. It is at this point that the JobNumber property will have a
meaningful value. Note that it is possible to force the PrintJob open by using the OpenJob method.
The event passes the JobNum variable, which is the internal Job Number that the CRPE assigns to the Job, and
which is used as an identifier for all the internal calls made to the CRPE concerning this particular Job. The Job
Number is also available via the component's JobNumber property, but in case the component is being created
dynamically within a procedure and may not be visible outside of it, the Job Number is passed in the event.
The JobNum variable can be used to make direct Print Engine DLL calls, such as are used internally in the
component, although care must be taken not to modify the PrintJob properties in such a way that the
component may not be aware of the changes.
VCI Re|etetce 174
fxampIc
The following example runs a Report to Window. When the Window is closed, the Print Job is also closed:
procedure TForm1.RunReport;
begin
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
procedure TForm1.Crpe1OnJobOpened(const JobNum: Word);
begin
ShowMessage('PrintJob opened successfully');
end;
OnPrintfndcd cvcnt
DccIaratiun
property OnPrintEnded: TNotifyEvent;
Typc
TNotifyEvent = procedure(Sender: TObject) of object;
Dcscriptiun
The OnPrintEnded event takes place within the Execute method, after the Crystal component values have
been sent to the Crystal Reports Print Engine, and after the Report has been run.
See Execute for a fuller explanation of the order of events.
fxampIc
The following example runs a Report to Printer. When the Job is finished, the Print Job is also closed:
procedure TForm1.RunReport;
begin
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Output := toPrinter;
Crpe1.Execute;
end;
procedure TForm1.Crpe1OnPrintEnded(Sender: TObject);
begin
Crpe1.CloseJob;
end;
VCI Re|etetce 17S
OnPrintcrScnd cvcnt
DccIaratiun
property OnPrinterSend: TCrpeCancelEvent;
Typc
TCrpeCancelEvent = procedure(Sender: TObject; var Cancel: Boolean) of object;
Dcscriptiun
The OnPrinterSend event occurs just before the Printer property values are sent to the Crystal Reports Print
Engine. Putting an event here allows the developer a "last chance" to over-ride any Printer DevMode settings
that the VCL may be changing via properties such as Orientation and PreserveRptSettings. This event should
not be required under normal circumstances.
NO7F: Sellng lhe Cancel arameler lo lrue wll cause lhe Prnler.Send lo aborl. Il lhs s done durng lhe
Cre1.Fxecule melhod, execulon ol lhe Reorl wll also slo.
fxampIc
The following example shows how the OnPrinterSend event can be used to over-ride DevMode settings:
procedure TForm.Crpe1OnPrinterSend(Sender: TObject; var Cancel: Boolean);
begin
TCrpe(Sender).Printer.PMode^.dmCopies := 3;
end;
OnWinduwCIusc cvcnt
DccIaratiun
property OnWindowClose : TNotifyEvent;
Typc
TNotifyEvent = procedure(Sender: TObject) of object;
Dcscriptiun
The OnWindowClose event takes place within the Execute method, after the Crystal component values have
been sent to the Crystal Reports Print Engine, and after the Report has been run.
See Execute method, Page 142, for a fuller explanation of the order of events.
VCI Re|etetce 176
fxampIc
The following example runs a Report to Window. When the Window is closed, the Print Job is also closed:
procedure TForm1.RunReport;
begin
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
procedure TForm1.Crpe1OnWindowClose(Sender: TObject);
begin
Crpe1.CloseJob;
end;
Winduwfvcnts
The Window Events consist of 23 events associated with the Crystal Reports Preview Window. These Window
Events are triggered when certain actions take place on the Preview Window and are only enabled if the
WindowEvents property is set to True.
wOnActivateWindow, Page 177
wOnCancelBtnClick, Page 178
wOnCloseBtnClick, Page 178
wOnCloseWindow, Page 179
wOnDeActivateWindow, Page 180
wOnDrillDetail, Page 181
wOnDrillGroup, Page 182
wOnExportBtnClick, Page 184
wOnFirstPageBtnClick, Page 185
wOnGroupTreeBtnClick, Page 185
wOnLastPageBtnClick, Page 186
wOnNextPageBtnClick, Page 187
wOnPreviousPageBtnClick, Page 188
wOnPrintBtnClick, Page 189
wOnPrintSetupBtnClick, Page 190
wOnReadingRecords, Page 191
wOnRefreshBtnClick, Page 192
VCI Re|etetce 177
wOnRightMouseClick, Page 192
wOnSearchBtnClick, Page 195
wOnShowGroup, Page 196
wOnStartEvent, Page 197
wOnStopEvent, Page 198
wOnZoomLevelChange, Page 199
wOnActivatcWinduw
wOnActivateWindow takes place just before the Preview Window becomes active, or receives the focus. This
event passes the following variables:
G WindowHandle - The Handle to the current Preview Window.
G Cancel - A variable that can be set to True to cancel the normal Preview Window response to the Event.
DccIaratiun
property wOnActivateWindow: TCrpeGeneralPrintWindowEvent;
Typc
TCrpeGeneralPrintWindowEvent = procedure(WindowHandle: HWnd; var Cancel:
Boolean) of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnActivateWindow Event:
procedure TForm1.Crpe1wOnActivateWindow(WindowHandle: Integer;
var Cancel: Boolean);
begin
with Memo1.Lines do
begin
Add('wOnActivateWindow Event:');
Add(' - Window was Activated ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add('');
end;
end;
end;
VCI Re|etetce 178
wOnCanccIBtnCIick
wOnCancelBtnClick takes place after the Cancel button on the Preview Window button bar is clicked but
before canceling the printing or reading of the database. This event passes the following variables:
DccIaratiun
property wOnCancelBtnClick: TCrpeGeneralPrintWindowEvent;
Typc
TCrpeGeneralPrintWindowEvent = procedure(WindowHandle: HWnd; var Cancel:
Boolean) of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnCancelBtnClick Event:
procedure TForm1.Crpe1wOnCancelBtnClick(WindowHandle: Integer;
var Cancel: Boolean);
begin
with Memo1.Lines do
begin
Add('wOnCancelBtnClick Event:');
Add(' - Cancel Button clicked ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add('');
end;
end;
wOnCIuscBtnCIick
wOnCloseBtnClick takes place after the Close button on the Preview Window button bar is clicked, but before
the Preview Window is closed. This event passes the following variables:
WindowHandle The Handle to the current Preview Window.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
WindowHandle The Handle to the current Preview Window.
ViewIndex Specifies which View is going to be closed. The View is the current tab on the
Preview Window, which could be the main Preview tab, or one of the open
drill-down tabs. The Preview tab is numbered 0, and the drill-down tabs are
numbered from left to right in order.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
VCI Re|etetce 170
DccIaratiun
property wOnCloseBtnClick: TCrpeCloseButtonClickedEvent;
Typc
TCrpeCloseButtonClickedEvent = procedure(WindowHandle: HWnd; ViewIndex: Word;
var Cancel: Boolean) of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnCloseBtnClick Event:
procedure TForm1.Crpe1wOnCloseBtnClick(WindowHandle: Integer;
ViewIndex: Word; var Cancel: Boolean);
begin
with Memo1.Lines do
begin
Add('wOnCloseBtnClick Event:');
Add(' - Close Button clicked ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add(' - ViewIndex: ' + IntToStr(ViewIndex));
Add('');
end;
end;
wOnCIuscWinduw
wOnCloseWindow takes place just before the Preview Window is closed. This event passes the following
variables:
DccIaratiun
property wOnCloseWindow: TCrpeGeneralPrintWindowEvent;
Typc
TCrpeGeneralPrintWindowEvent = procedure(WindowHandle: HWnd; var Cancel:
Boolean) of object;
WindowHandle The Handle to the current Preview Window.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
VCI Re|etetce 186
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnCloseWindow Event:
procedure TForm1.Crpe1wOnCloseWindow(WindowHandle: Integer;
var Cancel: Boolean);
begin
with Memo1.Lines do
begin
Add('wOnCloseWindow Event:');
Add(' - Window is being Closed ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add('');
end;
end;
wOnDcActivatcWinduw
wOnDeActivateWindow takes place when the Preview Window becomes inactive, or loses focus. This event
passes the following variables:
G WindowHandle - The Handle to the current Preview Window.
G Cancel - A variable that can be set to True to cancel the normal Preview Window response to the Event.
DccIaratiun
property wOnDeActivateWindow: TCrpeGeneralPrintWindowEvent;
Typc
TCrpeGeneralPrintWindowEvent = procedure(WindowHandle: HWnd; var Cancel:
Boolean) of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
VCI Re|etetce 181
fxampIc
The following procedure illustrates the wOnDeActivateWindow Event:
procedure TForm1.Crpe1wOnDeActivateWindow(WindowHandle: Integer;
var Cancel: Boolean);
begin
with Memo1.Lines do
begin
Add('wOnDeActivateWindow Event:');
Add(' - Window was DeActivated ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add('');
end;
end;
wOnDriIIDctaiI
wOnDrillDetail takes place when a Detail area on the Preview Window is double-clicked. Note that
AllowDrillDown must be True on the WindowButtonBar options before the Event will be returned. This event
passes the following variables:
G WindowHandle - The Handle to the current Preview Window.
G NSelectedField - The number of the field that was doubleclicked (if any). This number can be used to
locate the field information in the FieldNames and FieldValues stringlists.
G NFields - The total number of Fields in the Detail area that was drilled on.
G FieldNames - A stringlist containing the Names of all the Fields in the applicable detail area.
G FieldValues - A stringlist containing the actual values of the Fields in the applicable detail area. These
items should correspond to the FieldNames stringlist. For example, NFields can be used to loop
through the stringlists:
for cnt := 0 to (NFields - 1) do
begin
ShowMessage(FieldNames[cnt]);
ShowMessage(FieldValues[cnt]);
end;
G Cancel - A variable that can be set to True to cancel the normal Preview Window response to the Event.
DccIaratiun
property wOnDrillDetail: TCrpeDrillOnDetailEvent;
VCI Re|etetce 182
Typc
TCrpeDrillOnDetailEvent = procedure(WindowHandle: HWnd; NSelectedField,
NFields: smallint; FieldNames, FieldValues: TStringList; var Cancel: Boolean)
of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnDrillDetail Event:
procedure TForm1.Crpe1wOnDrillDetail(WindowHandle: Integer; NSelectedField,
NFields: Smallint; FieldNames, FieldValues: TStringList; var Cancel: Boolean);
var
cnt : integer;
begin
with Memo1.Lines do
begin
Add('wOnDrillDetail Event:');
Add(' - Detail Section was drilled ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add(' - Number of Fields in Details area: ' + IntToStr(NFields));
Add(' - Number of Selected Field: ' + IntToStr(NSelectedField));
Add(' - Field Names: ');
for cnt := 0 to (FieldNames.Count - 1) do
Add(' ' + IntToStr(cnt) + '. ' + FieldNames[cnt]);
Add(' - Field Values: ');
for cnt := 0 to (FieldValues.Count - 1) do
Add(' ' + IntToStr(cnt) + '. ' + FieldValues[cnt]);
Add('');
end;
end;
wOnDriIIGruup
wOnDrillGroup takes place when a Group area on the Preview Window is double-clicked or a GroupTree
node is Ctrl-clicked. Note that AllowDrillDown must be True on the WindowButtonBar options before the
Event will be returned. This event passes the following variables:
G WindowHandle - The Handle to the current Preview Window.
G NGroupLevel - The number of the Group chosen. The outer group starts with number 1, so if you use
NGroupLevel to find the name of the Group in the GroupList, be sure to decrement it by 1.
VCI Re|etetce 18!
G DrillType - The type of drill-down:
ddOnGroup - a Group area on the Report was double-clicked.
ddOnGroupTree - a GroupTree node was Ctrl-clicked.
ddOnGraph - a Graph area was double-clicked.
G GroupList - A stringlist containing the names of the Groups starting from the outer group and going up
to the Group chosen.
G Cancel - A variable that can be set to True to cancel the normal Preview Window response to the Event.
DccIaratiun
property wOnDrillGroup: TCrpeDrillOnGroupEvent;
Typc
TCrpeDrillOnGroupEvent = procedure(WindowHandle: HWnd; NGroupLevel: Word;
DrillType: TCrDrillDownType; GroupList: TStringList; var Cancel: Boolean) of
object;
TCrDrillDownType = (ddOnGroup, ddOnGroupTree, ddOnGraph);
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnDrillGroup Event:
procedure TForm1.Crpe1wOnDrillGroup(WindowHandle: Integer;
NGroupLevel: Word; DrillType: TCrDrillDownType; GroupList: TStringList;
var Cancel: Boolean);
var
cnt: integer;
begin
with Memo1.Lines do
begin
Add('wOnDrillGroup Event:');
Add(' - Group Section was drilled ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
case DrillType of
ddOnGroup : Add(' - DrillDown Type: OnGroup');
ddOnGroupTree : Add(' - DrillDown Type: OnGroupTree');
ddOnGraph : Add(' - DrillDown Type: OnGraph');
end;
VCI Re|etetce 184
Add(' - GroupLevel: ' + IntToStr(NGroupLevel));
Add(' - GroupList: ');
for cnt := 0 to (GroupList.Count - 1) do
Add(' ' + IntToStr(cnt) + '. ' + GroupList[cnt]);
Add('');
end;
end;
wOnfxpurtBtnCIick
wOnExportBtnClick takes place after the Export button on the Preview Window button bar is clicked, but
before the Export process starts. This event passes the following variables:
G WindowHandle - The Handle to the current Preview Window.
G Cancel - A variable that can be set to True to cancel the normal Preview Window response to the Event.
DccIaratiun
property wOnExportBtnClick: TCrpeGeneralPrintWindowEvent;
Typc
TCrpeGeneralPrintWindowEvent = procedure(WindowHandle: HWnd; var Cancel:
Boolean) of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnExportBtnClick Event:
procedure TForm1.Crpe1wOnExportBtnClick(WindowHandle: Integer; var Cancel:
Boolean);
begin
with Memo1.Lines do
begin
Add('wOnExportBtnClick Event:');
Add(' - Export Button clicked ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add('');
end;
end;
VCI Re|etetce 18S
wOnFirstPagcBtnCIick
wOnFirstPageBtnClick takes place after the FirstPage button on the Preview Window button bar is clicked,
but before the Report goes to the first page. This event passes the following variables:
DccIaratiun
property wOnFirstPageBtnClick: TCrpeGeneralPrintWindowEvent;
Typc
TCrpeGeneralPrintWindowEvent = procedure(WindowHandle: HWnd; var Cancel:
Boolean) of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnFirstPageBtnClick Event:
procedure TForm1.Crpe1wOnFirstPageBtnClick(WindowHandle: Integer; var Cancel:
Boolean);
begin
with Memo1.Lines do
begin
Add('wOnFirstPageBtnClick Event:');
Add(' - First Page Button clicked ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add('');
end;
end;
wOnGruupTrccBtnCIick
wOnGroupTreeBtnClick takes place after the GroupTree button on the Preview Window button bar is clicked,
but before showing or hiding the GroupTree. This event passes the following variables:
WindowHandle The Handle to the current Preview Window.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
WindowHandle The Handle to the current Preview Window.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
VCI Re|etetce 186
DccIaratiun
property wOnGroupTreeBtnClick: TCrpeGeneralPrintWindowEvent;
Typc
TCrpeGeneralPrintWindowEvent = procedure(WindowHandle: HWnd; var Cancel:
Boolean) of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnGroupTreeBtnClick Event:
procedure TForm1.Crpe1wOnGroupTreeBtnClick(WindowHandle: Integer; Visible:
Boolean; var Cancel: Boolean);
begin
with Memo1.Lines do
begin
Add('wOnGroupTreeBtnClick Event:');
Add(' - GroupTree Button clicked ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add(' - GroupTree Visible: ' + BooleanToStr(Visible));
Add('');
end;
end;
wOnlastPagcBtnCIick
wOnLastPageBtnClick takes place after the LastPage button on the Preview Window button bar is clicked, but
before going to the last page. This event passes the following variables:
DccIaratiun
property wOnLastPageBtnClick: TCrpeGeneralPrintWindowEvent;
Typc
TCrpeGeneralPrintWindowEvent = procedure(WindowHandle: HWnd; var Cancel:
Boolean) of object;
WindowHandle The Handle to the current Preview Window.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
VCI Re|etetce 187
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnLastPageBtnClick Event:
procedure TForm1.Crpe1wOnLastPageBtnClick(WindowHandle: Integer; var Cancel:
Boolean);
begin
with Memo1.Lines do
begin
Add('wOnLastPageBtnClick Event:');
Add(' - Last Page Button clicked ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add('');
end;
end;
wOnNcxtPagcBtnCIick
wOnNextPageBtnClick takes place after the NextPage button on the Preview Window button bar is clicked,
but before going to the next page. This event passes the following variables:
DccIaratiun
property wOnNextPageBtnClick: TCrpeGeneralPrintWindowEvent;
Typc
TCrpeGeneralPrintWindowEvent = procedure(WindowHandle: HWnd; var Cancel:
Boolean) of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
WindowHandle The Handle to the current Preview Window.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
VCI Re|etetce 188
fxampIc
The following procedure illustrates the wOnNextPageBtnClick Event:
procedure TForm1.Crpe1wOnNextPageBtnClick(WindowHandle: Integer; var Cancel:
Boolean);
begin
with Memo1.Lines do
begin
Add('wOnNextPageBtnClick Event:');
Add(' - Next Page Button clicked ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add('');
end;
end;
wOnPrcviuusPagcBtnCIick
wOnPreviousPageBtnClick takes place after the PreviousPage button on the Preview Window button bar is
clicked, but before going to the previous page. This event passes the following variables:
DccIaratiun
property wOnPreviousPageBtnClick: TCrpeGeneralPrintWindowEvent;
Typc
TCrpeGeneralPrintWindowEvent = procedure(WindowHandle: HWnd; var Cancel:
Boolean) of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnPreviousPageBtnClick Event:
procedure TForm1.Crpe1wOnPreviousPageBtnClick(WindowHandle: Integer; var
Cancel: Boolean);
begin
with Memo1.Lines do
WindowHandle The Handle to the current Preview Window.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
VCI Re|etetce 180
begin
Add('wOnPreviousPageBtnClick Event:');
Add(' - Previous Page Button clicked ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add('');
end;
end;
wOnPrintBtnCIick
wOnPrintBtnClick takes place after the Print button on the Preview Window button bar is clicked, but before
the printing process starts. This event passes the following variables:
DccIaratiun
property wOnPrintBtnClick: TCrpeGeneralPrintWindowEvent;
Typc
TCrpeGeneralPrintWindowEvent = procedure(WindowHandle: HWnd; var Cancel:
Boolean) of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnPrintBtnClick Event:
procedure TForm1.Crpe1wOnPrintBtnClick(WindowHandle: Integer; var Cancel:
Boolean);
begin
with Memo1.Lines do
begin
Add('wOnPrintBtnClick Event:');
Add(' - Print Button clicked ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add('');
end;
end;
WindowHandle The Handle to the current Preview Window.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
VCI Re|etetce 106
wOnPrintSctupBtnCIick
wOnPrintSetupBtnClick takes place after the PrintSetup button on the Preview Window button bar is clicked,
but before showing the Print Setup dialog box. This event passes the following variables:
DccIaratiun
property wOnPrintSetupBtnClick: TCrpeGeneralPrintWindowEvent;
Typc
TCrpeGeneralPrintWindowEvent = procedure(WindowHandle: HWnd; var Cancel:
Boolean) of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnPrintSetupBtnClick Event:
procedure TForm1.Crpe1wOnPrintSetupBtnClick(WindowHandle: Integer; var
Cancel: Boolean);
begin
with Memo1.Lines do
begin
Add('wOnPrintSetupBtnClick Event:');
Add(' - Print Setup Button clicked ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add('');
end;
end;
WindowHandle The Handle to the current Preview Window.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
VCI Re|etetce 101
wOnRcadingRccurds
wOnReadingRecords takes place during a reading of the database or regenerating saved data process. It is
triggered after a specified amount of time, not after reading every Record. This event passes the following
variables:
DccIaratiun
property wOnReadingRecords: TCrpeReadingRecordsEvent;
Typc
TCrpeReadingRecordsEvent = procedure(Cancelled: boolean; RecordsRead:
longint; RecordsSelected: longint; Done: boolean; var Cancel: boolean) of
object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnReadingRecords Event:
procedure TForm1.Crpe1wOnReadingRecords(Cancelled: Boolean; RecordsRead,
RecordsSelected: Integer; Done: Boolean; var Cancel: Boolean);
begin
with Memo1.Lines do
begin
Add('wOnReadingRecords Event:');
Add(' - Reading Records Event triggered ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add(' - Records Read: ' + IntToStr(RecordsRead));
Add(' - Records Selected: ' + IntToStr(RecordsSelected));
Add(' - Cancelled: ' + BooleanToStr(Cancelled));
Add(' - Done: ' + BooleanToStr(Done));
Add('');
end;
end;
Cancelled Indicates whether the reading Records is canceled.
RecordsRead Indicates how many Records have been read so far.
RecordsSelected Indicates how many Records have been selected so far.
Done Indicates whether reading Records is finished.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
VCI Re|etetce 102
wOnRcfrcshBtnCIick
wOnRefreshBtnClick takes place after the Refresh button on the Preview Window button bar is clicked, but
before refreshing the data. This event passes the following variables:
DccIaratiun
property wOnRefreshBtnClick: TCrpeGeneralPrintWindowEvent;
Typc
TCrpeGeneralPrintWindowEvent = procedure(WindowHandle: HWnd; var Cancel:
Boolean) of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnRefreshBtnClick Event:
procedure TForm1.Crpe1wOnRefreshBtnClick(WindowHandle: Integer; var Cancel:
Boolean);
begin
with Memo1.Lines do
begin
Add('wOnRefreshBtnClick Event:');
Add(' - Refresh Button clicked ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add('');
end;
end;
wOnRightMuuscCIick
wOnRightMouseClick takes place when the right Mouse button (or whichever Mouse button is mapped to the
Right click in Windows) is clicked on the Preview Window. This event passes the following variables:
G WindowHandle - The Handle to the current Preview Window.
G MouseInfo - A structure with various items that give information about the Mouse click.
Action - A TCrMouseClickAction value.
Button - A TCrMouseClickType value.
WindowHandle The Handle to the current Preview Window.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
VCI Re|etetce 10!
ShiftKey - True if the Shift key was held down.
ControlKey - True if the Control key was held down.
x,y - The actual mouse co-ordinates.
G FieldValue - The actual value of the database field or label that was clicked on (if any).
G FieldType - A TCrParamFieldType value that defines the data type of the field that was clicked on (if
any).
G Section - The Section name of the Report area that the Mouse was clicked in. This will be in the Crystal
Reports short section-naming convention, as used throughout the VCL.
G ObjectHandle - The handle of the Report object that was clicked on (if any). This number represents the
order of the object in the Crystal Reports design-view page, from top to bottom, left to right.
G Cancel - A variable that can be set to True to cancel the normal Preview Window response to the Event.
DccIaratiun
property wOnRightMouseClick : TCrpeMouseClickEvent;
Typc
TCrpeMouseClickEvent = procedure(WindowHandle: HWnd; MouseInfo: TCrMouseInfo;
FieldValue: string; FieldType: TCrParamFieldType; Section: string;
ObjectHandle: Hwnd; var Cancel: Boolean) of object;
TCrMouseClicction = (mbNotSupported, mbDown, mbUp);
TCrMouseClickType = (mcLeft, mcRight, mcMiddle);
TCrMouseInfo = record
Action : TCrMouseClicction;
Button : TCrMouseClickType;
ShiftKey : Boolean;
ControlKey : Boolean;
x,y : integer;
end;
Rcmarks
The wOnRightMouseClick event is only available with Seagate Crystal Reports 7 or higher.
VCI Re|etetce 104
fxampIc
The following procedure illustrates the wRightMouseClick event:
procedure Crpe1wOnRightMouseClick(WindowHandle: Hwnd; MouseInfo:
TCrMouseInfo; FieldValue: String; FieldType: TCrParamFieldType; Section:
String; ObjectHandle: HWnd; var Cancel: Boolean);
begin
with Memo1.Lines do
begin
Add('wOnRightMouseClick Event:');
case MouseInfo.Button of
mcLeft : Add(' - Button: Left Mouse Click');
mcRight : Add(' - Button: Right Mouse Click');
mcMiddle : Add(' - Button: Middle Mouse Click');
end;
case MouseInfo.Action of
mbNotSupported : Add(' - Action: Not Supported');
mbDown : Add(' - Action: Mouse Button Down');
mbUp : Add(' - Action: Mouse Button Up');
end;
if MouseInfo.ShiftKey = True then
Add(' - ShiftKey: True')
else
Add(' - ShiftKey: False');
if MouseInfo.ControlKey = True then
Add(' - ControlKey: True')
else
Add(' - ControlKey: False');
Add(' - X Coordinate: ' + IntToStr(MouseInfo.x));
Add(' - Y Coordinate: ' + IntToStr(MouseInfo.y));
Add(' - FieldValue: ' + FieldValue);
case Ord(FieldType) of
0 {pfNumber} : Add(' - FieldType: pfNumber');
1 {pfCurrency} : Add(' - FieldType: pfCurrency');
2 {pfBoolean} : Add(' - FieldType: pfBoolean');
3 {pfDate} : Add(' - FieldType: pfDate');
4 {pfString} : Add(' - FieldType: pfString');
5 {pfDateTime} : Add(' - FieldType: pfDateTime');
6 {pfTime} : Add(' - FieldType: pfTime');
7 {pfInteger} : Add(' - FieldType: pfInteger');
8 {pfColor} : Add(' - FieldType: pfColor');
9 {pfChar} : Add(' - FieldType: pfChar');
10{pfLong} : Add(' - FieldType: pfLong');
11{pfNoValue} : Add(' - FieldType: pfNoValue');
end;
VCI Re|etetce 10S
Add(' - Section: ' + Section);
Add(' - ObjectHandle: ' + IntToStr(ObjectHandle));
Add('');
end;
end;
wOnScarchBtnCIick
wOnSearchBtnClick takes place after the Search button on the Preview Window button bar is clicked, but
before the search starts. This event passes the following variables:
DccIaratiun
property wOnSearchBtnClick: TCrpeSearchButtonClickedEvent;
Typc
TCrpeSearchButtonClickedEvent = procedure(WindowHandle: HWnd; SearchString:
string; var Cancel: Boolean) of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnSearchBtnClick Event:
procedure TForm1.Crpe1wOnSearchBtnClick(WindowHandle: Integer; SearchString:
string; var Cancel: Boolean);
begin
with Memo1.Lines do
begin
Add('wOnSearchBtnClick Event:');
Add(' - Search Button clicked ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add(' - Search String: ' + SearchString);
Add('');
end;
03/;
WindowHandle The Handle to the current Preview Window.
SearchString The text that was entered into the Search String field on the Preview
Window.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
VCI Re|etetce 106
wOnShuwGruup
wOnShowGroup takes place after one of the GroupTree nodes is clicked on, but before showing that group.
This event passes the following variables:
DccIaratiun
property wOnShowGroup: TCrpeShowGroupEvent;
Typc
TCrpeShowGroupEvent = procedure(WindowHandle: HWnd; NGroupLevel: Word;
GroupList: TStringList; var Cancel: Boolean) of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnShowGroup Event:
procedure TForm1.Crpe1wOnShowGroup(WindowHandle: Integer; NGroupLevel: Word;
GroupList: TStringList; var Cancel: Boolean);
var
cnt: integer;
begin
with Memo1.Lines do
begin
Add('wOnShowGroup Event:');
Add(' - Group Tree was clicked ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add(' - GroupLevel: ' + IntToStr(NGroupLevel));
Add(' - GroupList: ');
for cnt := 0 to (GroupList.Count - 1) do
Add(' ' + IntToStr(cnt) + '. ' + GroupList[cnt]);
Add('');
end;
end;
WindowHandle The Handle to the current Preview Window.
NGroupLevel The number of the Group chosen. The outer group starts with number 1,
so if you use NGroupLevel to find the name of the Group in the
GroupList, be sure to decrement it by 1.
GroupList A stringlist containing the names of the Groups starting from the outer
group and going up to the Group chosen.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
VCI Re|etetce 107
wOnStartfvcnt
wOnStartEvent takes place before the Report Engine starts a process. A process can be printing to the printer,
exporting, printing to a window, or generating pages when navigating through the Preview Window. This
event passes the following variables:
DccIaratiun
property wOnStartEvent: TCrpeStartEvent;
Typc
TCrpeStartEvent = procedure(Destination: TCrStartEventDestination; var
Cancel: Boolean) of object;
TCrStartEventDestination = (seNoWhere, seToWindow, seToPrinter, seToExport,
seFromQuery);
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnStartEvent Event:
procedure TForm1.Crpe1wOnStartEvent(Destination: TCrStartEventDestination;
var Cancel: Boolean);
begin
with Memo1.Lines do
begin
Add('wOnStartEvent Event:');
Add(' - An Event was Started ');
case Destination of
seNoWhere : Add(' - Destination: seNoWhere');
seToWindow : Add(' - Destination: seToWindow');
seToPrinter : Add(' - Destination: seToPrinter');
seToExport : Add(' - Destination: seToExport');
seFromQuery : Add(' - Destination: seFromQuery');
end;
Add('');
end;
end;
Destination The destination of the current process.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
VCI Re|etetce 108
wOnStupfvcnt
wOnStopEvent takes place whenever a process has finished. This event passes the following variables:
DccIaratiun
property wOnStopEvent: TCrpeStopEvent;
Typc
TCrpeStopEvent = procedure(Destination: TCrStartEventDestination; JobStatus:
TCrStopEventJobStatus; var Cancel: Boolean) of object;
TCrStartEventDestination = (seNoWhere, seToWindow, seToPrinter, seToExport,
seFromQuery);
TCrStopEventJobStatus = (seNotStarted, seInProgress, seCompleted, seFailed,
seCancelled, seHalted);
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
fxampIc
The following procedure illustrates the wOnStopEvent Event:
procedure TForm1.Crpe1wOnStopEvent(Destination: TCrStartEventDestination;
JobStatus: TCrStopEventJobStatus; var Cancel: Boolean);
begin
with Memo1.Lines do
begin
Add('wOnStopEvent Event:');
Add(' - An Event was Stopped ');
case Destination of
seNoWhere : Add(' - Destination: seNoWhere');
seToWindow : Add(' - Destination: seToWindow');
seToPrinter : Add(' - Destination: seToPrinter');
seToExport : Add(' - Destination: seToExport');
seFromQuery : Add(' - Destination: seFromQuery');
end;
Destination The destination of the process.
JobStatus The status of the process.
Cancel A variable that can be set to True to cancel the normal Preview Window
response to the Event.
VCI Re|etetce 100
case JobStatus of
seUndefined : Add(' - JobStatus: seUndefined');
seNotStarted : Add(' - JobStatus: seNotStarted');
seInProgress : Add(' - JobStatus: seInProgress');
seCompleted : Add(' - JobStatus: seCompleted');
seFailed : Add(' - JobStatus: seFailed');
seCancelled : Add(' - JobStatus: seCancelled');
seHalted : Add(' - JobStatus: seHalted');
end;
Add('');
end;
end;
wOnZuumlcvcIChangc
wOnZoomLevelChange takes place after the zoom setting is changed via the drop-down Zoom Level combo
box on the button bar of the Preview Window, but before the Preview Zoom Level is actually changed. This
event passes the following variables:
G WindowHandle - The Handle to the current Preview Window.
G ZoomLevel - This value can be a value from 25 to 400, indicating a magnification percentage, or it can be
one of the following constants:
1 - Page Width
2 - Whole Page
G Cancel - A variable that can be set to True to cancel the normal Preview Window response to the Event.
DccIaratiun
property wOnZoomLevelChange : TCrpeZoomLevelChangingEvent;
Typc
TCrpeZoomLevelChangingEvent = procedure(WindowHandle: HWnd; ZoomLevel: Word;
var Cancel: Boolean) of object;
Rcmarks
You must be using Crystal 6.0 or higher to use Window Events.
VCI Re|etetce 266
fxampIc
The following procedure illustrates the wOnZoomLevelChange Event:
procedure TForm1.Crpe1wOnZoomLevelChange(WindowHandle: Integer;
ZoomLevel: Word; var Cancel: Boolean);
begin
with Memo1.Lines do
begin
Add('wOnZoomLevelChange Event:');
Add(' - Zoom Level was changed ');
Add(' - WindowHandle: ' + IntToStr(WindowHandle));
Add(' - Zoom Level: ' + IntToStr(ZoomLevel));
Add('');
end;
end;
Typcs
fnumcratcd Typcs / SpcciaI-lcngth Typcs
GcncraI
fxpurt
TCrReportName = string[255];
TCrBoolean = (cFalse, cTrue, cDefault);
TCrOutput = (toWindow, toPrinter, toExport);
TCrState = (crsSetup, crsInit);
TCrError = (errVCL, errEngine);
TCrColumnWidth = (ByArea, ByConstant);
TCrExportAppName = string;
TCrExportFileName = string[255];
TCrExportType = (Records, TabSeparated, Ascii, Dif, Csv, CharacterSeparated,
TabSeparatedText, CrystalReportRPT, Excel2, Excel3, Excel4,
LotusWK1, LotusWK3, LotusWKS, RTF, WordForWindows, Excel5,
HTML30, HTML32ext, HTML32std, ODBCTable, PaginatedText,
Excel5Extended, ReportDefinition);
VCI Re|etetce 261
FicIdMapping
FurmuIas
Graph
Margins
TCrExportDestination = (toFile, toEmailViaMapi, toEmailViaVIM, toMSExchange, to
Application);
TCrFieldCharSeparator = string[1];
TCrFieldDelimiter = string[PE_FIELDDELIMLEN]; {16}
TCrFieldMappingInfo
public
property TableName :
property FieldName :
property FieldType :
property MapTo :
end;
= class(TPersistent)
string
string
TCrFieldValueType
integer
TCrFieldMappingType = (fmAuto, fmPrompt, fmEvent)
TCrFieldValueType = (fvUnknown, fvInt8s, fvInt8u, fvInt16s, fvInt16u, fvInt32s, fvInt32u,
fvNumber, fvCurrency, fvBoolean, fvDate, fvTime, fvString,
fvTransientMemo, fvPersistentMemo, fvBlob, fvDateTime, fvBitmap,
fvIcon, fvPicture, fvOle, fvGraph);
TCrAreaFormatFormula = (afSuppress, afHide, afNewPageBefore, afNewPageAfter,
afKeepTogether, afResetPageNAfter, afPrintAtBottomOfPage);
TCrSectionFormatFormula = (sfSuppress, sfPrintAtBottomOfPage, sfNewPageBefore,
sfNewPageAfter, sfResetPageNAfter, sfKeepTogether,
sfSuppressBlankSection, sfUnderlaySection, sfBackgroundColor);
TCrBarDirection = (bdHorizontal, bdVertical, bdDefault);
TCrGraphDirection = (Rows, Cols, RowCol, ColRow, Unknown);
TCrGraphType = (SideBySide, ThreeDSide, StackedBar, ThreeDStacked, PercentBar,
ThreeDPercent, Line, Area, ThreeDBars, Pie, MultiplePie,
WeightedPie, UserDefined, UnknownGraph);
TCrGraphTextType = string[128];
TCrMarginTwips = -2..PE_SM_DEFAULT; {32768}
VCI Re|etetce 262
ParamFicIds
Printcr/PrintOptiuns
RcpurtOptiuns
ScctiunFunt
Surt/Gruup
TCrParamFieldName = string[255];
TCrParamFieldReportName = string[128];
TCrParamFieldSource = (psReport, psStoredProc, psQuery);
TCrParamFieldType = (pfNumber, pfCurrency, pfBoolean, pfDate, pfString), pfDateTime,
pfTime, pfInteger, pfColor, pfChar, pfLong, pfNoValue);
TCrParamInfoValueType = (vtRanges, vtDiscrete);
TCrRangeBounds = (IncludeStartAndEnd, IncludeStartOnly, IncludeEndOnly,
ExcludeStartAndEnd);
TCrPrinterDevice = class Driver, Device, Port : string;
TCrPrinterName = string[80];
TCrCollation = (Uncollated, Collated, DefaultCollation);
TCrOrientation = (orDefault, orPortrait, orLandscape);
TCrPreserveRptSet = (prOrientation, prPaperSize, prPaperSource);
TCrPreserveRptSettings = set of TCrPreserveRptSet
TCrPrintFileName = string;
TCrDateTimeType = (dtConvertToString, dtConvertToDate, dtKeepAsDateTime,
dtDefault);
TCrFontCharSet = (fcAnsi, fcDefault, fcSymbol, fcShiftJis, fcHangeul, fcChineseBig5,
fcOEM);
TCrFontFamily = (ffDefault, ffRoman, ffSwiss, ffModern, ffScript, ffDecorative);
TCrFontScope = (fsFields, fsText, fsBoth);
TCrFontWeight = (fwDefault, fwThin, fwExtraLight, fwLight, fwNormal,
fwMedium, fwSemiBold, fwBold, fwExtraBold, fwHeavy);
TCrSortDirection = (sdDescending, sdAscending, sdDefault);
TCrGroupType = (gtOther, gtDate, gtBoolean);
TCrGroupDirection = (gdDescending, gdAscending, gdOriginal, gdSpecified,
gdDefault);
VCI Re|etetce 26!
SQl
Summarylnfu
TabIcs
Winduw
Winduw Cursur
Winduw fvcnts
TCrGroupCondition = (AnyChange, dateDaily, dateWeekly, dateBiWeekly,
dateSemiMonthly, dateMonthly, dateQuarterly, dateSemiAnnually,
dateAnnually, boolToYes, boolToNo, boolEveryYes, boolEveryNo,
boolNextIsYes, boolNextIsNo);
TCrTopNOptions = (tnUnsorted, tnSorted, tnTopN, tnBottomN, tnDefault);
TCrConnectMethod = (useConnect, useLogOnInfo);
TCrStoredProcParamName = string[128];
TCrStoredProcParamType = (spLongVarChar, spBinary, spVarBinary, spLongVarBinary,
spBigInt, spTinyInt, spBit, spChar, spNumeric, spDecimal, spInteger,
spSmallInt, spFloat, spReal, spDouble, spDate, spTime,
spTimeStamp, spVarChar);
TCrSummaryString = string[128];
TCrTableType = (ttUnknown, ttStandard, ttSQL, ttStoredProcedure);
TCrFormBorderStyle = bsNone..bsDialog;
TCrZoomMagnification = -1..400;
TCrZoomPreview = (pwNormal, pwPageWidth, pwWholePage, pwDefault);
TCrWindowCursor = (wcDefault, wcArrow, wcCross, wcIBeam, wcUpArrow, wcSizeAll,
wcSizeNWSE, wcSizeNESW, wcSizeWE, wcSizeNS, wcNo, wcWait,
wcAppStart, wcHelp, wcMagnify);
TCrDrillDownType = (ddOnGroup, ddOnGroupTree, ddOnGraph, ddOnMap,
ddOnSubreport);
TCrMouseClickAction = (mbNotSupported, mbDown, mbUp);
TCrMouseClickType = (mcLeft, mcRight, mcMiddle);
VCI Re|etetce 264
fvcnt Typcs
TCrMouseInfo
Action:
Button:
ShiftKey:
ControlKey:
x, y:
end;
= record
TCrMouseClickAction;
TCrMouseClickType;
Boolean;
Boolean;
integer;
TCrStartEventDestination = (seNoWhere, seToWindow, seToPrinter, seToExport,
seFromQuery);
TCrStopEventJobStatus = (seUndefined, seNotStarted, seInProgress, seCompleted, seFailed,
seCancelled, seHalted);
TCrpeCancelEvent = procedure(Sender: TObject; var Cancel: Boolean) of object;
TCrpeCloseButtonClickedEvent = procedure(WindowHandle: HWnd; ViewIndex: Word; var
Cancel: Boolean) of object;
TCrpeDrillOnDetailEvent = procedure(WindowHandle: HWnd; NSelectedField: smallint;
NFields: smallint; FieldNames: TStringList; FieldValues:
TStringList; var Cancel: Boolean) of object;
TCrpeDrillOnGroupEvent = procedure(WindowHandle: HWnd; NGroupLevel: Word;
DrillType: TCrDrillDownType; GroupList: TStringList; var
Cancel: Boolean) of object;
TCrpeErrorEvent = procedure(const ErrorNum: smallint; const ErrorString:
string; var IgnoreError: Boolean) of object;
TCrpeGeneralPrintWindowEvent = procedure(WindowHandle: HWnd; var Cancel: Boolean) of
object;
TCrpeGroupTreeButtonClickedEvent = procedure(WindowHandle: HWnd; Visible: Boolean; var
Cancel: Boolean) of object;
TCrpeNotifyEvent = procedure(Sender: TObject; var Cancel: Boolean) of object;
TCrpeNotifyEvent2 = procedure(Sender: TObject) of object;
TCrpeNotifyEvent3 = procedure(const JobNum: Word) of object;
TCrpeReadingRecordsEvent = procedure(Cancelled: Boolean; RecordsRead: LongInt;
RecordsSelected: LongInt; Done: Boolean; var Cancel: Boolean)
of object;
TCrpeSearchButtonClickedEvent = procedure(WindowHandle: HWnd; SearchString: string; var
Cancel: Boolean) of object;
TCrpeShowGroupEvent = procedure(WindowHandle: HWnd; NGroupLevel: Word;
GroupList: TStringList; var Cancel: Boolean) of object;
VCI Re|etetce 26S
Custum Prupcrty FicId Typcs
TCrpeStartEvent = procedure(Destination: TCrStartEventDestination; var Cancel:
Boolean) of object;
TCrpeStopEvent = procedure(Destination: TCrStartEventDestination; JobStatus:
TCrStopEventJobStatus; var Cancel: Boolean) of object;
TCrpeZoomLevelChangingEvent = procedure(WindowHandle: HWnd; ZoomLevel: Word; var
Cancel: Boolean) of object;
TCrAreaFormatSection = string;
TCrAreaFormatFormulasSection = string;
TCrExportAppName = string;
TCrExportFileName = string[255];
TCrExpressionName = string;
TCrFormulaName = string;
TCrGraphDataNumber = integer;
TCrGraphOptionsNumber = integer;
TCrGraphTextNumber = integer;
TCrGraphNumber = integer;
TCrGroupConditionNumber = integer;
TCrGroupOptionsNumber = integer;
TCrGroupSortFieldsNumber = integer;
TCrLogOnInfoTable = integer;
TCrParamFieldName = string[255];
TCrRangeNumber = integer;
TCrReportName = string[255];
TCrSectionFontSection = string;
TCrSectionFormatSection = string;
TCrSectionFormatFormulasSection = string;
TCrSectionHeightSection = string;
TCrSessionInfoTable = integer;
TCrSortFieldsNumber = integer;
TCrStoredProcParamName = string[128];
TCrSubreportName = string;
TCrTableNumber = integer;
TCrWinControl = TWinControl;
VCI Re|etetce 266
Cunstants
fmpty String
CrEmptyStr = 'EmptyStr';
DctaiICupics
TCRPE_DEFAULT_DETAILCOPIES = 1;
fxpurt
TCRPE_DEFAULT_LINESPERPAGE = 60;
TCRPE_DEFAULT_USERPTDATEFMT = True;
TCRPE_DEFAULT_USERPTNUMBERFMT = True;
PE_FIELDDELIMLEN = 16;
Margins
PE_SM_DEFAULT = $8000; {32768 in decimal}
PrintOptiuns
TCRPE_DEFAULT_PRINTERCOPIES = 1;
TCRPE_DEFAULT_STARTPAGE = 0;
TCRPE_DEFAULT_STOPPAGE = 0;
Scctiun
clNoColor = -1; {or $FFFFFFFF}
clUnchangedColor = -2;
VCI Re|etetce 267
frrur Cudcs - VCl Cumpuncnt
The Seagate Crystal Reports Component generates the following error codes when necessary:
General, Page 207
Graphs, Page 208
GroupCondition/GroupOptions, Page 208
GroupSortFields, Page 208
LogOnInfo, Page 208
Parameter Fields, Page 208
Printer, Page 208
Sections, Page 209
SessionInfo, Page 209
SortFields, Page 209
SQL Params, Page 209
Subreports, Page 209
SummaryInfo, Page 209
Tables, Page 210
Window, Page 210
GcncraI
100 Unable to open CRPE32.DLL
102 Incompatible Crystal version
104 Error loading function from CRPE32.DLL
106 Error Allocating Memory for Report Info Structure
108 Error DeAllocating Memory for Report Info Structure
110 Error Allocating Memory for Internal Variables
112 No report name assigned
114 Report not found
116 Subscript out of range
118 Error adding item; Item currently exists
130 Error Allocating Memory in Error Handler
140 Undefined PrintEngine Error
VCI Re|etetce 268
Graphs
GruupCunditiun/GruupOptiuns
GruupSurtFicIds
lugOnlnfu
Paramctcr FicIds
Printcr
380 Error in GraphType: Invalid chart number
382 Error in GraphOptions: Invalid chart number
384 Error in GraphText: Invalid chart number
386 Error in GraphData: Invalid chart number
388 Error in GraphData: Invalid Bar Direction
350 Error in GroupCondition: Too many groups specified
352 Error in GroupOptions: Too many groups specified
354 Error in GroupCondition/GroupOptions: GroupType and Condition do not match
340 Error in GroupSortFields: Invalid Number
342 Error in GroupSortFields: Invalid Direction
250 Error in LogOnInfo: table number invalid
290 Error in ParamFields: Parameter name not found in report
292 Error in ParamFields: Number value is not properly formatted
294 Error in ParamFields: Date value is not properly formatted: YYYY,MM,DD
296 Error in ParamFields: Boolean value not properly formatted: True/False
170 Error: Printer Name has not been set
175 Error getting Printer Information
VCI Re|etetce 260
Scctiuns
Scssiunlnfu
SurtFicIds
SQl Params
Subrcpurts
Summarylnfu
360 Error in Section Value: Invalid Section Code or String
362 Error setting SectionAsCode: Value must be greater than 0
364 Formula is not available for PH/PF Section:
366 Formula is not available for PH/PF(or RH/RF) Section:
368 Error in Color
370 Error in SectionMinHeight: Invalid height value
260 Error in SessionInfo: Invalid Table Number
330 Error in SortFields: Invalid Number
332 Error in SortFields: Invalid Direction
270 Error in Params: Param name not found in report
280 Error converting Value to Date
282 Error converting Value to DateTime
200 Subreport name not found. Use "Add" to add a subreport name, or "Retrieve" to obtain
the subreport names from the report
205 Cannot delete subreports[0]; this is the main report
210 Error: Subreport name not found in report
400 Error in SummaryInfo: Comments cannot be greater than 512 characters
VCI Re|etetce 216
TabIcs
Winduw
frrur Cudcs - CrystaI Rcpurts Print fnginc
The Crystal Report Engine DLL generates the following error codes when necessary:
320 Error in Tables Property: Table Number too large
322 Error setting Table Location: Could not find Alias Name
150 Invalid Magnification Value. Use -1 for Default, 0,1,2 for ZoomPreview constants, or 25-
400 for Zoom values
155 Invalid WindowSize: Value must not be less than -1 (default)
500 There is not enough memory available to complete the call or an incorrect ODBC handle
was specified.
501 You have specified a job number that does not exist.
502 You have specified a handle that does not exist.
503 The string you are calling with PEGetHandleString is too long for the buffer allocated. If
returned by other routines, it means that the string does not end with a null byte.
504 You have specified a report that does not exist in the path.
505 You have made the PEStartPrintJob call without first specifying a print destination.
506 You have tried to set an Nth file name and the file number you specified is out of the
existing range. 0<= fileN < N files.
507 There is an error in the file name you specified.
508 The field number you specified is out of the existing range. 0<=fieldN<= N fields.
509 The program can not add the field name you specified.
510 The program can not add the formula name you specified.
511 Sort direction must be either PE_SF_DESCENDING or PE_SF_ASCENDING. You have
specified a sort direction other than those allowed.
512 The report engine must be open in order for the call to be successful. Your code is
lacking a PEOpenEngine call.
513 The printer driver for the printer you specified is missing or there is no default printer
installed.
514 The name you have specified for the export file currently exists. You must delete the file
and export again or specify a different file.
VCI Re|etetce 211
515 There is a formula error in the replacement formula text. Review the formula syntax and
retry. This also returns the formula name and a formula message indicating the source
of the error.
516 The group section you specified is now invalid in the report. A group is based on a
formula field and the formula has changed so it is no longer suitable for basing a group
on.
517 Only one application can access the Report Engine at one time. There is currently
another application using the engine.
518 You have given a bad value as the section code for some function like
PESetGroupCondition.
519 There is no print window available to make your call successful (for any call that
depends on a print window currently existing: PEGetWindowHandle, PECloseWindow,
PEPrintWindow).
520 You are trying to start a print job that has already been started. This can happen if you
start a print job and then try to start printing again before the previous printing has
finished.
521 The summary field specified as a group sort field is invalid or non-existent.
522 There are not enough Windows system resources to process the function.
523 You have specified an invalid group condition.
524 You tried to initiate printing while Seagate Crystal Reports was currently printing a job.
525 There is something wrong with the report you are trying to open.
526 You have not specified a default printer. Specify a default printer via the Windows
Control Panel.
527 Unable to connect to the server or unable to successfully run the SQL query. Some of the
most common reasons for the error to occur are:
G Database Driver DLLs can not be found.
G LogOnInfo Parameters are not NULL terminated.
G Incorrect Logon Parameters. Ensure that the ServerName, DatabaseName, UserId,
and Password are all valid for the server that you are trying to logon to.
G Incorrect structSize given for LogOnInfo Structure. If an incorrect value is given
here, an SQL server error may result. The correct value for the structSize is 514.
G Incorrect SQL Query or the query generated an ODBC error or server error.
528 You have specified an invalid line number.
529 When printing to file or when sorting, the program requires more room than is available
on the disk.
530 In trying to print to file, the program is encountering another file problem besides disk
full.
531 You have specified an incorrect password.
532 The database DLL is corrupt.
VCI Re|etetce 212
533 Something is wrong with the database you have specified. You may need to verify using
the Database|Verify Database command.
534 The database DLL is corrupt, missing or out of date.
535 You have attempted to log on using incomplete or incorrect session parameters.
536 You have attempted to log on using incomplete or incorrect log on parameters.
537 The table you have specified can not be found.
538 The structure size of the structure parameter has not been set correctly.
539 You have specified an invalid date using the PESetPrintDate function.
540 The DLL required by your export call is either missing or out of date. This error can also
be caused by an invalid export options parameter.
541 An export DLL has reported an error.
542 You are using the previous page control in the print window when you are currently at
the first page of the report.
543 You are using the next page control in the print window when you are currently at the
last page of the report.
544 Access to report file denied. Another program or user may be using it. If an OLE-based
report is currently open in CRW and you are trying to open it via CRPE, the call will fail.
545 The user clicked the cancel button.
546 The program can not open the report (which includes an OLE 2.0 object) because OLE
2.0 can not be loaded.
547 You have specified an invalid row or column field in your Cross-Tab report.
548 You are trying to run a Cross-Tab report without specifying a summarized field.
549 You have called PEDecodeExportOptions before first calling PEGetExportOptions.
550 You have used an invalid page number with PEShowNthPage.
552 Returned by PESetNthParam when there is no table in the current report that is based
on a stored procedure.
553 The parameter you have specified does not exist in the stored procedure, or the value
you have entered is not valid for the specified parameter.
554 The graph specified for the section does not exist.
555 The graph type you have indicated with PESetGraphType is not valid.
556 Returned by PESetGraphData if:
G the report is a Cross-Tab, and colGroupN or rowGroupN is > 1, or
G the report is not a Cross-Tab, and rowGroupN is something other than
PE_GRAPH_DATA_NULL_SELECTION or colGroupN+1.
557 Returned by PESetGraphData if the report is not a Cross-Tab, and colGroupN differs
from the graph's current value for colGroupN.
558 Returned by PESetGraphText. The graph text structure PEGraphTextInfo contains an
invalid entry.
VCI Re|etetce 21!
559 Returned by PESetGraphOptions. The graph options structure, PEGraphOptions
contains an invalid entry.
560 Returned by PESetMinimumSectionHeight. The section height specified is either
negative or 0; it must be a value greater than 0.
561 Returned by PESetNthParameterField. The valueType specified in the
PEParameterFieldInfo structure is invalid for a parameter field. It must be one of the
following: number, currency, Boolean, date, or string.
562 Returned by PEOpenSubreport. The subreport name passed does not exist.
564 Returned by PESetDialogParentWindow. The parent window handle specified is
invalid.
565 Returned by PEZoomPreviewWindow. The zoom factor passed in the level parameter is
invalid. It must be 0, 1, 2 >= 25, <= 400, or one of the defined constants.
567 Returned if the total length of the page header and page footer is greater than the length
allotted for a page.
568 Returned if GDI memory gets down to 10%. The program will give this message rather
than GPF.
570 Returned when the user passes in an invalid group number. This can happen, for
example, when the user passes an invalid group number to PEAddGroup.
572 Returned when the user passes in a negative value where a value greater than zero
should be passed. This can happen, for example, when the user passes a negative
section height to PESetMinimumSectionHeight.
573 Returned when the user passes in an invalid pointer, for example, an invalid structure
pointer, an invalid string pointer, etc.
594 Returned when the user passes in an invalid parameter field number, for example,
when the user passes an invalid parameter field number to PESetNthParameterField.
599 Returned when the user passes invalid information to PELogonServer, or
PELogOffServer. This can happen, for example, if the user does not specify the server
name.
999 Internal error.
VCI Re|etetce 214
Sub-CIass Prupcrtics and Mcthuds
ArcaFurmat Prupcrtics
ArcaFurmat Hidc prupcrty
DccIaratiun
property Hide: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
Hide determines if the specified Area will show or not. A hidden section is still available for drill-down in the
Preview Window (provided that the drill-down options are turned on in the WindowButtonBar object). To
suppress an Area so that it is not available for drill-down, use the Suppress property.
fxampIc
The code below retrieves the AreaFormat settings from the Report, then loops through looking for the Details
area, and sets the Hide option for that area:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormat.Retrieve;
for cnt := 0 to (Crpe1.AreaFormat.Count - 1) do
begin
{Look for Details area}
if Crpe1.AreaFormat[cnt].Section = 'D' then
Crpe1.AreaFormat[cnt].Hide := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
VCI Re|etetce 21S
ArcaFurmat ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeAreaFormat;
Dcscriptiun
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 various items stored in the AreaFormat 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: AreaFormat[2] is the
same as AreaFormat.Item[2].
Item returns a reference to itself, so the AreaFormat properties can be used right after the subscript:
AreaFormat[2].Hide := True;
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\MyReport.rpt';
Crpe1.AreaFormat.Retrieve;
{Set AreaFormat to the 3rd area}
Crpe1.AreaFormat.Item[2];
Crpe1.ReportName := 'C:\MyReport.rpt';
Crpe1.AreaFormat.Retrieve;
{Set AreaFormat to the 3rd area}
Crpe1.AreaFormat[2];
ArcaFurmat ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current AreaFormat item number, or
set the AreaFormat object to another item.
VCI Re|etetce 216
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 (AreaFormat[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the AreaFormat object is
pointing to the first AreaFormat item:
if Crpe1.AreaFormat.ItemIndex <> 0 then
Crpe1.AreaFormat[0];
ArcaFurmat kccpTugcthcr prupcrty
DccIaratiun
property KeepTogether: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
KeepTogether determines whether an Area which is printing fields from the same Record will be split on a Page
Break or not. For example, if a Details area has fields placed on 4 horizontal lines, setting KeepTogether to cTrue
will ensure that those fields will not be split when a Page Break occurs, by moving them all to the new page.
NO7F: 7he AreaFormal Kee7ogelher roerly s nol lhe same as Cryslal Reorls KeeGrou7ogelher
olon, whch kees a Grou lrom slllng on a Page Break, and whch s avalable va lhe Kee7ogelher
roerly ol lhe GrouOlons objecl.
fxampIc
The code below retrieves the AreaFormat settings from the Report, then loops through looking for the Details
area, and sets the KeepTogether option for that area:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormat.Retrieve;
for cnt := 0 to (Crpe1.AreaFormat.Count - 1) do
VCI Re|etetce 217
begin
{Look for Details area}
if Crpe1.AreaFormat[cnt].Section = 'D' then
Crpe1.AreaFormat[cnt].KeepTogether := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ArcaFurmat NcwPagcAftcr prupcrty
DccIaratiun
property NewPageAfter: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
NewPageAfter determines if a Page Break will occur after the specified Area.
fxampIc
The code below retrieves the AreaFormat settings from the Report, then loops through looking for the Details
area, and sets the NewPageAfter option for that area:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormat.Retrieve;
for cnt := 0 to (Crpe1.AreaFormat.Count - 1) do
begin
{Look for Details area}
if Crpe1.AreaFormat[cnt].Section = 'D' then
Crpe1.AreaFormat[cnt].NewPageAfter := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
VCI Re|etetce 218
ArcaFurmat NcwPagcBcfurc prupcrty
DccIaratiun
property NewPageBefore: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
NewPageBefore determines if a Page Break will occur before the specified Area.
fxampIc
The code below retrieves the AreaFormat settings from the Report, then loops through looking for the Details
area, and sets the NewPageBefore option for that area:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormat.Retrieve;
for cnt := 0 to (Crpe1.AreaFormat.Count - 1) do
begin
{Look for Details area}
if Crpe1.AreaFormat[cnt].Section = 'D' then
Crpe1.AreaFormat[cnt].NewPageBefore := cDefault;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ArcaFurmat PrintAtButtumOfPagc prupcrty
DccIaratiun
property PrintAtBottomOfPage: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
VCI Re|etetce 210
Dcscriptiun
PrintAtBottomOfPage determines if the specified Area will appear at the bottom of the page when the Report
is run.
fxampIc
The code below retrieves the AreaFormat settings from the Report, then loops through looking for the Details
area, and sets the PrintAtBottomOfPage option for that area:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormat.Retrieve;
for cnt := 0 to (Crpe1.AreaFormat.Count - 1) do
begin
{Look for Details area}
if Crpe1.AreaFormat[cnt].Section = 'D' then
Crpe1.AreaFormat[cnt].PrintAtBottomOfPage := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ArcaFurmat RcsctPagcNAftcr prupcrty
DccIaratiun
property ResetPageNAfter: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
ResetPageNAfter determines if the Page Number will be reset back to 1 after the specified Area.
VCI Re|etetce 226
fxampIc
The code below retrieves the AreaFormat settings from the Report, then loops through looking for the Details
area, and sets the ResetPageNAfter option for that area:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormat.Retrieve;
for cnt := 0 to (Crpe1.AreaFormat.Count - 1) do
begin
{Look for Details area}
if Crpe1.AreaFormat[cnt].Section = 'D' then
Crpe1.AreaFormat[cnt].ResetPageNAfter := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ArcaFurmat Scctiun prupcrty
DccIaratiun
property Section: TCrAreaFormatSection;
Typc
TCrAreaFormatSection = string;
Dcscriptiun
The Section property contains the Section name of the item that the AreaFormat object is currently pointed to.
It's primary use is as a look-up property to point the AreaFormat object to the item with the Section specified.
The default array property, Item, however, provides an easier way to navigate through the object.
If the Retrieve method is used, the Section name of each AreaFormat item is automatically filled when the
AreaFormat information is retrieved.
The Section name syntax is the same as the Short Section Names used in the Crystal Reports Designer:
RH - Report Header
PH - Page Header
GH - Group Header
D - Details
GF - Group Footer
PF - Page Footer
RF - Report Footer
Numbers are used to designate different Groups: GH1, GF2, etc. See g for more details on the syntax.
VCI Re|etetce 221
NO7F: Whereas objecls such as SeclonFormal and SeclonFormalFormulas work on seclc ndvdual sub-
seclons, such as Delals "a", Delals "b", elc., AreaFormal and AreaFormalFormulas work on cerlan areas,
lor examle, Delals area. 7he olons sel n lhese objecls allecl all lhe sub-seclons ol lhal Area as a unl.
fxampIc
The code below retrieves the AreaFormat settings from the Report, then loops through looking for the Details
area, and sets various options for that area:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormat.Retrieve;
for cnt := 0 to (Crpe1.AreaFormat.Count - 1) do
begin
{Look for Details area}
if Crpe1.AreaFormat[cnt].Section = 'D' then
begin
Crpe1.AreaFormat[cnt].Hide := cFalse;
Crpe1.AreaFormat[cnt].KeepTogether := cTrue;
Crpe1.AreaFormat[cnt].NewPageAfter := cDefault;
Crpe1.AreaFormat[cnt].NewPageBefore := cDefault;
Crpe1.AreaFormat[cnt].PrintAtBottomOfPage := cFalse;
Crpe1.AreaFormat[cnt].ResetPageNAfter := cTrue;
Crpe1.AreaFormat[cnt].Suppress := cFalse;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ArcaFurmat ScctiunAsCudc prupcrty
DccIaratiun
property SectionAsCode: smallint;
Dcscriptiun
The SectionAsCode property can be used to read and write the Section property via Print Engine Section Code
numbers. Since the Print Engine Section Codes are numeric, it is easier to apply conditional formatting to
certain sections (in a For loop for example) based on mathematical calculations on the Section Code number
than it is by parsing out the regular Section Code string (GH1, etc.).
VCI Re|etetce 222
fxampIc
The SectionAsCode property can be used to apply formatting to specific sections based on mathematical
calculations or comparisons. The following code checks each section to see if it is a Group section greater than
1, such as GH2, GH3, etc., and if it is, the Area is suppressed:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormat.Retrieve;
for cnt := 0 to (Crpe1.AreaFormat.Count - 1) do
begin
if (Crpe1.AreaFormat[cnt].SectionAsCode mod 1000 > 0)
then
Crpe1.AreaFormat[cnt].Suppress := cTrue;
end;
Crpe1.Execute;
The logic behind the math expression is based on the fact that each group-area increments the Section Code
number by 1 (from 0 to 24 are the possible numbers). So, since 3000 is the general Section Code start number
for a Group Header, and is therefore the number to represent GroupHeader 1, 3001 represents GroupHeader
2, 3002 represents GroupHeader 3, etc. Dividing by 1000 will only give a remainder for those Groups that are
greater than 1.
ArcaFurmat Supprcss prupcrty
DccIaratiun
property Suppress: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
Suppress determines if the specified Area will show or not. A suppressed section is not available for drill-
down in the Preview Window (the drill-down options are specified in the WindowButtonBar object). To hide
an Area so that it is still available for drill-down, use the Hide property.
VCI Re|etetce 22!
fxampIc
The code below retrieves the AreaFormat settings from the Report, then loops through looking for the Details
area, and sets the Suppress option for that area:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormat.Retrieve;
for cnt := 0 to (Crpe1.AreaFormat.Count - 1) do
begin
{Look for Details area}
if Crpe1.AreaFormat[cnt].Section = 'D' then
Crpe1.AreaFormat[cnt].Suppress := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ArcaFurmat Mcthuds
ArcaFurmat Add mcthud
DccIaratiun
procedure Add(SectionName: TCrAreaFormatSection);
Typc
TCrAreaFormatSection = string;
Dcscriptiun
The Add method adds an item to the AreaFormat object and sets the internal index to that item. It requires a
Section name as a parameter, which should be a name corresponding to a Section in the Report. Sections are
named using the Short Section Name convention used in Crystal Reports. See About Section Names, Volume 1,
Chapter 7, for more information. If the Add method is used, the steps to using AreaFormat are:
1 Add an item to the AreaFormat object (you must specify the Section name).
2 Fill the item's properties (KeepTogether, Suppress, etc.) with values.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
Seclon names are correcl lor lhe currenl Reorl.
VCI Re|etetce 224
fxampIc
The Add method can be used to manually add an item to the AreaFormat object, instead of using Retrieve:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Section Name - must be same as in Report}
Crpe1.AreaFormat.Add('D');
Crpe1.AreaFormat.KeepTogether := cTrue;
Crpe1.Output := toWindow;
Crpe1.Execute;
ArcaFurmat CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the AreaFormat 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 is only applied to the AreaFormat object of the current Report/Subreport specified in the Subreports
object. Therefore, to clear all the AreaFormat of all the Subreports will require a looping procedure that goes
through each Subreport and applies the Clear.
fxampIc
This code clears the AreaFormat properties for the main Report (assuming the default state of Subreports[0]):
Crpe1.AreaFormat.Clear;
This code clears the AreaFormat properties for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.AreaFormat.Clear;
end;
VCI Re|etetce 22S
ArcaFurmat CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeAreaFormat): boolean;
Dcscriptiun
The CopyFrom method copies the AreaFormat property values from another TCrpeAreaFormat object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the AreaFormat property values to a temporary TCrpeAreaFormat object:
var
tempAreaFormat : TCrpeAreaFormat;
begin
tempAreaFormat := TCrpeAreaFormat.Create;
tempAreaFormat.CopyFrom(Crpe1.Version);
{...later, when finished with the temp object...}
tempAreaFormat.Free;
end;
ArcaFurmat Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the AreaFormat object. It is handy
for setting up loops to make similar changes to each item.
fxampIc
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.AreaFormat.Retrieve;
for cnt := 0 to (Crpe1.AreaFormat.Count - 1) do
Crpe1.AreaFormat[cnt].KeepTogether := cTrue;
end;
VCI Re|etetce 226
ArcaFurmat Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the AreaFormat object, and does not
need to be called in code.
Arca Furmat DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the AreaFormat object. The "nIndex" parameter
represents the number of the item in the AreaFormat object.
fxampIc
The Delete method can be used to manually remove an item from the AreaFormat object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Section Name - must be same as in Report}
Crpe1.AreaFormat.Add('D');
Crpe1.AreaFormat.KeepTogether := cTrue;
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.AreaFormat.Delete(0);
ArcaFurmat Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
VCI Re|etetce 227
ArcaFurmat Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the AreaFormat information from the Report and stores it in the AreaFormat
object. If no AreaFormat information was found, the call returns False. Be aware that calling Retrieve will first
cause the AreaFormat object to be cleared, so any current information stored in it will be removed.
NO7F: Snce lhe AreaFormal objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe
AreaFormal lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl
lo oblan lhe AreaFormal nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle
lhrough lhe Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale AreaFormal
nlormalon lor each Subreorl (see Fxamle).
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormat.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.AreaFormat.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
VCI Re|etetce 228
ArcaFurmat ScctiunTypc mcthud
DccIaratiun
function SectionType: string;
Dcscriptiun
The SectionType method returns the Section Code without the subsection specifier. In other words, if the
Section Code for an item is GH1, the SectionType method would return GH; if the SectionCode is Da, the
SectionType method would return D.
The primary use for this method is to apply changes to all the Sections in an area, regardless of the sub-section
specifier. See the Example for an illustration.
NO7F: Snce AreaFormal already works on an "area" ralher lhan "seclon" bass, lhs melhod s ol lmled use.
Il can be used wlh lhe Grou areas, however, snce l wll gnore Grou numbers, and n lhs way, lormallng
can be aled lo all lhe Grous.
fxampIc
The following example uses the SectionType method to apply conditional formatting. The formatting is to
apply to all Group areas, so the SectionType method can be used in an expression to apply the changes:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormat.Retrieve;
for cnt := 0 to (Crpe1.AreaFormat.Count - 1) do
begin
{if the SectionType is Group Header, apply the change}
if (Crpe1.AreaFormat[cnt].SectionType = 'GH') then
Crpe1.AreaFormat[cnt].Hide := cTrue;
end;
end;
ArcaFurmat Scnd mcthud
DccIaratiun
function Send: boolean;
VCI Re|etetce 220
Dcscriptiun
The Send method sends the AreaFormat 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.
fxampIc
In this example, the AreaFormat settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.AreaFormat.Send;
ArcaFurmatFurmuIas Prupcrtics
ArcaFurmatFurmuIas FurmuIa prupcrty
DccIaratiun
property Formula: TCrpeString;
Typc
TCrpeString = class(TStringList)
Dcscriptiun
The Formula property specifies the actual AreaFormat Formula text. Any values in the AreaFormat Formula
that must be seen as strings should be put in double quotes, for example:
Crpe1.AreaFormatFormulas.Formula.Text := '{company.STATE} = "CA"';
Before setting the Formula property, be sure the AreaFormatFormulas 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.
VCI Re|etetce 2!6
fxampIc
This example retrieves the AreaFormatFormula information, then assigns a Suppress formula to the Details
area, so that the Details area will be suppressed if the State is California:
Crpe1.ReportName := 'Company.rpt';
Crpe1.AreaFormatFormulas.Retrieve;
{Set AreaFormatFormulas to the Details area}
Crpe1.AreaFormatFormulas.Section = 'D';
{Set the Details item to the Suppress formula}
Crpe1.AreaFormatFormulas.Name := afSuppress;
{Assigning the new formula}
Crpe1.AreaFormatFormulas[cnt].Formula.Assign('{company.STATE} = "CA"');
Crpe1.Output := toWindow;
Crpe1.Execute;
ArcaFurmatFurmuIas ltcm prupcrty
DccIaratiun
property Item[nIndex: integer]: TCrpeAreaFormatFormulas
Dcscriptiun
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 AreaFormatFormulas 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:
AreaFormatFormulas[2] is the same as AreaFormatFormulas.Item[2].
Item returns a reference to itself, so the AreaFormatFormulas properties can be used right after the subscript:
AreaFormatFormulas[2].Section := GH;
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormatFormulas.Retrieve;
{Set AreaFormatFormulas object to the 2nd item}
Crpe1.AreaFormatFormulas.Item[1];
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormatFormulas.Retrieve;
{Set AreaFormatFormulas object to the 2nd item}
Crpe1.AreaFormatFormulas[1];
VCI Re|etetce 2!1
ArcaFurmatFurmuIas ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current AreaFormatFormulas item
number, or set the AreaFormatFormulas 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 (AreaFormatFormulas[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the AreaFormatFormulas object
is pointing to the first AreaFormatFormulas item:
if Crpe1.AreaFormatFormulas.ItemIndex <> 0 then
Crpe1.AreaFormatFormulas[0];
ArcaFurmatFurmuIas Namc prupcrty
DccIaratiun
property Name: TCrAreaFormatFormula;
Typc
TCrAreaFormatFormula = (afSuppress, afHide, afNewPageBefore, afNewPageAfter,
afKeepTogether, afResetPageNAfter, afPrintAtBottomOfPage);
Dcscriptiun
The Name property specifies which formula name the AreaFormatFormulas 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.
VCI Re|etetce 2!2
The Retrieve method will obtain the applicable Formula names for each Area Section in the Report.
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 AreaFormatFormulas object.
The Names available in a given Area 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 AreaFormatFormulas object.
fxpIanatiun
After Retrieve has been called the AreaFormatFormulas object contains an item for each Area Section in the
Report, and each of these Section items contains an item for each Formula Name available to that Area. To
locate a given Formula for a given Area Section, the first step is to navigate the AreaFormatFormulas object to
the Section item:
Crpe1.AreaFormatFormulas.Section := 'D';
{or}
{assuming Details is the 4th Section}
Crpe1.AreaFormatFormulas[4];
And then navigate the Section to the Formula Name item:
Crpe1.AreaFormatFormulas.Name := afSuppress;
{or}
Crpe1.AreaFormatFormulas.Names[0];
The arrangement of Areas and Formulas could be illustrated like this:
Seclon lems Names lems
RH afSuppress
afHide
afNewPageAfter
afKeepTogether
afKeepTogether
afResetPageNAfter
afPrintAtBottomOfPage
PH afSuppress
afResetPageNAfter
GH1 afSuppress
afHide
afNewPageBefore
VCI Re|etetce 2!!
limitatiuns
Since some AreaFormat Formula options are not available for certain Sections, it is not wise to assume that each
AreaFormatFormula item will have 7 Formulas associated with it. On the contrary, it could have anywhere from
2 to 7 Formulas. For the Main Report, Page Headers (PH) and Page Footers (PF) have only 2 available options.
The following chart lists the Sections that have limitations, and which options can have formulas:
x = available
o = not available
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.
fxampIc
This example retrieves the AreaFormatFormula information, then assigns a Suppress formula to the Details
area, so that the Details area will be suppressed if the State is California:
Crpe1.ReportName := 'Company.rpt';
Crpe1.AreaFormatFormulas.Retrieve;
{Loop through the Areas}
for cnt := 0 to (Crpe1.AreaFormatFormulas.Count - 1) do
begin
afNewPageAfter
afKeepTogether
afResetPageNAfter
afPrintAtBottomOfPage
Formula Names RH RF PH PF
afSuppress x x x x
afHide x x o o
afNewPageBefore o x o o
afNewPageAfter x o o o
afKeepTogether x x o o
afResetPageNAfter x x x x
afPrintAtBottomOfPage x x o o
Seclon lems Names lems
VCI Re|etetce 2!4
{Check for Details area}
if Crpe1.AreaFormatFormulas[cnt].Section = 'D' then
begin
{Choose the Suppress formula}
Crpe1.AreaFormatFormulas[cnt].Name := afSuppress;
{Clear it from any previous formula}
Crpe1.AreaFormatFormulas[cnt].Formula.Clear;
{Add the new formula}
Crpe1.AreaFormatFormulas[cnt].Formula.Add('{company.STATE} = "CA"');
Break;
end;
end;
Crpe1.Execute;
ArcaFurmatFurmuIas Namclndcx Prupcrty
DccIaratiun
property NameIndex: integer
Dcscriptiun
The NameIndex property is a run-time only property which can be used to obtain the current Formula Name
item number, or set the Formula Name list to another item.
Cumparisun uf Prupcrtics fur Scctiun ltcms and Namc ltcms
The AreaFormatFormulas object contains an internal Index which determines which Area item it is currently
looking at. This index is changed via the Section, Item, and ItemIndex properties, and can be read via the
IndexOf method.
Likewise, since each Area contains numerous Formula Name items, these are controlled via a secondary
internal Index which is changed via the Name, Names, and NameIndex properties, and can be read via the
IndexOfName method.
Seclons Names
Section Name
Item Names
ItemIndex NameIndex
IndexOf IndexOfName
Count NameCount
VCI Re|etetce 2!S
fxampIc
This example checks the NameIndex of the Formula names list and sets it to the first item if it is not currently
pointing to that item:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormatFormulas.Retrieve;
if Crpe1.AreaFormatFormulas[0].NameIndex <> 0 then
Crpe1.AreaFormatFormulas[0].NameIndex := 0;
ArcaFurmatFurmuIas Namcs Prupcrty
DccIaratiun
property Names[nIndex: integer]: TCrAreaFormatFormula
Typc
TCrAreaFormatFormula = (afHide, afSuppress, afPrintAtBottomOfPage,
afNewPageBefore, afNewPageAfter, afResetPageNAfter, afKeepTogether);
Dcscriptiun
The Names property can be used to step through the Formula Name items of an AreaFormatFormulas item
by numerical subscript. It is useful in looping constructs, to gather all the Formula Names that apply to a
particular Section. In this case, it should be used along with the NameCount method, to avoid a "Subscript out
of bounds" error.
Comparison of Properties for Section Items and Name Items:
G The AreaFormatFormulas object contains an internal Index which determines which Area item it is
currently looking at. This index is changed via the Section, Item, and ItemIndex properties, and can be
read via the IndexOf method.
G Likewise, since each Area contains numerous Formula Name items, these are controlled via a secondary
internal Index which is changed via the Name, Names, and NameIndex properties, and can be read via
the IndexOfName method.
AreaFormatFormulas Section property:
Seclons Names
Section Name
Item Names
ItemIndex NameIndex
IndexOf IndexOfName
Count NameCount
VCI Re|etetce 2!6
DccIaratiun
property Section: TCrAreaFormatFormulasSection;
Typc
TCrAreaFormatFormulasSection = string;
Dcscriptiun
The Section property specifies the Section name that the AreaFormatFormulas object is currently pointed to.
The property acts as a look-up, to point the AreaFormatFormulas object to the item with the Section specified.
If the Retrieve method is used, the Section property is automatically filled when the AreaFormatFormulas are
retrieved. The IndexOf method can be used to locate an AreaFormatFormula item with a specific Section name.
The Section name syntax is the same as the Short Section Names used in the Crystal Reports Designer:
RH - Report Header
PH - Page Header
GH - Group Header
D - Details
GF - Group Footer
PF - Page Footer
RF - Report Footer
Numbers are used to designate different Groups: GH1, GF2, etc. See About Section Names, Volume 1, Chapter 7,
for more details on the syntax.
NO7F: Whereas objecls such as SeclonFormal and SeclonFormalFormulas work on seclc ndvdual sub-
seclons, such as Delals "a", Delals "b", elc., AreaFormal and AreaFormalFormulas work on cerlan areas,
lor examle, Delals area. 7he olons sel n lhese objecls allecl all lhe sub-seclons ol lhal Area as a unl.
fxampIc
This example retrieves the AreaFormatFormula information, then assigns a Suppress formula to the Details
area, so that the Details area will be suppressed if the State is California:
Crpe1.ReportName := 'Company.rpt';
Crpe1.AreaFormatFormulas.Retrieve;
{Loop through the Areas}
for cnt := 0 to (Crpe1.AreaFormatFormulas.Count - 1) do
begin
{Check for Details area}
if Crpe1.AreaFormatFormulas[cnt].Section = 'D' then
begin
{Choose the Suppress formula}
Crpe1.AreaFormatFormulas[cnt].Name := afSuppress;
{Clear it from any previous formula}
Crpe1.AreaFormatFormulas[cnt].Formula.Clear;
VCI Re|etetce 2!7
{Add the new formula}
Crpe1.AreaFormatFormulas[cnt].Formula.Add('{company.STATE} = "CA"');
Break;
end;
end;
Crpe1.Execute;
ArcaFurmatFurmuIas ScctiunAsCudc prupcrty
DccIaratiun
property SectionAsCode: smallint
Dcscriptiun
The SectionAsCode property can be used to read and write the Section property via Print Engine Section Code
numbers. Since the Print Engine Section Codes are numeric, it is easier to apply conditional formatting to
certain sections (in a For loop for example) based on mathematical calculations on the Section Code number
than it is by parsing out the regular Section Code string (GH1, etc.).
See also: About Section Names, Volume 1, Chapter 7.
fxampIc
The SectionAsCode property can be used to apply formula-based formatting to specific sections based on
mathematical calculations or comparisons. The following code checks each section to see if it is a Group section
greater than 1, such as GH2, GH3, etc., and if it is, the Area is suppressed conditionally:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormatFormulas.Retrieve;
for cnt := 0 to (Crpe1.AreaFormatFormulas.Count - 1) do
begin
if (Crpe1.AreaFormatFormulas[cnt].SectionAsCode mod 1000 > 0) then
begin
Crpe1.AreaFormatFormulas[cnt].Name := afSuppress;
Crpe1.AreaFormatFormulas[cnt].Formula.Text := '{company.STATE} = "CA"';
end;
end;
Crpe1.Execute;
The logic behind the math expression is based on the fact that each group-area increments the Section Code
number by 1 (from 0 to 24 are the possible numbers). So, since 3000 is the general Section Code start number
for a Group Header, and is therefore the number to represent GroupHeader 1, 3001 represents GroupHeader
2, 3002 represents GroupHeader 3, etc. Dividing by 1000 will only give a remainder for those Groups that are
greater than 1.
VCI Re|etetce 2!8
ArcaFurmatFurmuIas Mcthuds
ArcaFurmatFurmuIas Add mcthud
DccIaratiun
procedure Add(SectionName: TCrAreaFormatFormulasSection);
Typc
TCrAreaFormatFormulasSection = string;
Dcscriptiun
The Add method adds an item to the AreaFormatFormulas object and sets the internal index to that item. It
requires a Section name as a parameter, which should be a name corresponding to a Section in the Report. Sections
are named using the Short Section Name convention used in Crystal Reports (see About Section Names, Volume 1,
Chapter 7, for more information). If the Add method is used, the steps to using AreaFormatFormulas are:
1 Add an item to the AreaFormatFormulas object (you must specify the Section name).
2 Specify values for the properties (Name, Formula, etc.).
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
Seclon names are correcl lor lhe currenl Reorl.
fxampIc
The Add method can be used to manually add an item to the AreaFormatFormulas object, instead of using
Retrieve:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Section Name - must be same as in Report}
Crpe1.AreaFormatFormulas.Add('PH');
Crpe1.AreaFormatFormulas.Name := afSuppress;
Crpe1.AreaFormatFormulas.Formula.Text := 'True';
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 2!0
ArcaFurmatFurmuIas Chcck mcthud
DccIaratiun
function Check: boolean;
Dcscriptiun
The Check method can be used to check the syntax of an AreaFormatFormula before running the Report.
Check returns a boolean value:
True - AreaFormatFormula is good.
False - AreaFormatFormula has an error.
NO7F: Check s nol workng roerly al lhs lme (l always relurns 7rue).
fxampIc
The Check method does not work properly for AreaFormatFormulas at this time.
ArcaFurmatFurmuIas CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the AreaFormatFormulas 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 is only applied to the AreaFormatFormulas object of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the AreaFormatFormulas of all the Subreports will require a looping
procedure that goes through each Subreport and applies the Clear.
fxampIc
This code clears the AreaFormatFormulas properties for the main Report (assuming the default state of
Subreports[0]):
Crpe1.AreaFormatFormulas.Clear;
VCI Re|etetce 246
This code clears the AreaFormatFormulas for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.AreaFormatFormulas.Clear;
end;
ArcaFurmatFurmuIas CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeAreaFormatFormulas): boolean;
Dcscriptiun
The CopyFrom method copies the AreaFormatFormulas property values from another
TCrpeAreaFormatFormulas object. It is similar to Delphi's Assign method. It is useful for transferring or
temporary storage of values.
fxampIc
The following example copies all the AreaFormatFormulas property values to a temporary
TCrpeAreaFormatFormulas object:
var
tempAreaFormatFormulas : TCrpeAreaFormatFormulas;
begin
tempAreaFormatFormulas := TCrpeAreaFormatFormulas.Create;
tempAreaFormatFormulas.CopyFrom(Crpe1.AreaFormatFormulas);
{...later, when finished with the temp object...}
tempAreaFormatFormulas.Free;
end;
ArcaFurmatFurmuIas Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the AreaFormatFormulas object. It
is handy for setting up loops to make similar changes to each item.
VCI Re|etetce 241
fxampIc
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.AreaFormatFormulas.Retrieve;
for cnt := 0 to (Crpe1.AreaFormatFormulas.Count - 1) do
begin
Crpe1.AreaFormatFormulas[cnt].Name := afKeepTogether;
Crpe1.AreaFormatFormulas[cnt].Formula.Text := 'True';
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ArcaFurmatFurmuIas Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create constructor creates the AreaFormatFormulas object. It is used internally in the VCL component to
create the AreaFormatFormulas object when the component is created, and should not be called outside of the
component.
ArcaFurmatFurmuIas DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the AreaFormatFormulas object. The "nIndex"
parameter represents the number of the item in the AreaFormatFormulas object.
VCI Re|etetce 242
fxampIc
The Delete method can be used to manually remove an item from the AreaFormatFormulas object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Section Name - must be same as in Report}
Crpe1.AreaFormatFormulas.Add('PH');
Crpe1.AreaFormatFormulas.Name := afSuppress;
Crpe1.AreaFormatFormulas.Formula.Text := 'True';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.AreaFormatFormulas.Delete(0);
ArcaFurmatFurmuIas Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method frees the AreaFormatFormulas object. It is used internally in the VCL component to
destroy the AreaFormatFormulas object when the component is destroyed, and should not be called outside
of the component.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
ArcaFurmatFurmuIas lndcxOf mcthud
DccIaratiun
function IndexOf(SectionName: TCrAreaFormatFormulasSection): integer;
Typc
TCrAreaFormatFormulasSection = string;
Dcscriptiun
The IndexOf method takes a Section name and returns the index position of the Section item in the current
AreaFormatFormulas object.
VCI Re|etetce 24!
After the Retrieve method has been called, the AreaFormatFormulas object contains one item for each Area in
the Report. This could be illustrated like so (the Section items in your Reports may not be the same):
Section items:
RH
PH
GH1
GH2
D
GF2
GF1
PF
RF
The IndexOf method can be used to determine if a given Section Name actually exists in the
AreaFormatFormulas object before trying to access it.
fxampIc
The following code illustrates the use of the IndexOf method to locate a specific AreaFormatFormula item by
it's Area name:
var
nItem: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormatFormulas.Retrieve;
{Find Details area}
nItem := Crpe1.AreaFormatFormulas.IndexOf('D');
{If it exists...}
if nItem > -1 then
begin
with Crpe1.AreaFormatFormulas[nItem] do
begin
{Suppress area if STATE is California}
Name := afSuppress;
Formula.Text := '{company.STATE} = "CA"';
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
VCI Re|etetce 244
ArcaFurmatFurmuIas lndcxOfNamc mcthud
DccIaratiun
function IndexOfName(FormulaName: TCrAreaFormatFormula): integer;
Typc
TCrAreaFormatFormula = (afSuppress, afHide, afNewPageBefore, afNewPageAfter,
afKeepTogether, afResetPageNAfter, afPrintAtBottomOfPage);
Dcscriptiun
The IndexOfName method takes an AreaFormatFormula name and returns the index position of the Formula
item in the current Area item of the AreaFormatFormulas object. See the explanation of the Name property for
more details.
Comparison of Properties for Section Items and Name Items:
The AreaFormatFormulas object contains an internal Index which determines which Area item it is currently
looking at. This index is changed via the Section, Item, and ItemIndex properties, and can be read via the
IndexOf method.
Likewise, since each Area contains numerous Formula Name items, these are controlled via a secondary
internal Index which is changed via the Name, Names, and NameIndex properties, and can be read via the
IndexOfName method.

fxampIc
This example uses the IndexOfName method to update a ListBox of Formula Names for the Details Area:
var
nItem: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormatFormulas.Retrieve;
{Set AreaFormatFormulas object to Details item}
Crpe1.AreaFormatFormulas.Section := 'D';
Sections Names
Section Name
Item Names
ItemIndex NameIndex
IndexOf IndexOfName
Count NameCount
VCI Re|etetce 24S
{Loop through and get formula names}
for cnt := 0 to (Crpe1.AreaFormatFormulas.NameCount - 1) do
begin
case Ord(Crpe1.AreaFormatFormulas.Names[cnt]) of
0: ListBox1.Items.Add('Suppress');
1: ListBox1.Items.Add('Hide');
2: ListBox1.Items.Add('NewPageBefore');
3: ListBox1.Items.Add('NewPageAfter');
4: ListBox1.Items.Add('KeepTogether');
5: ListBox1.Items.Add('ResetPageNAfter');
6: ListBox1.Items.Add('PrintAtBottomOfPage');
end;
end;
{Set Formulas Index to NewPageBefore}
Crpe1.AreaFormatFormulas.Name := afNewPageBefore;
{Get Index number}
nItem := Crpe1.AreaFormatFormulas.IndexOfName(afNewPageBefore);
{Update ListBox with Index}
ListBox1.ItemIndex := nItem;
ArcaFurmatFurmuIas NamcCuunt mcthud
DccIaratiun
function NameCount: integer;
Dcscriptiun
The NameCount property returns the number of Formula Names available for a specific Section. NameCount
can be used with the Names property in a looping construct, to step through the Formula Name items.
Comparison of Properties for Section Items and Name Items:
The AreaFormatFormulas object contains an internal Index which determines which Area item it is currently
looking at. This index is changed via the Section, Item, and ItemIndex properties, and can be read via the
IndexOf method.
Likewise, since each Area contains numerous Formula Name items, these are controlled via a secondary
internal Index which is changed via the Name, Names, and NameIndex properties, and can be read via the
IndexOfName method.

Sections Names
Section Name
Item Names
ItemIndex NameIndex
IndexOf IndexOfName
Count NameCount
VCI Re|etetce 246
fxampIc
The NameCount method is used in the example below, to loop through the Formula items for the Page Header
section, sending the Formula names to a ListBox:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormatFormulas.Retrieve;
Crpe1.AreaFormatFormulas.Section := 'PH';
for cnt := 0 to (Crpe1.AreaFormatFormulas.NameCount - 1) do
begin
case Ord(Crpe1.AreaFormatFormulas.Names[cnt]) of
0: ListBox1.Items.Add('afHide');
1: ListBox1.Items.Add('afSuppress');
2: ListBox1.Items.Add('afPrintAtBottomOfPage');
3: ListBox1.Items.Add('afNewPageBefore');
4: ListBox1.Items.Add('afNewPageAfter');
5: ListBox1.Items.Add('afResetPageNAfter');
6: ListBox1.Items.Add('afKeepTogether');
end;
end;
end;
ArcaFurmatFurmuIas Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the AreaFormatFormulas from the Report and stores them in the
AreaFormatFormulas object. If AreaFormatFormulas information was not found, the call returns False. Be
aware that calling Retrieve will first cause the AreaFormatFormulas object to be cleared, so any current
information stored in it will be removed.
NO7F: Snce lhe AreaFormalFormulas objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe
AreaFormalFormulas lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il
you wanl lo oblan lhe AreaFormalFormulas nlormalon lor lhe man Reorl and all ol lhe Subreorls, you
wll have lo sle lhrough lhe Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale
AreaFormalFormulas nlormalon lor each Subreorl (see Fxamle).
VCI Re|etetce 247
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormatFormulas.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.AreaFormatFormulas.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
ArcaFurmatFurmuIas ScctiunTypc mcthud
DccIaratiun
function SectionType: string;
Dcscriptiun
The SectionType method returns the Section Code without the subsection specifier. In other words, if the
Section Code for an item is GH1, the SectionType method would return GH.
This method can be used to apply formatting to all the Groups in a Report regardless of their level number.
See the Example for an illustration.
fxampIc
The following example uses the SectionType method to apply conditional formatting. The formatting is to
apply to all Group Header areas, so the SectionType method can be used in an expression to apply the changes:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormatFormulas.Retrieve;
VCI Re|etetce 248
for cnt := 0 to (Crpe1.AreaFormatFormulas.Count - 1) do
begin
{if the SectionType is Group Header, apply the change}
if (Crpe1.AreaFormatFormulas[cnt].SectionType = 'GH') then
begin
Crpe1.AreaFormatFormulas[cnt].Name := afHide;
Crpe1.AreaFormatFormulas[cnt].Formula.Text := '{company.STATE} = "CA"';
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ArcaFurmatFurmuIas Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the AreaFormatFormulas 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.
We strongly recommend 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.
fxampIc
In this example, the AreaFormatFormulas settings are sent from the Crystal component to the Crystal Reports
Print Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.AreaFormatFormulas.Send;
Cunncct Prupcrtics
Cunncct DatabascNamc prupcrty
DccIaratiun
property DatabaseName: string;
Dcscriptiun
This property contains the name of the Database being connected to. Most SQL Servers require this parameter
(Oracle is usually an exception to the rule).
VCI Re|etetce 240
NO7F: Wlh Cryslals runlme engne, l s ossble lo change lhe dalabase name or alh lhal an ODBC
Dalasource s onlng lo, wlhoul havng lo reconlgure lhe Dalasource manually. See CRWDC lor lhe lull
exlanalon and examles.
When usng an ODBC Dalasource lhal goes lo a PC-lye dalabase (dBase, FoxPro, Paradox, elc.), where lhe
Dalasource onls lo a dreclory, nol an aclual lable, lhe DalabaseName roerly cannol be used lo change
lhe name ol lhe dalabase beng used by lhe Reorl. Use lhe 7ables objecl nslead.
fxampIc
The following example sets the Connect properties and tests the connection before running the Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Connect.ServerName := 'WBSQLServer';
Crpe1.Connect.UserID := 'Elmer Fudd';
Crpe1.Connect.Password := 'Wabbit';
Crpe1.Connect.DatabaseName := 'Company1';
if Crpe1.Connect.Test then
Crpe1.Execute
else
ShowMessage('Error Connecting');
Cunncct Passwurd prupcrty
DccIaratiun
property Password: string;
Dcscriptiun
The Password property contains the user password required for logging on to a SQL Server. This is not stored
in the Report when it is saved (and therefore will not be returned by the Retrieve method), but must be
provided before running the Report.
fxampIc
The following example sets the Connect properties and tests the connection before running the Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Connect.ServerName := 'WBSQLServer';
Crpe1.Connect.UserID := 'Elmer Fudd';
Crpe1.Connect.Password := 'Wabbit';
Crpe1.Connect.DatabaseName := 'Company1';
if Crpe1.Connect.Test then
Crpe1.Execute
else
ShowMessage('Error Connecting');
VCI Re|etetce 2S6
Cunncct Prupagatc prupcrty
DccIaratiun
property Propagate: boolean;
Dcscriptiun
The Propagate property causes the Connect information from the main Report to apply to any Subreports also.
Since the Connect object is created for Subreports as well, there are two ways of using this property:
1. Propagate is set to True for the main Report - This will cause all Subreports to use the same Connect
values as the main Report.
2. Propagate is set to True for a Subreport - This will cause that particular Subreport to get it's Connect
information from the main Report. All other Subreports will not be affected.
Propagate is True by default.
fxampIc
The following code will cause the Connect values to be used for any Subreports also:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Connect.ServerName := 'WBSQLServer';
Crpe1.Connect.UserID := 'Elmer Fudd';
Crpe1.Connect.Password := 'Wabbit';
Crpe1.Connect.DatabaseName := 'Company1';
Crpe1.Connect.Propagate := True;
if Crpe1.Connect.Test then
Crpe1.Execute
else
ShowMessage('Error Connecting');
The following code will cause the first Subreport to get it's Connect values
from the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve Subreports}
Crpe1.Subreports.Retrieve;
{Go to main Report}
Crpe1.Subreports[0];
{Set the main Report Connect}
Crpe1.Connect.ServerName := 'WBSQLServer';
Crpe1.Connect.UserID := 'Elmer Fudd';
Crpe1.Connect.Password := 'Wabbit';
Crpe1.Connect.DatabaseName := 'Company1';
{Go to first Subreport}
Crpe1.Subreports[1];
VCI Re|etetce 2S1
{Set Propagate for the Subreport Connect}
Crpe1.Connect.Propagate := True;
{Go back to main Report}
Crpe1.Subreports[0];
{Run the Report}
if Crpe1.Connect.Test then
Crpe1.Execute
else
ShowMessage('Error Connecting');
Cunncct ScrvcrNamc prupcrty
DccIaratiun
property ServerName: string;
Dcscriptiun
This property contains the name of the Server being connected to. If the Report was created using Crystal's
native SQL drivers, this will be the actual Server name. If the Report was created using ODBC drivers, this will
be the ODBC Data Source Name.
fxampIc
The following example sets the Connect properties and tests the connection before running the Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Connect.ServerName := 'WBSQLServer';
Crpe1.Connect.UserID := 'Elmer Fudd';
Crpe1.Connect.Password := 'Wabbit';
Crpe1.Connect.DatabaseName := 'Company1';
if Crpe1.Connect.Test then
Crpe1.Execute
else
ShowMessage('Error Connecting');
Cunncct UscrlD prupcrty
DccIaratiun
property UserID: string;
Dcscriptiun
This property contains the user name required to log on to the SQL Server.
VCI Re|etetce 2S2
fxampIc
The following example sets the Connect properties and tests the connection before running the Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Connect.ServerName := 'WBSQLServer';
Crpe1.Connect.UserID := 'Elmer Fudd';
Crpe1.Connect.Password := 'Wabbit';
Crpe1.Connect.DatabaseName := 'Company1';
if Crpe1.Connect.Test then
Crpe1.Execute
else
ShowMessage('Error Connecting');
Cunncct Mcthuds
Cunncct CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to set the Connect properties to their default values:
ServerName := '';
UserID := '';
Password := '';
DatabaseName := '';
Propagate := True;
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.
fxampIc
This code clears the Connect properties for the main Report (assuming the default state of Subreports[0]):
Crpe1.Connect.Clear;
This code clears the Connect properties for the second Subreport:Crpe1.Subreports[2];
Crpe1.Connect.Clear;
VCI Re|etetce 2S!
Cunncct CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeConnect): boolean;
Dcscriptiun
The CopyFrom method copies the Connect property values from another TCrpeConnect object. It is similar to
Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the Connect property values to a temporary TCrpeConnect object:
var
tempConnect : TCrpeConnect;
begin
tempConnect := TCrpeConnect.Create;
tempConnect.CopyFrom(Crpe1.Connect);
{...later, when finished with the temp object...}
tempConnect.Free;
end;
Cunncct Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component and does not need to be called in code.
Cunncct Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
VCI Re|etetce 2S4
Dcscriptiun
The Retrieve method obtains the Connect information from the Report. The Connect information is obtained
from the first table in the Report that has LogOn information (i.e. the first SQL table located). Returns True if
the call was successful in obtaining Connect information.
NO7F: Snce lhe Connecl objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe Connecl lor lhe
Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl lo oblan lhe Connecl
sellngs lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle lhrough lhe Subreorls objecl and
call Relreve lor each lem. 7he VCI wll slore searale Connecl sellngs lor each Subreorl (see Fxamle).
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Connect.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve Subreports}
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.Connect.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
Cunncct Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the Connect 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.
VCI Re|etetce 2SS
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.
fxampIc
In this example, the Connect settings are sent from the Crystal component to the Crystal Reports Print Engine
DLL. This is normally handled automatically in the Execute method:
Crpe1.Connect.Send;
Cunncct Tcst mcthud
DccIaratiun
function Test: boolean;
Dcscriptiun
The Test method can be used to try out a connection after the Connect properties have been filled.
fxampIc
The Test method is used in the example below to check the Connect information before running a Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Connect.Retrieve;
Crpe1.Connect.Password := 'Agent86';
if Crpe1.Connect.Test then
Crpe1.Execute
else
ShowMessage('Error Connecting');
fxpurt Prupcrtics
fxpurt AppNamc prupcrty
DccIaratiun
property AppName: TCrExportAppName;
Typc
TCrExportAppName = string;
VCI Re|etetce 2S6
Dcscriptiun
When the Destination property is set "toApplication", the Report will be exported in one of two ways:
1. If the AppName property has a value assigned to it, the Report will be exported to the FileName
specified and then the VCL will attempt to open this exported file with the application specified in the
AppName property.
2. If the AppName property is blank, the Report will be exported to a temporary file, and the Print Engine
will attempt to launch the temporary file using the application associated with the filename extension in
the Windows environment.
fxampIc
The following example exports a Report to a defined application:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toApplication;
Crpe1.Export.FileType := Dif;
Crpe1.Export.FileName := 'C:\Company.dif';
Crpe1.Export.AppName := 'C:\Windows\Notepad.exe';
Crpe1.Execute;
The following example exports a Report to application using the Application with the associated extension in
the Windows environment (if there is one):
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toApplication;
Crpe1.Export.FileType := Dif;
Crpe1.Export.FileName := 'C:\Company.dif';
Crpe1.Export.AppName := '';
Crpe1.Execute;
fxpurt CharScpQuutc prupcrty
DccIaratiun
property CharSepQuote: TCrFieldCharSeparator;
Typc
TCrFieldCharSeparator = string[1];
VCI Re|etetce 2S7
Dcscriptiun
The CharSepQuote property holds the value of the string field quote-mark character when exporting to
CharacterSeparated format. This is the character that is used to specify the start and end of an individual string
field. Quotes are not applied to numeric fields. This property works in conjunction with CharSepSeparator.
fxampIc
Exporting to File in CharacterSeparated format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := CharacterSeparated;
Crpe1.Export.FileName := 'C:\MyReport.txt';
{CharSepQoute surrounds string fields}
Crpe1.Export.CharSepQuote := '#';
{CharSepSeparator separates fields}
Crpe1.Export.CharSepSeparator := '+++';
Crpe1.Execute;
fxpurt CharScpScparatur prupcrty
DccIaratiun
property CharSepSeparator: TCrFieldDelimiter;
Typc
TCrFieldDelimiter = string[PE_FIELDDELIMLEN];
Cunstant
PE_FIELDDELIMLEN = 16;
Dcscriptiun
The CharSepSeparator property holds the value of the character(s) used to separate one field from another
when exporting to CharacterSeparated format. This works in conjunction with CharSepQuote.
VCI Re|etetce 2S8
fxampIc
Exporting to File in CharacterSeparated format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := CharacterSeparated;
Crpe1.Export.FileName := 'C:\MyReport.txt';
{CharSepQoute surrounds string fields}
Crpe1.Export.CharSepQuote := '#';
{CharSepSeparator separates fields}
Crpe1.Export.CharSepSeparator := '+++';
Crpe1.Execute;
fxpurt Dcstinatiun prupcrty
DccIaratiun
property Destination: TCrExportDestination;
Typc
TCrExportDestination = (toFile, toEmailViaMapi, toEmailViaVIM, toMSExchange,
toApplication);
Dcscriptiun
The Destination property determines what kind of Export destination will be used when a Report is exported
for example, when Output is set toExport. There are five options:
fxampIc
toFile To a Disk File. FileName must be specified if PromptForOptions is False.
toEmailViaMapi To an email message on MS Exchange, MS Outlook, etc.
toEmailViaVIM To an email message on Lotus Notes mail, etc.
toMSExchange To an email message in an MS Exchange Folder.
toApplication To an Application, either by file extension association, or specified in AppName.
VCI Re|etetce 2S0
Exporting to File in ODBCTable format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toFile;
FileType := ODBCTable;
ODBC.Source := 'SQLServer';
ODBC.User := 'Maxwell Smart';
ODBC.Password := 'Agent86';
ODBC.Table := 'ReportTable';
end;
Crpe1.Execute;
Export to Email in HTML format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toEmailViaMapi;
FileType := HTML3;
FileName := 'c:\MyReport.htm';
Email.ToList := 'Maxwell Smart';
Email.CCList := 'The Chief';
Email.Subject := 'Chaos';
Email.Message := 'Would you believe...';
end;
Crpe1.Execute;
Export to Exchange Folder in PaginatedText format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toMSExchange;
FileType := PaginatedText;
LinesPerPage := 25;
Exchange.Profile := 'Microsoft Outlook';
Exchange.Folder := 'Personal Folders@Inbox';
Exchange.Password := 'Agent86';
end;
Crpe1.Execute;
VCI Re|etetce 266
fxpurt fmaiI prupcrty
DccIaratiun
property Email: TCrpeExportEmail;
Typc
TCrpeExportEmail = class(TPersistent)
Dcscriptiun
The Email object encompasses the properties needed to specify an Email destination for Export. If the Export
Destination is EmailViaMapi, then the four properties available are:
CCList
Message
Subject
ToList
If the Destination is EmailViaVIM, then a fifth property is also available:
VIMBCCList
The Clear method can be used to set all the properties back to empty strings.
NO7F: When exorlng lo Fmal, lhe FleName roerly wll nol aly, bul lhe FleName wll be laken lrom
lhe ReorlName. One excelon lo lhs rule s lhe H7MI lormal, n whch a FleName can be secled when
exorlng lo Fmal.
7here currenlly seems lo be a roblem exorlng lo ODBC when lhe deslnalon s Fmal. 7he 7able wll be
crealed on lhe ODBC Dala Source, bul lhe Fmal send wll lal. Il you need lo exorl an ODBC lable lo Fmal,
l wll have lo be done n lwo sles:
1. Fxorl lhe Reorl lo ODBC 7able
2. Send lhe 7able lo Fmal n your alcalon code.
fxampIc
Export to Email in HTML format:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toEmailViaMapi;
FileType := HTML3;
VCI Re|etetce 261
FileName := 'C:\MyReport.htm';
Email.ToList := 'Maxwell Smart';
Email.CCList := 'The Chief';
Email.Subject := 'Chaos';
Email.Message := 'Would you believe...';
end;
Crpe1.Execute;
fxpurt fmaiI CClist prupcrty
DccIaratiun
property CCList: string;
Dcscriptiun
Specifies the CC list to which you want your Email message sent. Applies to both MAPI and VIM.
Multiple names must be separated by a semicolon.
fxampIc
Export to Email in HTML format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toEmailViaMapi;
FileType := HTML3;
FileName := 'C:\MyReport.htm';
Email.ToList := 'Maxwell Smart';
Email.CCList := 'The Chief';
Email.Subject := 'Chaos';
Email.Message := 'Would you believe...';
end;
Crpe1.Execute;
fxpurt fmaiI Mcssagc prupcrty
DccIaratiun
property Message: string;
Dcscriptiun
Specifies the string you want to appear as the body of your Email Message. Applies to both MAPI and VIM.
VCI Re|etetce 262
fxampIc
Export to Email in HTML format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toEmailViaMapi;
FileType := HTML3;
FileName := 'C:\MyReport.htm';
Email.ToList := 'Maxwell Smart';
Email.CCList := 'The Chief';
Email.Subject := 'Chaos';
Email.Message := 'Would you believe...';
end;
Crpe1.Execute;
fxpurt fmaiI Subjcct prupcrty
DccIaratiun
property Subject: string;
Dcscriptiun
Specifies the Subject line in your Email message. Applies to both MAPI and VIM.
fxampIc
Export to Email in HTML format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toEmailViaMapi;
FileType := HTML3;
FileName := 'C:\MyReport.htm';
Email.ToList := 'Maxwell Smart';
Email.CCList := 'The Chief';
Email.Subject := 'Chaos';
Email.Message := 'Would you believe...';
end;
Crpe1.Execute;
VCI Re|etetce 26!
fxpurt fmaiI Tulist prupcrty
DccIaratiun
property ToList: string;
Dcscriptiun
Specifies the "To" list to which you want your Email message directed. Applies to both MAPI and VIM.
Multiple names must be separated by a semicolon.
fxampIc
Export to Email in HTML format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toEmailViaMapi;
FileType := HTML3;
FileName := 'C:\MyReport.htm';
Email.ToList := 'Maxwell Smart';
Email.CCList := 'The Chief';
Email.Subject := 'Chaos';
Email.Message := 'Would you believe...';
end;
Crpe1.Execute;
fxpurt fmaiI VlMBCClist prupcrty
DccIaratiun
property VIMBCCList: string;
Dcscriptiun
Specifies the "Blind CC" list to which you want your Email message copied. Applies to VIM only (cc:Mail), not
MAPI. Multiple names must be separated by a semicolon.
VCI Re|etetce 264
fxampIc
Export to Email in HTML format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toEmailViaVIM;
FileType := HTML3;
FileName := 'C:\MyReport.htm';
Email.ToList := 'Maxwell Smart';
Email.CCList := 'The Chief';
Email.VIMBCCList := 'Agent99; Heimi';
Email.Subject := 'Chaos';
Email.Message := 'Would you believe...';
end;
Crpe1.Execute;
fxpurt fmaiI CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to set the Email properties to their default values:
ToList := '';
CCList := '';
VIMBCCList := '';
Subject := '';
Message := '';
It is called automatically if the Clear method is called for the main component, but may be called in code as
needed.
fxampIc
This line of code clears the Email properties:
Crpe1.Export.Email.Clear;
VCI Re|etetce 26S
fxpurt fmaiI CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeExportEmail): boolean;
Dcscriptiun
The CopyFrom method copies the Email property values from another TCrpeExportEmail object. It is similar
to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the Email property values to a temporary TCrpeExportEmail object:
var
tempEmail : TCrpeExportEmail;
begin
tempEmail := TCrpeExportEmail.Create;
tempEmail.CopyFrom(Crpe1.Export.Email);
{...later, when finished with the temp object...}
tempEmail.Free;
end;
fxpurt fxccISfxt prupcrty
DccIaratiun
property Excel5Ext: TCrpeExportExcel5Ext;
Typc
TCrpeExportExcel5Ext = class(TPersistent)
Dcscriptiun
Only available with SCR 7.0 and higher. The Excel5Ext object contains the properties that apply when
exporting a Report to Excel5Extended.
G The ColumnHeadings property determines if the exported Excel File will have Column Headings or not.
G The ColumnWidth property determines how the column width is calculated on a Report exported to
Excel5Extended. If it is set to ByArea, then the column width is determined by the Area property
setting. If it is set to ByConstant, then the column width is determined by the Constant property
setting. Area allows Crystal to set the width based on the objects in a certain Report area; Constant
allows the programmer to hard-code a column width value.
VCI Re|etetce 266
G The Area property specifies the Report Section whose objects will be used to determine the column
widths of the exported Excel file (if ColumnWidth is set to ByArea).
G The Constant property determines the column width on a Report exported to Excel5Extended if
ColumnWidth is set to ByConstant.
G The TabularFormat property determines if all the objects in one area in a Report will be arranged into
one row (when TabularFormat is True), or whether they will be split into separate rows (when
TabularFormat is False).
G The Clear method can be used to set the Excel5Ext object back to it's default property values.
G The CopyFrom method can be used to copy the Excel5Ext property values to another Excel5Ext object
(for temporary storage).
fxampIc
Exporting to File in Excel5Extended format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := Excel5Extended;
Crpe1.Export.Excel5Ext.ColumnHeadings := True;
Crpe1.Export.Excel5Ext.ColumnWidth := ByArea;
Crpe1.Export.Excel5Ext.Area := 'D';
Crpe1.Export.Excel5Ext.TabularFormat := True;
Crpe1.Execute;
fxpurt fxccISfxt Arca prupcrty
DccIaratiun
property Area: string;
Dcscriptiun
The Area property specifies the Report Section whose objects will be used to determine the column widths of
the exported Excel file. The ColumnWidth property must also be set to ByArea for this property to have effect.
The Area name syntax is the same as the Short Section Names used in the Crystal Reports Designer:

RH Report Header
PH Page Header
GH Group Header
VCI Re|etetce 267
Numbers are used to designate different Groups: GH1, GF2, etc. See About Section Names, Volume 1, Chapter 7,
for more details on the syntax.The default setting for the Area property is "D" (Details).
fxampIc
Exporting to File in Excel5Extended format. The Column Width is determined by the Details area of the
Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := Excel5Extended;
Crpe1.Export.Excel5Ext.ColumnHeadings := True;
Crpe1.Export.Excel5Ext.ColumnWidth := ByArea;
Crpe1.Export.Excel5Ext.Area := 'D';
Crpe1.Export.Excel5Ext.TabularFormat := True;
Crpe1.Execute;
fxpurt fxccISfxt CuIumnHcadings prupcrty
DccIaratiun
property ColumnHeadings: boolean;
Dcscriptiun
Setting ColumnHeadings to True will cause the exported Excel spreadsheet to have Column Headings.
fxampIc
Exporting to File in Excel5Extended format with column headings:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := Excel5Extended;
Crpe1.Export.Excel5Ext.ColumnHeadings := True;
Crpe1.Export.Excel5Ext.ColumnWidth := ByArea;
Crpe1.Export.Excel5Ext.Area := 'D';
Crpe1.Export.Excel5Ext.TabularFormat := True;
Crpe1.Execute;
D Details
GF Group Footer
PF Page Footer
RF Report Footer
VCI Re|etetce 268
fxpurt fxccISfxt CuIumnWidth prupcrty
DccIaratiun
property ColumnWidth: TCrColumnWidth;
Typc
TCrColumnWidth = (ByArea, ByConstant);
Dcscriptiun
ColumnWidth determines how the column width is calculated on a Report exported to Excel5Extended. If it is
set to ByArea, then the column width is determined by the Area property setting. If it is set to ByConstant, then
the column width is determined by the Constant property setting. Area allows Crystal to set the width based on
the objects in a certain Report area; Constant allows the programmer to hard-code a column width value.
fxampIc
Exporting to File in Excel5Extended format. The Column Width is determined by the Details area of the
Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := Excel5Extended;
Crpe1.Export.Excel5Ext.ColumnHeadings := True;
Crpe1.Export.Excel5Ext.ColumnWidth := ByArea;
Crpe1.Export.Excel5Ext.Area := 'D';
Crpe1.Export.Excel5Ext.TabularFormat := True;
Crpe1.Execute;
Exporting to File in Excel5Extended format. The Column Width is determined by the value of the Constant
property, in this case, 12:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := Excel5Extended;
Crpe1.Export.Excel5Ext.ColumnHeadings := True;
Crpe1.Export.Excel5Ext.ColumnWidth := ByConstant;
Crpe1.Export.Excel5Ext.Constant := 12;
Crpe1.Export.Excel5Ext.TabularFormat := True;
Crpe1.Execute;
VCI Re|etetce 260
fxpurt fxccISfxt Cunstant prupcrty
DccIaratiun
property Constant: double;
Dcscriptiun
If the ColumnWidth property is set to ByConstant, the Constant property determines the column width on a
Report exported to Excel5Extended. The default setting for the Constant property is 9.
fxampIc
Exporting to File in Excel5Extended format. The Column Width is determined by the value of the Constant
property, in this case, 12:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := Excel5Extended;
Crpe1.Export.Excel5Ext.ColumnHeadings := True;
Crpe1.Export.Excel5Ext.ColumnWidth := ByConstant;
Crpe1.Export.Excel5Ext.Constant := 12;
Crpe1.Export.Excel5Ext.TabularFormat := True;
Crpe1.Execute;
fxpurt fxccISfxt TabuIarFurmat prupcrty
DccIaratiun
property TabularFormat: boolean;
Dcscriptiun
The TabularFormat property determines if all the objects in one area in a Report will be arranged into one row
(when TabularFormat is True), or whether they will be split into separate rows (when TabularFormat is False).
VCI Re|etetce 276
fxampIc
Exporting to File in Excel5Extended format with tabular format active:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := Excel5Extended;
Crpe1.Export.Excel5Ext.ColumnHeadings := True;
Crpe1.Export.Excel5Ext.ColumnWidth := ByArea;
Crpe1.Export.Excel5Ext.Area := 'D';
Crpe1.Export.Excel5Ext.TabularFormat := True;
Crpe1.Execute;
fxpurt fxccISfxt CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to set the properties of the Excel5Ext object back to their default values:
Area := 'D';
ColumnHeadings := False;
ColumnWidth := ByArea;
Constant := 9;
TabularFormat := False;
It is called automatically if the Clear method is called for the main component, but may be called in code as
desired.
fxampIc
This code sets the Excel5Ext properties back to default:
Crpe1.Export.Excel5Ext.Clear;
fxpurt fxccISfxt CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeExportExcel5Ext): boolean;
VCI Re|etetce 271
Dcscriptiun
The CopyFrom method copies the Excel5Ext property values from another TCrpeExportExcel5Ext object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the Excel5Ext property values to a temporary TCrpeExportExcel5Ext object:
var
tempExcel5Ext : TCrpeExportExcel5Ext;
begin
tempExcel5Ext := TCrpeExportExcel5Ext.Create;
tempExcel5Ext.CopyFrom(Crpe1.Export.Excel5Ext);
{...later, when finished with the temp object...}
tempExcel5Ext.Free;
end;
fxpurt fxccISfxt Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the Excel5Ext object, and does not
need to be called in code, unless you are using the CopyFrom method to store Excel5Ext data to a temporary
object:
var
tempExcel5Ext : TCrpeExcel5Ext;
begin
tempExcel5Ext := TCrpeExcel5Ext.Create;
tempExcel5Ext.CopyFrom(Crpe1.Export.Excel5Ext);
end;
fxpurt fxchangc Prupcrty
DccIaratiun
property Exchange: TCrpeExportExchange;
Typc
TCrpeExportExchange = class(TPersistent)
VCI Re|etetce 272
Dcscriptiun
The Exchange object encompasses the properties needed to specify an Exchange Folder destination for Export.
The three properties are: Profile, Folder, and Password.
G Profile is the Exchange Profile name.
G Password is the Exchange Password required.
G Folder is the Exchange Folder string which represents the desired destination.
The "@" sign is used to specify sub-folders for the Folder property:
Crpe1.Export.Exchange.Folder := 'Personal Folders@Inbox';Export Exchange
Example
Export to Exchange Folder in PaginatedText format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toMSExchange;
FileType := PaginatedText;
LinesPerPage := 25;
Exchange.Profile := 'Microsoft Outlook';
Exchange.Folder := 'Personal Folders@Inbox';
Exchange.Password := 'Agent86';
end;
Crpe1.Execute;
fxpurt fxchangc FuIdcr prupcrty
DccIaratiun
property Folder: string;
Dcscriptiun
Specifies the Exchange Folder name when you want to export to Microsoft Exchange Folder. ExchangeFolder
is case-sensitive. If you enter a value in the wrong case you will receive an error message. The "@" symbol is
used to indicate sub-folder levels: 'Personal Folders@Inbox'.
VCI Re|etetce 27!
fxampIc
Export to Exchange Folder in PaginatedText format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toMSExchange;
FileType := PaginatedText;
LinesPerPage := 25;
Exchange.Profile := 'Microsoft Outlook';
Exchange.Folder := 'Personal Folders@Inbox';
Exchange.Password := 'Agent86';
end;
Crpe1.Execute;
fxpurt fxchangc Passwurd prupcrty
DccIaratiun
property Password: string;
Dcscriptiun
Specified the Exchange Password when you want to export to Microsoft Exchange.
fxampIc
Export to Exchange Folder in PaginatedText format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toMSExchange;
FileType := PaginatedText;
LinesPerPage := 25;
Exchange.Profile := 'Microsoft Outlook';
Exchange.Folder := 'Personal Folders@Inbox';
Exchange.Password := 'Agent86';
end;
Crpe1.Execute;
VCI Re|etetce 274
fxpurt fxchangc PrufiIc prupcrty
DccIaratiun
property Profile: string;
Dcscriptiun
Specifies the Exchange Profile to export a file, when you want to export a Report to Microsoft Exchange.
fxampIc
Export to Exchange Folder in PaginatedText format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toMSExchange;
FileType := PaginatedText;
LinesPerPage := 25;
Exchange.Profile := 'Microsoft Outlook';
Exchange.Folder := 'Personal Folders@Inbox';
Exchange.Password := 'Agent86';
end;
Crpe1.Execute;
fxpurt fxchangc CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to set the Exchange properties to their default values:
Folder := '';
Password := '';
Profile := '';
It is called automatically if the Clear method is called for the main component, but may be called in code as
needed.
VCI Re|etetce 27S
fxampIc
The following example illustrates the use of the Clear method between exporting a Report to Exchange
Folders. This is not really required for the Exchange object since all the properties must be filled with new
values anyway, but it could be required for other objects in the Crystal Reports component in cases where
some of the properties are not going to be filled out with new values:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toMSExchange;
FileType := PaginatedText;
LinesPerPage := 25;
Exchange.Profile := 'Microsoft Outlook';
Exchange.Folder := 'Personal Folders@Inbox';
Exchange.Password := 'Agent86';
end;
Crpe1.Execute;
with Crpe1.Export.Exchange do
begin
{Clear the Exchange properties}
Clear;
{Set the new values}
Profile := 'Microsoft Outlook';
Folder := 'Personal Folders@Inbox';
Password := 'Agent99';
end;
Crpe1.Execute;
fxpurt fxchangc CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeExportExchange): boolean;Description
The CopyFrom method copies the Exchange property values from another TCrpeExportExchange object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
VCI Re|etetce 276
fxampIc
The following example copies all the Exchange property values to a temporary TCrpeExportExchange object:
var
tempExchange : TCrpeExportExchange;
begin
tempExchange := TCrpeExportExchange.Create;
tempExchange.CopyFrom(Crpe1.Export.Exchange);
{...later, when finished with the temp object...}
tempExchange.Free;
end;
fxpurt FiIcNamc prupcrty
DccIaratiun
property FileName: TCrExportFileName;
Typc
TCrExportFileName = string[255];
Dcscriptiun
FileName holds the name (and path) of the file that will be created when exporting a Report. This property
only applies when the Export Destination is set toFile, except in the case of HTML, where the FileName can be
used even when going to Email or Exchange.
fxampIc
Exporting to File in Ascii format:
Crpe1.ReportName := 'C:\MyReport.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := Ascii;
Crpe1.Export.FileName := 'C:\MyReport.txt';
Crpe1.Execute;
VCI Re|etetce 277
fxpurt FiIcTypc prupcrty
DccIaratiun
property FileType: TCrExportType;
Typc
TCrExportType = (Records, TabSeparated, Ascii, Dif, Csv, CharacterSeparated,
TabSeparatedText, CrystalReportRPT, Excel2, Excel3, Excel4, LotusWK1,
LotusWK3, LotusWKS, RTF, WordForWindows, Excel5, HTML30, HTML32ext, HTML32std,
ODBCTable, PaginatedText, Excel5Extended, ReportDefinition);
Dcscriptiun
The FileType property determines what kind of Export format will be used when a Report is exported (i.e.
when Output is set toExport). There are 24 options (WordPerfect, WordForDOS, and QuattroPro are only
available in 16-bit, and are not included in the 32-bit version of the component):
Olon Descrlon
Ascii Text style. Saves the data in ASCII text format with all values separated by
spaces. This style looks most like the printed page.
CharacterSeparated Saves the data as character separated values in ASCII text format. All values
are separated by a character or characters specified by CharSepSeparator and
CharSepQuote properties. Applicable options: UseRptDateFmt,
UseRptNumberFmt, CharSepQuote, CharSepSeparator.
CrystalReportRPT Standard Seagate Crystal Reports format is used. Most often used for sending
the Report to another user via e-mail.
Csv Comma separated values. Encloses alphanumeric field data in quotes and
separates fields with commas. Applicable options: UseRptDateFmt,
UseRptNumberFmt.
Dif Saves the data in data interchange format. This format is often used for the
transfer of data between different spreadsheet programs. Applicable options:
UseRptDateFmt, UseRptNumberFmt.
Excel2 Exports the Report as a Microsoft Excel 2.1 Worksheet.
Excel3 Exports the Report as a Microsoft Excel 3.0 Worksheet.
Excel4 Exports the Report as a Microsoft Excel 4.0 Worksheet.
Excel5 Uses Excel 5 format to save the data in the Report.
Excel5Extended Uses an Excel 5 Extended format to save the data in the Report. This is similar
to Excel5 format, but with extra options. Applicable options: Excel5Ext.
VCI Re|etetce 278
fxampIc
Exporting to File in Ascii format:
Crpe1.ReportName := 'C:\MyReport.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := Ascii;
Crpe1.Export.FileName := 'C:\MyReport.txt';
Crpe1.Execute;
HTML30 Uses HTML 3 format to save the data in the Report. Applicable options:
FileName.
HTML32ext Uses the Internet Explorer version of HTML to save the data in the Report.
Applicable options: FileName.
HTML32std Uses the Netscape version of HTML to save the data in the Report. Applicable
options: FileName.
LotusWK1 Exports the Report as a Lotus 1-2-3 WK1 format worksheet.
LotusWK3 Exports the Report as a Lotus 1-2-3 WK3 format worksheet.
LotusWKS Exports the Report as a Lotus 1-2-3 WKS format worksheet.
ODBCTable Exports to a database format corresponding to a specified ODBC Data Source.
Applicable options (in ODBC sub-class): Source, User, Password, Table.
PaginatedText Exports the Report to Text with Page Headers/Footers. Applicable options:
LinesPerPage.
Records Record style (columns of values). Does not use commas or separators.
Outputs every record with a fixed field width. Applicable options:
UseRptDateFmt, UseRptNumberFmt.
ReportDefinition Exports a text file of descriptive details about the Report. Useful for
cataloging Report design information.
RTF Saves the data in Rich Text Format.
TabSeparated Tab separated values. Presents data in tabular form. Encloses alphanumeric
field data in quotes and separates fields with tabs. Applicable options:
UseRptDateFmt, UseRptNumberFmt.
TabSeparatedText Saves the data in ASCII text format with all values separated by tabs.
WordForWindows Uses the Microsoft Word for Windows format to save the data in the Report.
Olon Descrlon
VCI Re|etetce 270
fxpurt lincsPcrPagc prupcrty
DccIaratiun
property LinesPerPage: Word;
Dcscriptiun
LinesPerPage is an option that applies when PaginatedText is chosen as the Export FileType. It indicates the
number of lines to be printed before the page break. The default is 60 lines. If PromptForOptions is True, the
user will be prompted for the LinesPerPage value.
fxampIc
Export to Exchange Folder in PaginatedText format:
Crpe1.ReportName := 'C:\MyReport.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toMSExchange;
FileType := PaginatedText;
LinesPerPage := 25;
Exchange.Profile := 'Microsoft Outlook';
Exchange.Folder := 'Personal Folders@Inbox';
Exchange.Password := 'Agent86';
end;
Crpe1.Execute;
fxpurt ODBC Prupcrty
DccIaratiun
property ODBC: TCrpeExportODBC;
Typc
TCrpeExportODBC = class(TPersistent)
VCI Re|etetce 286
Dcscriptiun
The ODBC object encompasses the properties needed to specify an ODBC Table destination for Export. The
four properties are:
Source : Must be a valid ODBC Data Source Name
User : Must be a valid UserID (if required)
Password : Must be a valid Password (if required)
Table : Specifies the name of the Table to be created. The Table must not already exist or the
Export will fail.
G If the ODBC Data Source is an SQL-type (Oracle, SQLServer, Sybase, etc.), you must have rights to
create a Table on the Server.
G If the ODBC Data Source is of PC-type (Paradox, dBase, FoxPro, etc.), the resulting Table will be created
as a file in the directory specified in the ODBC Data Source. User and Password are not normally
required for these types of Data Sources.
G Some of the PC-type Data Sources (such as dBase) may not be able to create Tables with names longer
than 8 characters. In this case, the Table name you specify will be truncated if it is over 8 characters.
NO7F: 7here currenlly seems lo be a roblem exorlng lo ODBC when lhe deslnalon s Fmal. 7he 7able
wll be crealed on lhe ODBC Dala Source, bul lhe Fmal send wll lal. Il you need lo exorl an ODBC lable lo
Fmal, l wll have lo be done n lwo sles:
1. Fxorl lhe Reorl lo ODBC 7able
2. Send lhe 7able lo Fmal n your alcalon code.
fxampIc
Exporting to File in ODBC-Table format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toFile;
FileType := ODBCTable;
ODBC.Source := 'SQLServer';
ODBC.User := 'Maxwell Smart';
ODBC.Password := 'Agent86';
ODBC.Table := 'ReportTable';
end;
Crpe1.Execute;
VCI Re|etetce 281
fxpurt ODBC Passwurd prupcrty
DccIaratiun
property Password: string;
Dcscriptiun
Specifies the Password required to connect to an ODBC Data Source when exporting a Report in ODBC format.
This is only required if the ODBC Data Source that you are exporting to requires a Password (most SQL types
do, most PC types don't).
fxampIc
Exporting to File in ODBC-Table format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toFile;
FileType := ODBCTable;
ODBC.Source := 'SQLServer';
ODBC.User := 'Maxwell Smart';
ODBC.Password := 'Agent86';
ODBC.Table := 'ReportTable';
end;
Crpe1.Execute;
fxpurt ODBC Suurcc prupcrty
DccIaratiun
property Source: string;
Dcscriptiun
Specifies the name of the ODBC Data Source to export to when exporting a Report in ODBC format.
VCI Re|etetce 282
fxampIc
Exporting to File in ODBC-Table format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toFile;
FileType := ODBCTable;
ODBC.Source := 'SQLServer';
ODBC.User := 'Maxwell Smart';
ODBC.Password := 'Agent86';
ODBC.Table := 'ReportTable';
end;
Crpe1.Execute;
fxpurt ODBC TabIc prupcrty
DccIaratiun
property Table: string;
Dcscriptiun
Specifies the name of the Table to export to when exporting a Report in ODBC format.
fxampIc
Exporting to File in ODBC-Table format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toFile;
FileType := ODBCTable;
ODBC.Source := 'SQLServer';
ODBC.User := 'Maxwell Smart';
ODBC.Password := 'Agent86';
ODBC.Table := 'ReportTable';
end;
Crpe1.Execute;
VCI Re|etetce 28!
fxpurt ODBC Uscr prupcrty
DccIaratiun
property User: string;
Dcscriptiun
Specifies the UserID required to connect to the ODBC Data Source when exporting a Report in ODBC format.
fxampIc
Exporting to File in ODBC-Table format:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
with Crpe1.Export do
begin
Destination := toFile;
FileType := ODBCTable;
ODBC.Source := 'SQLServer';
ODBC.User := 'Maxwell Smart';
ODBC.Password := 'Agent86';
ODBC.Table := 'ReportTable';
end;
Crpe1.Execute;
fxpurt ODBC CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to set the ODBC properties to their default values:
Source := '';
User := '';
Password := '';
Table := '';
It is called automatically if the Clear method is called for the main component, but may be called in code as
needed.
VCI Re|etetce 284
fxampIc
This line of code clears the ODBC Export properties:
Crpe1.Export.ODBC.Clear;
fxpurt ODBC CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeExportODBC): boolean;
Dcscriptiun
The CopyFrom method copies the ODBC property values from another TCrpeExportODBC object. It is similar
to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the ODBC property values to a temporary TCrpeExportODBC object:
var
tempODBC : TCrpeExportODBC;
begin
tempODBC := TCrpeExportODBC.Create;
tempODBC.CopyFrom(Crpe1.Export.ODBC);
{...later, when finished with the temp object...}
tempODBC.Free;
end;
fxpurt PrumptFurOptiuns prupcrty
DccIaratiun
property PromptForOptions: boolean
VCI Re|etetce 28S
Dcscriptiun
PromptForOptions determines if the Crystal Reports Print Engine will use the Export Options specified in the
VCL properties, or if it will prompt the user for those values. The prompt dialog boxes are the same as those
seen when the Export button is pressed in the Crystal Reports runtime Preview Window, of which the
following are samples:
NO7F: 7he VCI Fxorl roerly sellngs wll nol allecl lhe delaull slale ol lhe roerles n lhe Prnl Fngne
roml dalogs.
fxampIc
The following code will export a Report and prompt the user for the values:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.PromptForOptions := True;
Crpe1.Execute;
VCI Re|etetce 286
fxpurt PrumptOnOvcrwritc prupcrty
DccIaratiun
property PromptOnOverwrite: boolean;
Dcscriptiun
PromptOnOverwrite can be used to warn the user if the file that is being exported to already exists. It is only
active if the Destination is toFile. If PromptOnOverwrite is True, and the file specified in FileName already
exists, the following dialog box will appear:

fxampIc
The following code will export a Report to file, and prompt the user if the file exists already:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := Ascii;
Crpe1.Export.FileName := 'C:\Company.txt';
Crpe1.Export.PromptOnOverwrite := True;
Crpe1.Execute;
fxpurt UscRptDatcFmt prupcrty
DccIaratiun
property UseRptDateFmt: Boolean;
VCI Re|etetce 287
Dcscriptiun
When exporting a Report, the UseRptDateFmt property indicates whether or not the dates should be exported
in the same date format (MDY, DMY, etc.) that is used in the Report or instead optimize the dates for the file
format that has been selected. This property applies only when FileType is set to one of the following:
Records
TabSeparated
Dif
Csv
CharacterSeparated
By default, the UseRptDateFmt property is set to True.
fxampIc
The following code shows how to export to File in DIF format. The Number and Date formats will be
optimized for the file format, regardless of how they are formatted in the Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := Dif;
Crpe1.Export.FileName := 'C:\Company.dif';
Crpe1.Export.UseRptDateFmt := False;
Crpe1.Export.UseRptNumberFmt := False;
Crpe1.Execute;
fxpurt UscRptNumbcrFmt prupcrty
DccIaratiun
property UseRptNumberFmt: Boolean;
Dcscriptiun
When exporting a Report, UseRptNumberFmt indicates whether or not the numbers in the exported file will
retain the same format (decimal places, negatives, etc.) used in the Report, or instead optimize the numbers
for the file format that has been selected. This property only applies when PrintFileType is set one of the
following types:
Records
TabSeparated
Dif
Csv
CharacterSeparated
By default, the UseRptNumberFmt property is set to True.
VCI Re|etetce 288
fxampIc
The following code shows how to export to File in DIF format. The Number and Date formats will be
optimized for the file format, regardless of how they are formatted in the Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := Dif;
Crpe1.Export.FileName := 'C:\Company.dif';
Crpe1.Export.UseRptDateFmt := False;
Crpe1.Export.UseRptNumberFmt := False;
Crpe1.Execute;
fxpurt Mcthuds
fxpurt CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to set the Export properties back to their default values. These defaults consist of
clearing all the string fields, and setting the following properties:
FileName := '';
FileType := Ascii;
Destination := toFile;
CharSepQuote := '';
CharSepSeparator := '';
UseRptNumberFmt := TCRPE_DEFAULT_USERPTNUMBERFMT; {True}
UseRptDateFmt := TCRPE_DEFAULT_USERPTDATEFMT; {True}
LinesPerPage := TCRPE_DEFAULT_LINESPERPAGE; {60}
ColumnHeadings := False;
PromptForOptions := False;
PromptOnOverwrite := False;
Email.Clear;
Exchange.Clear;
ODBC.Clear;
It is called automatically if the Clear method is called for the main component, but may be called in code as
needed.
VCI Re|etetce 280
fxampIc
This line of code clears the Export properties:
Crpe1.Export.Clear;
fxpurt CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeExport): boolean;
Dcscriptiun
The CopyFrom method copies the Export property values from another TCrpeExport object. It is similar to
Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the Export property values to a temporary TCrpeExport object:
var
tempExport : TCrpeExport;
begin
tempExport := TCrpeExport.Create;
tempExport.CopyFrom(Crpe1.Export);
{...later, when finished with the temp object...}
tempExport.Free;
end;
fxpurt Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the Export object, and does not need
to be called in code.
VCI Re|etetce 206
fxpurt Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
fxpurt Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the Export 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.
fxampIc
In this example, the Export settings are sent from the Crystal component to the Crystal Reports Print Engine
DLL. This is normally handled automatically in the Execute method:
Crpe1.Export.Send;
FurmuIas Prupcrtics
FurmuIas FurmuIa prupcrty
DccIaratiun
property Formula: TCrpeString;
VCI Re|etetce 201
Typc
TCrpeString = class(TStringList)
Dcscriptiun
The Formula property contains the actual text of the Formula. To assign a new value to the Formula property,
any of the following methods can be used (or any other method that is valid for a StringList):
1) Crpe1.Formulas.Formula.Assign('new text');
2) Crpe1.Formulas.Formula.Text := 'new text';
3) Crpe1.Formulas.Formula.Clear;
Crpe1.Formulas.Formula[0] := 'new text';
4) Crpe1.Formulas.Formula.SetText(PChar('new text'));
G The new Formula string must conform to Seagate Crystal Reports syntax requirements.
See also: Using Variables with Formulas, Volume 1, Chapter 7.
fxampIc
The following code shows how the Formula property is used to store a new formula.
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Formulas.Retrieve;
Crpe1.Formulas[0];
Crpe1.Formulas.Formula.Assign('({company.SALES} * 10) / 100');
Crpe1.Output := toWindow;
Crpe1.Execute;
FurmuIas ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeFormulas;
Dcscriptiun
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 various items stored in the Formulas object, allowing the object
to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript: Formulas[2] is
the same as Formulas.Item[2].
G Item returns a reference to itself, so the Formulas properties can be used right after the subscript:
Formulas[2].Name := 'Formula1';
VCI Re|etetce 202
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Formulas.Retrieve;
{Set Formulas to the 3rd formula}
Crpe1.Formulas.Item[2];
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Formulas.Retrieve;
{Set Formulas to the 3rd formula}
Crpe1.Formulas[2];
FurmuIas ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current Formulas item number, or set
the Formulas 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 (Formulas[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the Formulas object is pointing
to the first Formula:
if Crpe1.Formulas.ItemIndex <> 0 then
Crpe1.Formulas[0];
VCI Re|etetce 20!
FurmuIas Namc prupcrty
DccIaratiun
property Name: TCrFormulaName;
Typc
TCrFormulaName = string;
Dcscriptiun
The Name property specifies the Name of the Formula. It is a key property, and therefore serves as a lookup;
that is, assigning it a value will cause the Formulas object to point to the item that has a Formula Name with
the same value. Before using the Name property to navigate through the Formulas, the Retrieve method
should be called, or the manual Add method.
fxampIc
The following code uses the Formula Name property to point the Formulas object to the specified formula. It
then assigns a new formula text to the Formula property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Formulas.Retrieve;
{Set the Formulas object to the "Formula One" item}
Crpe1.Formulas.Name := 'Formula One';
{Assign a new formula to the Formula property}
Crpe1.Formulas.Formula.Text := '{table.NUM} * 100';
Crpe1.Output := toWindow;Crpe1.Execute;
FurmuIas Mcthuds
FurmuIas Add mcthud
DccIaratiun
procedure Add(FormulaName: TCrFormulaName);
Typc
TCrFormulaName = string;
VCI Re|etetce 204
Dcscriptiun
The Add method adds an item to the Formulas object and sets the internal index to that item. It requires a
Formula name as a parameter, which should be a name corresponding to a Formula in the Report. Formula
Names are expressed as they are written in Crystal Reports, but without the "@" symbol that gets added when
they are used within other Formulas. If the Add method is used, the steps to using Formulas are:
1 Add an item to the Formulas object (you must specify the Formula name).
2 Fill the Text property with a formula.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
Formula names are correcl lor lhe currenl Reorl.
fxampIc
The Add method can be used to manually add an item to the Formulas object, instead of using Retrieve:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Formula Name - must be same as in Report}
Crpe1.Formulas.Add('Formula2');
Crpe1.Formulas.Formula.Text := '2001';
Crpe1.Output := toWindow;
Crpe1.Execute;
FurmuIas Chcck mcthud
DccIaratiun
function Check: boolean;
Dcscriptiun
The Check method can be used to check the syntax of a Formula before running the Report. Check returns a
boolean value:
True :Formula is good.
False :Formula has an error.
VCI Re|etetce 20S
fxampIc
The following code loops through all the Formulas, checking each one:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Formulas.Retrieve;
for cnt := 0 to (Crpe1.Formulas.Count - 1) do
begin
if not Crpe1.Formulas[cnt].Check then
ShowMessage('Error in Formula #' + IntToStr(cnt));
end;
end;
FurmuIas CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the Formulas 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 is only applied to the Formulas object of the current Report/Subreport specified in the Subreports
object. Therefore, to clear all the Formulas of all the Subreports will require a looping procedure that goes
through each Subreport and applies the Clear.
fxampIc
This code clears the Formulas properties for the main Report (assuming the default state of Subreports[0]):
Crpe1.Formulas.Clear;
This code clears the Formulas properties for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.Formulas.Clear;
end;
VCI Re|etetce 206
FurmuIas CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeFormulas): boolean;
Dcscriptiun
The CopyFrom method copies the Formulas property values from another TCrpeFormulas object. It is similar
to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the Formulas property values to a temporary TCrpeFormulas object:
var
tempFormulas : TCrpeFormulas;
begin
tempFormulas := TCrpeFormulas.Create;
tempFormulas.CopyFrom(Crpe1.Formulas);
{...later, when finished with the temp object...}
tempFormulas.Free;
end;
FurmuIas Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the Formulas object. It is handy for
setting up loops to make similar changes to each item.
VCI Re|etetce 207
fxampIc
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.Formulas.Retrieve;
for cnt := 0 to (Crpe1.Formulas.Count - 1) do
Crpe1.Formulas[cnt].Formula.Text := '2001';
end;
FurmuIas Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the Formulas object, and does not
need to be called in code.
FurmuIas DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the Formulas object. The "nIndex" parameter
represents the number of the item in the Formulas object.
NO7F: Delele wll nol remove lhe Formula lrom lhe Reorl, l wll jusl remove l lrom lhe Cryslal VCI.
VCI Re|etetce 208
fxampIc
The Delete method can be used to manually remove an item from the Formulas object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Formula Name - must be same as in Report}
Crpe1.Formulas.Add('Formula2');
Crpe1.Formulas.Formula.Text := '2001';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.Formulas.Delete(0);
FurmuIas Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
FurmuIas lndcxOf mcthud
DccIaratiun
function IndexOf(FormulaName: TCrFormulaName): integer;
Typc
TCrFormulaName = string;
Dcscriptiun
The IndexOf method takes a Formula name and returns the index position of the Formula item in the current
Formulas object.
After the Retrieve method has been called, the Formulas object contains one item for each Formula in the
Report. The IndexOf method can be used to determine if a given Formula Name actually exists in the Formulas
object before trying to access it.
VCI Re|etetce 200
fxampIc
The following code illustrates the use of the IndexOf method to locate a specific Formula item by its name:
var
nItem: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Formulas.Retrieve;
{Find a specific formula}
nItem := Crpe1.Formulas.IndexOf('Percentage Sales');
{If it exists...}
if nItem > -1 then
begin
with Crpe1.Formulas[nItem] do
begin
{Calculate 20% of SALES}
Formula.Text := '{company.SALES} * .20';
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
FurmuIas Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the Formulas from the Report and stores them in Formulas object. If no Formulas
were found, the call returns False. Be aware that calling Retrieve will first cause the Formulas object to be
cleared, so any current information stored in it will be removed.
NO7F: Snce lhe Formulas objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe Formulas lor
lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl lo oblan lhe
Formulas nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle lhrough lhe
Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale Formulas nlormalon lor each
Subreorl.
VCI Re|etetce !66
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Formulas.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.Formulas.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
FurmuIas Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the Formulas 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.
We strongly recommend 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.
fxampIc
In this example, the Formulas settings are sent from the Crystal component to the Crystal Reports Print Engine
DLL. This is normally handled automatically in the Execute method:
Crpe1.Formulas.Send;
VCI Re|etetce !61
GraphData Prupcrtics
GraphData CuIGruupN prupcrty
DccIaratiun
property ColGroupN: smallint;
Dcscriptiun
The ColGroupN property specifies which Group number in the Report is used to create the values in the
columns of the Graph.
G Group numbers start with 1.
G Use -1 for Default (no change).
fxampIc
The sample code below illustrates the use of the GraphData object to change the Group Field that Columns of
the Graph are based on:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphData.Retrieve;
if Crpe1.GraphData.Count > 0 then
Crpe1.GraphData[0].ColGroupN := 2;
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphData Dircctiun prupcrty
DccIaratiun
property Direction: TCrGraphDirection;
Typc
TCrGraphDirection = (Rows, Cols, RowCol, ColRow, Unknown);
VCI Re|etetce !62
Dcscriptiun
The Direction property is used to specify in what direction a Graph will read its data from the Report.
G For normal Group/Total report, the Direction, is always Cols.
G For Cross-Tab Graphs, use any of the following TCrGraphDirection values:
fxampIc
The sample code below illustrates the use of the GraphData object to change the Direction in which the Graph
will read its data from the Report. In this case, the Report is a Cross Tab Report (which is a requirement in
order to change the Direction), and the Graph will read its data from the Rows:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphData.Retrieve;
if Crpe1.GraphData.Count > 0 then
Crpe1.GraphData[0].Direction := Rows;
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphData ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeGraphData;
7CrGrahDreclon Meanng
Rows Use only row values in graph.
Cols Use only column values in graph.
RowCol Graph by row values, then by column values.
ColRow Graph by column values, then by row values.
Unknown The direction of the graph is unknown.
VCI Re|etetce !6!
Dcscriptiun
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 GraphData object, allowing the
object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript: GraphData[2] is
the same as GraphData.Item[2].
G Item returns a reference to itself, so the GraphData properties can be used right after the subscript:
GraphData[2].SummarizedFieldN := 1;
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphData.Retrieve;
{Set GraphData object to the 2nd graph}
Crpe1.GraphData.Item[1];
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphData.Retrieve;
{Set GraphData object to the 2nd graph}
Crpe1.GraphData[1];
GraphData ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current GraphData item number, or
set the GraphData 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 (GraphData[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.
VCI Re|etetce !64
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the GraphData object is pointing
to the first GraphData item:
if Crpe1.GraphData.ItemIndex <> 0 then
Crpe1.GraphData[0];
GraphData Numbcr prupcrty
DccIaratiun
property Number: TCrGraphDataNumber;
Typc
TCrGraphDataNumber = integer;
Dcscriptiun
The Number property specifies the Graph Number.
G If the Retrieve method is used to fill the GraphData object with information from the Report, each
GraphData item will have a unique Graph Number assigned by the VCL.
G If the manual Add method is used instead, a Graph number will have to be specified which corresponds
to the Print Engine method of numbering Graphs (see How Graphs are Numbered, Page 37).
The primary use of the Number property is as a look-up to point the GraphData object to the item with the
Graph number specified. The default array property, Item, however, provides an easier way to navigate
through the object.
fxampIc
The sample code below illustrates the use of the Number property to navigate the GraphData object to the item
that specifies the details for Graph number 0 (the first Graph in the Report):
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphData.Retrieve;
Crpe1.GraphData.Number := 0;
Crpe1.GraphData.SummarizedFieldN := 2;Crpe1.Execute;
VCI Re|etetce !6S
GraphData RuwGruupN prupcrty
DccIaratiun
property RowGroupN: smallint;
Dcscriptiun
The RowGroupN property specifies which Group number in the report is used to create the values in the Rows
of the Graph.
G Group numbers start with 1.
G Use -1 for default (no change).
fxampIc
The sample code below illustrates the use of the GraphData object to change the Group Field that Rows of the
Graph are based on:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphData.Retrieve;
if Crpe1.GraphData.Count > 0 then
Crpe1.GraphData[0].RowGroupN := 2;
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphData Scctiun prupcrty
DccIaratiun
property Section: string;
Dcscriptiun
The Section property contains the Section name of the item that the GraphData object is currently pointed to.
It indicates in which Section of the Report that the Graph is located.
Note that you cannot move a Graph from one Section to another by changing this property. It should primarily
be used as a read-only property after the GraphData information has been retrieved with the Retrieve method.
If the manual Add method is used to add items to the GraphData object, then Section will have to be assigned
the correct value in code.
VCI Re|etetce !66
The Section name syntax is the same as the Short Section Names used in the Crystal Reports Designer:
Lower-case letters: a, b, c, etc. are used to specify sub-sections. Numbers are used to designate different
Groups: GH1, GF2, etc. See About Section Names, Volume 1, Chapter 7, for more details on the syntax.
fxampIc
The sample code applies a change only to those Graphs which are located in Group Header 1 (GH1):
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphData.Retrieve;
for cnt := 0 to (Crpe1.GraphData.Count - 1) do
begin
if Crpe1.GraphData[cnt].Section = 'GH1' then
Crpe1.GraphData[cnt].SummarizedFieldN := 2;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphData ScctiunAsCudc prupcrty
DccIaratiun
property SectionAsCode: smallint;
Dcscriptiun
The SectionAsCode property can be used to read and write the Section property via Print Engine Section Code
numbers. Since the Print Engine Section Codes are numeric, it is easier to apply conditional formatting to
certain sections (in a For loop for example) based on mathematical calculations on the Section Code number
than it is by parsing out the regular Section Code string (GH1b, etc.).
See also: About Section Names, Volume 1, Chapter 7.
RH Report Header
PH Page Header
GH Group Header
D Details
GF Group Footer
PF Page Footer
RF Report Footer
VCI Re|etetce !67
fxampIc
The following example uses the SectionAsCode property to apply conditional changes to a Graph. In this case,
there is a Graph in each of three Group Header sections (GH1a, GH2a, GH3a). Since the Section Code for GH1a
is 3000, GH2a is 3001, and GH3a is 3002, it is possible to do a simple mathematical calculation on the remainder
of the Section Code divided by 1000 to change the style of the Graph only if it is in GH1:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphData.Retrieve;
for cnt := 0 to (Crpe1.GraphData.Count - 1) do
begin
{if the remainder of the SectionCode divided by 1000 is greater than zero,
then apply the change}
if (Crpe1.GraphData[cnt].SectionAsCode mod 1000 = 0) then
Crpe1.GraphData[cnt].SummarizedFieldN := 1;
end;
end;
GraphData SummarizcdFicIdN prupcrty
DccIaratiun
property SummarizedFieldN: smallint;
Dcscriptiun
The SummarizedFieldN property specifies which Summary field in the report is used to set the values of the
Risers in the Graph.
G Summary fields are numbered in order of their creation.
G Summary Field numbers start with 0.
G Use -1 for default (no change).
fxampIc
The sample code below illustrates the use of the GraphData object to change the Summary Field that the Graph
is based on:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphData.Retrieve;
if Crpe1.GraphData.Count > 0 then
Crpe1.GraphData[0].SummarizedFieldN := 2;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce !68
GraphData Mcthuds
GraphData Add mcthud
DccIaratiun
procedure Add(GraphNumber: TCrGraphDataNumber);
Typc
TCrGraphDataNumber = integer;
Dcscriptiun
The Add method adds an item to the GraphData object and sets the internal index to that item. It requires a
Graph number as a parameter, which should be a number corresponding to a Graph in the Report. Graphs are
numbered starting from zero, from the top of the Report down, and left to right in each Section. If the Add
method is used, the steps to using GraphData are:
1 Add an item to the GraphData object (you must specify the Graph number).
2 Fill the item's properties (ColGroupN, RowGroupN, etc.) with values.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
Grah numbers are correcl lor lhe currenl Reorl.
fxampIc
The Add method can be used to manually add an item to the GraphData object, instead of using Retrieve:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Graph Number - must be same as in Report}
Crpe1.GraphData.Add(0);
{Section must also be specified when using Add}
Crpe1.GraphData.Section := 'PH';
Crpe1.GraphData.SummarizedFieldN := 2;
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphData CIcar mcthud
DccIaratiun
procedure Clear;
VCI Re|etetce !60
Dcscriptiun
This method can be used to clear the internal memory of the GraphData 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 GraphData object of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the GraphData of all the Subreports will require a looping procedure
that goes through each Subreport and applies the Clear method.
fxampIc
This code clears the GraphData properties for the main Report (assuming the default state of Subreports[0]):
Crpe1.GraphData.Clear;
This code clears the GraphData properties for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.GraphData.Clear;
end;
GraphData CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeGraphData): boolean;
Dcscriptiun
The CopyFrom method copies the GraphData property values from another TCrpeGraphData object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the GraphData property values to a temporary TCrpeGraphData object:
var
tempGraphData : TCrpeGraphData;
begin
tempGraphData := TCrpeGraphData.Create;
tempGraphData.CopyFrom(Crpe1.GraphData);
{...later, when finished with the temp object...}
tempGraphData.Free;
end;
VCI Re|etetce !16
GraphData Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the GraphData object. It is handy
for setting up loops to make similar changes to each item.
fxampIc
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.GraphData.Retrieve;
for cnt := 0 to (Crpe1.GraphData.Count - 1) do
Crpe1.GraphData[cnt].SummarizedFieldN := 2;
end;
GraphData Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the GraphData object, and does not
need to be called in code.
GraphData DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
VCI Re|etetce !11
Dcscriptiun
The Delete method can be used to remove an item from the GraphData object. The "nIndex" parameter
represents the number of the item in the GraphData object.
fxampIc
The Delete method can be used to manually remove an item from the GraphData object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Graph Number - must be same as in Report}
Crpe1.GraphData.Add(0);
{Section must also be specified when using Add}
Crpe1.GraphData.Section := 'PH';
Crpe1.GraphData.SummarizedFieldN := 2;
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.GraphData.Delete(0);
GraphData Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
GraphData Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the GraphData information from the Report and stores it in the GraphData
object. If no GraphData information was found, the call returns False. Be aware that calling Retrieve will first
cause the GraphData object to be cleared, so any current information stored in it will be removed.
VCI Re|etetce !12
NO7F: Snce lhe GrahDala objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe GrahDala
lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl lo oblan
lhe GrahDala nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle lhrough lhe
Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale GrahDala nlormalon lor each
Subreorl (see Fxamle).
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphData.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.GraphData.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
GraphData ScctiunTypc mcthud
DccIaratiun
function SectionType: string;
Dcscriptiun
The SectionType method returns the Section Code without the subsection specifier. In other words, if the
Section Code for an item is GH1ac, the SectionType method would return GH; if the SectionCode is Da, the
SectionType method would return D.
The primary use for this method is to apply changes to all the Sections in an area, regardless of the sub-section
specifier. See the Example for an illustration.
VCI Re|etetce !1!
fxampIc
The following example uses the SectionType method to apply conditional changes to Graphs. In this case,
there is a Graph in each of three sections (RH, GH1a, GH2a). Only the Graphs in the Group Headers should
be changed, so the SectionType method can be used in an expression to apply the changes:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphData.Retrieve;
for cnt := 0 to (Crpe1.GraphData.Count - 1) do
begin
{if the SectionType is GroupHeader, apply the change}
if (Crpe1.GraphData[cnt].SectionType = 'GH') then
Crpe1.GraphData[cnt].SummarizedFieldN := 1;
end;
end;
GraphData Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the GraphData 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.
fxampIc
In this example, the GraphData settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.GraphData.Send;
VCI Re|etetce !14
GraphOptiuns Prupcrtics
GraphOptiuns BarDircctiun prupcrty
DccIaratiun
property BarDirection: TCrBarDirection;
Typc
TCrBarDirection = (bdHorizontal, bdVertical, bdDefault);
Dcscriptiun
The BarDirection property specifies the direction of the bars in a Bar Graph. These can be either vertical or
horizontal.
fxampIc
The following code illustrates the use of the GraphOptions BarDirection property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphOptions.Retrieve;
if Crpe1.GraphOptions.Count > 0 then
Crpe1.GraphOptions[0].BarDirection := bdHorizontal;
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphOptiuns DataVaIucs prupcrty
DccIaratiun
property DataValues: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The DataValues property specifies whether or not the numeric value associated with each Riser on the Graph
will be displayed. If set to cTrue, a value appears in the Graph for each Riser.
VCI Re|etetce !1S
fxampIc
The following code illustrates the use of the GraphOptions DataValues property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphOptions.Retrieve;
if Crpe1.GraphOptions.Count > 0 then
Crpe1.GraphOptions[0].DataValues := cTrue;
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphOptiuns Funt prupcrty
DccIaratiun
property Font: TFontName;
Dcscriptiun
The Font property specifies the font for all text and values in the Graph. The property uses Delphi's
TFontName type, which makes a list of installed fonts available on the Object Inspector (or if the property is
double-clicked, the Font Dialog will appear).
fxampIc
The following code illustrates the use of the GraphOptions Font property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphOptions.Retrieve;
if Crpe1.GraphOptions.Count > 0 then
Crpe1.GraphOptions[0].Font := 'Times New Roman';
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphOptiuns Gridlincs prupcrty
DccIaratiun
property GridLines: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
VCI Re|etetce !16
Dcscriptiun
The GridLines property specifies whether or not to display Grid Lines on the Graph. If the property is set to
cTrue, Grid Lines will be visible.
fxampIc
The following code illustrates the use of the GraphOptions GridLines property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphOptions.Retrieve;
if Crpe1.GraphOptions.Count > 0 then
Crpe1.GraphOptions[0].GridLines := cTrue;
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphOptiuns ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeGraphOptions;
Dcscriptiun
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 various items stored in the GraphOptions object, allowing the
object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript:
GraphOptions[2] is the same as GraphOptions.Item[2].
G Item returns a reference to itself, so the GraphOptions properties can be used right after the subscript:
GraphOptions[2].Min := 2000;
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.GraphOptions.Retrieve;
{Set GraphOptions object to the 2nd graph}
Crpe1.GraphOptions.Item[1];
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.GraphOptions.Retrieve;
{Set GraphOptions object to the 2nd graph}
Crpe1.GraphOptions[1];
VCI Re|etetce !17
GraphOptiuns ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current GraphOptions item number,
or set the GraphOptions 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 (GraphOptions[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the GraphOptions object is
pointing to the first GraphOptions item:
if Crpe1.GraphOptions.ItemIndex <> 0 then
Crpe1.GraphOptions[0];
GraphOptiuns lcgcnd prupcrty
DccIaratiun
property Legend: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The Legend property specifies whether or not to display the Graph Legend. If the property is set to cTrue, the
Legend will be visible.
VCI Re|etetce !18
fxampIc
The following code illustrates the use of the GraphOptions Legend property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphOptions.Retrieve;
if Crpe1.GraphOptions.Count > 0 then
Crpe1.GraphOptions[0].Legend := cTrue;
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphOptiuns Max prupcrty
DccIaratiun
property Max: double;
Dcscriptiun
The Max property specifies the maximum value that will appear in the graph. Any Graph values above this
value are not charted.
fxampIc
The following code illustrates the use of the GraphOptions Max property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphOptions.Retrieve;
if Crpe1.GraphOptions.Count > 0 then
Crpe1.GraphOptions[0].Max := 144000;
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphOptiuns Min prupcrty
DccIaratiun
property Min: double;
Dcscriptiun
The Min property specifies the minimum value that will appear in the Graph. Any Graph values below this
value are not charted.
VCI Re|etetce !10
fxampIc
The following code illustrates the use of the GraphOptions Min property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphOptions.Retrieve;
if Crpe1.GraphOptions.Count > 0 then
Crpe1.GraphOptions[0].Min := 40;
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphOptiuns Numbcr prupcrty
DccIaratiun
property Number: TCrGraphOptionsNumber;
Typc
TCrGraphOptionsNumber = integer;
Dcscriptiun
The Number property specifies the Graph Number.
G If the Retrieve method is used to fill the GraphOptions object with information from the Report, each
GraphOptions item will have a unique Graph Number assigned by the VCL.
G If the manual Add method is used instead, a Graph number will have to be specified which corresponds
to the Print Engine method of numbering Graphs (see How Graphs are Numbered, Page 37).
The primary use of the Number property is as a look-up to point the GraphOptions object to the item with the
Graph number specified. The default array property, Item, however, provides an easier way to navigate
through the object.
fxampIc
The following code illustrates the use of the Number property to navigate the GraphOptions object to the
specific item that has a Number value of 1:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphOptions.Retrieve;
{Set GraphOptions to item with Number value of 1}
Crpe1.GraphOptions.Number = 1;
Crpe1.GraphOptions.BarDirection := bdHorizontal;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce !26
GraphOptiuns Scctiun prupcrty
DccIaratiun
property Section: string;
Dcscriptiun
The Section property contains the Section name of the item that the GraphOptions object is currently pointed
to. It indicates in which Section of the Report that the Graph is located.
Note that you cannot move a Graph from one Section to another by changing this property. It should primarily
be used as a read-only property after the GraphOptions information has been retrieved with the Retrieve
method. If the manual Add method is used to add items to the GraphOptions object, then Section will have to
be assigned the correct value in code.
The Section name syntax is the same as the Short Section Names used in the Crystal Reports Designer:

Lower-case letters: a, b, c, etc. are used to specify sub-sections. Numbers are used to designate different
Groups: GH1, GF2, etc. See About Section Names, Volume 1, Chapter 7 for more details on the syntax.
fxampIc
In the following example, the Section property is used to apply changes only to Graphs which exist in a given
Report Section (Page Header in this case):
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphOptions.Retrieve;
for cnt := 0 to (Crpe1.GraphOptions.Count - 1) do
begin
if Crpe1.GraphOptions[cnt].Section = 'PH' then
Crpe1.GraphOptions[cnt].BarDirection := bdHorizontal;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
RH Report Header
PH Page Header
GH Group Header
D Details
GF Group Footer
PF Page Footer
RF Report Footer
VCI Re|etetce !21
GraphOptiuns ScctiunAsCudc prupcrty
DccIaratiun
property SectionAsCode: smallint;
Dcscriptiun
The SectionAsCode property can be used to read and write the Section property via Print Engine Section Code
numbers. Since the Print Engine Section Codes are numeric, it is easier to apply conditional formatting to
certain sections (in a For loop for example) based on mathematical calculations on the Section Code number
than it is by parsing out the regular Section Code string (GH1b, etc.).
See also: About Section Names, Volume 1, Chapter 7.
fxampIc
The following example uses the SectionAsCode property to apply conditional changes to Graphs. In this case,
there is a Graph in each of three Group Header sections (GH1a, GH2a, GH3a). Since the Section Code for GH1a
is 3000, GH2a is 3001, and GH3a is 3002, it is possible to do a simple mathematical calculation on the remainder
of the Section Code divided by 1000 to change the options of the Graph only if it is not in GH1:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphOptions.Retrieve;
for cnt := 0 to (Crpe1.GraphOptions.Count - 1) do
begin
{if the remainder of the SectionCode divided by 1000
is greater than zero, then apply the change}
if (Crpe1.GraphOptions[cnt].SectionAsCode mod 1000 > 0) then
Crpe1.GraphOptions[cnt].GridLines := cTrue;
end;
end;
GraphOptiuns Mcthuds
GraphOptiuns Add mcthud
DccIaratiun
procedure Add(GraphNumber: TCrGraphOptionsNumber);
VCI Re|etetce !22
Typc
TCrGraphOptionsNumber = integer;
Dcscriptiun
The Add method adds an item to the GraphOptions object and sets the internal index to that item. It requires
a Graph number as a parameter, which should be a number corresponding to a Graph in the Report. Graphs
are numbered starting from zero, from the top of the Report down, and left to right in each Section. If the Add
method is used, the steps to using GraphOptions are:
1 Add an item to the GraphOptions object (you must specify the Graph number).
2 Fill the item's properties (BarDirection, DataValues, etc.) with values.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
Grah numbers are correcl lor lhe currenl Reorl.
fxampIc
The Add method can be used to manually add an item to the GraphOptions object, instead of using Retrieve:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Graph number - must be same as in Report}
Crpe1.GraphOptions.Add(0);
{Section must also be specified when using Add}
Crpe1.GraphOptions.Section := 'PH';
Crpe1.GraphOptions.Font := 'Times New Roman';
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphOptiuns CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the GraphOptions 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 is only applied to the GraphOptions object of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the GraphOptions of all the Subreports will require a looping
procedure that goes through each Subreport and applies the Clear.
VCI Re|etetce !2!
fxampIc
This code clears the GraphOptions properties for the main Report (assuming the default state of
Subreports[0]):
Crpe1.GraphOptions.Clear;
This code clears the GraphOptions properties for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.GraphOptions.Clear;
end;
GraphOptiuns CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeGraphOptions): boolean;
Dcscriptiun
The CopyFrom method copies the GraphOptions property values from another TCrpeGraphOptions object. It
is similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the GraphOptions property values to a temporary TCrpeGraphOptions
object:
var
tempGraphOptions : TCrpeGraphOptions;
begin
tempGraphOptions := TCrpeGraphOptions.Create;
tempGraphOptions.CopyFrom(Crpe1.GraphOptions);
{...later, when finished with the temp object...}
tempGraphOptions.Free;
end;
VCI Re|etetce !24
GraphOptiuns Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the GraphOptions object. It is handy
for setting up loops to make similar changes to each item.
fxampIc
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.GraphOptions.Retrieve;
for cnt := 0 to (Crpe1.GraphOptions.Count - 1) do
Crpe1.GraphOptions[cnt].GridLines := cTrue;
end;
GraphOptiuns Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the GraphOptions object, and does
not need to be called in code.
GraphOptiuns DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the GraphOptions object. The "nIndex" parameter
represents the number of the item in the GraphOptions object.
VCI Re|etetce !2S
fxampIc
The Delete method can be used to manually remove an item from the GraphOptions object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Graph number - must be same as in Report}
Crpe1.GraphOptions.Add(0);
{Section must also be specified when using Add}
Crpe1.GraphOptions.Section := 'PH';
Crpe1.GraphOptions.Font := 'Times New Roman';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.GraphOptions.Delete(0);
GraphOptiuns Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
GraphOptiuns Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the GraphOptions information from the Report and stores it in the GraphOptions
object. If no GraphOptions information was found, the call returns False. Be aware that calling Retrieve will
first cause the GraphOptions object to be cleared, so any current information stored in it will be removed.
NO7F: Snce lhe GrahOlons objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe
GrahOlons lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you
wanl lo oblan lhe GrahOlons nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo
sle lhrough lhe Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale GrahOlons
nlormalon lor each Subreorl (see Fxamle).
VCI Re|etetce !26
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphOptions.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.GraphOptions.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
GraphOptiuns ScctiunTypc mcthud
DccIaratiun
function SectionType: string;
Dcscriptiun
The SectionType method returns the Section Code without the subsection specifier. In other words, if the
Section Code for an item is GH1ac, the SectionType method would return GH; if the SectionCode is Da, the
SectionType method would return D.
The primary use for this method is to apply changes to all the Sections in an area, regardless of the sub-section
specifier. See the Example for an illustration.
VCI Re|etetce !27
fxampIc
The following example uses the SectionType method to apply conditional changes to Graphs. In this case,
there is a Graph in each of three sections (RH, GH1a, GH2a). Only the Graphs in the Group Headers should
be changed, so the SectionType method can be used in an expression to apply the changes:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphOptions.Retrieve;
for cnt := 0 to (Crpe1.GraphOptions.Count - 1) do
begin
{If SectionType is GroupHeader, apply the change}
if (Crpe1.GraphOptions[cnt].SectionType = 'GH') then
Crpe1.GraphOptions[cnt].Legend := cTrue;
end;
end;
GraphOptiuns Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the GraphOptions 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.
fxampIc
In this example, the GraphOptions settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.GraphOptions.Send;
VCI Re|etetce !28
GraphTcxt Prupcrtics
GraphTcxt FuutNutc prupcrty
DccIaratiun
property FootNote: TCrGraphTextType;
Typc
TCrGraphTextType = string[128];
Dcscriptiun
The FootNote property specifies the footnote text that will appear under the Graph.
fxampIc
The following example retrieves the GraphText information from the Report, then changes the FootNote text
for the first Graph:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
if Crpe1.GraphText.Count > 0 then
Crpe1.GraphText[0].FootNote := 'New FootNote';
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphTcxt GruupsTitIc prupcrty
DccIaratiun
property GroupsTitle: TCrGraphTextType;
Typc
TCrGraphTextType = string[128];
Dcscriptiun
The GroupsTitle property specifies the title of the Groups which are being graphed.
VCI Re|etetce !20
fxampIc
The following example retrieves the GraphText information from the Report, then changes the GroupsTitle for
the first Graph:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
if Crpe1.GraphText.Count > 0 then
Crpe1.GraphText[0].GroupsTitle := 'New Groups Title';
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphTcxt ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeGraphText;
Dcscriptiun
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 various items stored in the GraphText object, allowing the
object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript:
GraphText[2] is the same as GraphText.Item[2].
G Item returns a reference to itself, so the GraphText properties can be used right after the subscript:
GraphText[2].Title := 'NewGraph';
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
{Set GraphText object to the 2nd graph}
Crpe1.GraphText.Item[1];
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
{Set GraphText object to the 2nd graph}
Crpe1.GraphText[1];
VCI Re|etetce !!6
GraphTcxt ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current GraphText item number, or set
the GraphText 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 (GraphText[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the GraphText object is pointing
to the first GraphText item:
if Crpe1.GraphText.ItemIndex <> 0 then
Crpe1.GraphText[0];
GraphTcxt Numbcr prupcrty
DccIaratiun
property Number: TCrGraphTextNumber;
Typc
TCrGraphTextNumber = integer;
Dcscriptiun
The Number property specifies the Graph Number.
G If the Retrieve method is used to fill the GraphText object with information from the Report, each
GraphText item will have a unique Graph Number assigned by the VCL.
G If the manual Add method is used instead, a Graph number will have to be specified which corresponds
to the Print Engine method of numbering Graphs (see How Graphs are Numbered, Page 37).
VCI Re|etetce !!1
The primary use of the Number property is as a look-up to point the GraphText object to the item with the
Graph number specified. The default array property, Item, however, provides an easier way to navigate
through the object.
fxampIc
The following example uses the Number property to navigate the GraphText object to a specific item whose
properties are then changed:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
if Crpe1.GraphText.Count > 0 then
begin
Crpe1.GraphText.Number := 0;
Crpe1.GraphText.XAxisTitle := 'New XAxis Title';
Crpe1.GraphText.YAxisTitle := 'New YAxis Title';
Crpe1.GraphText.ZAxisTitle := 'New ZAxis Title';
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphTcxt Scctiun prupcrty
DccIaratiun
property Section: string;
Dcscriptiun
The Section property contains the Section name of the item that the GraphText object is currently pointed to.
It indicates in which Section of the Report that the Graph is located.
Note that you cannot move a Graph from one Section to another by changing this property. It should primarily
be used as a read-only property after the GraphText information has been retrieved with the Retrieve method.
If the manual Add method is used to add items to the GraphText object, then Section will have to be assigned
the correct value in code.
The Section name syntax is the same as the Short Section Names used in the Crystal Reports Designer:

RH Report Header
PH Page Header
GH Group Header
D Details
GF Group Footer
VCI Re|etetce !!2
Lower-case letters: a, b, c, etc. are used to specify sub-sections. Numbers are used to designate different
Groups: GH1, GF2, etc. See About Section Names, Volume 1, Chapter 7 for more details on the syntax.
fxampIc
The Section property can be used to apply conditional changes to GraphText (i.e. only those items that are in
the Page Header are affected in the following example):
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
for cnt := 0 to (Crpe1.GraphText.Count - 1) then
begin
if Crpe1.GraphText[cnt].Section = 'PH' then
begin
Crpe1.GraphText[cnt].XAxisTitle := 'New XAxis Title';
Crpe1.GraphText[cnt].YAxisTitle := 'New YAxis Title';
Crpe1.GraphText[cnt].ZAxisTitle := 'New ZAxis Title';
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
GraphTcxt ScctiunAsCudc prupcrty
DccIaratiun
property SectionAsCode: smallint;
Dcscriptiun
The SectionAsCode property can be used to read and write the Section property via Print Engine Section Code
numbers. Since the Print Engine Section Codes are numeric, it is easier to apply conditional formatting to
certain sections (in a For loop for example) based on mathematical calculations on the Section Code number
than it is by parsing out the regular Section Code string (GH1b, etc.).
See also: About Section Names, Volume 1, Chapter 7.
PF Page Footer
RF Report Footer
VCI Re|etetce !!!
fxampIc
The following example uses the SectionAsCode property to apply conditional changes to Graphs. In this case,
there is a Graph in each of three Group Header sections (GH1a, GH2a, GH3a). Since the Section Code for GH1a
is 3000, GH2a is 3001, and GH3a is 3002, it is possible to do a simple mathematical calculation on the remainder
of the Section Code divided by 1000 to change the Title of the Graph only if it is not in GH1:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
for cnt := 0 to (Crpe1.GraphText.Count - 1) do
begin
{if the remainder of the SectionCode divided by 1000
is greater than zero, then apply the change}
if (Crpe1.GraphText[cnt].SectionAsCode mod 1000 > 0) then
Crpe1.GraphText[cnt].Title := 'Sub-Group Graph';
end;
end;
GraphTcxt ScricsTitIc prupcrty
DccIaratiun
property SeriesTitle: TCrGraphTextType;
Typc
TCrGraphTextType = string[128];
Dcscriptiun
The SeriesTitle property specifies the title of the Series which is being graphed.
fxampIc
The following example retrieves the GraphText information from the Report, then changes the SeriesTitle for
the first Graph:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
if Crpe1.GraphText.Count > 0 then
Crpe1.GraphText[0].SeriesTitle := 'New Series Title';
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce !!4
GraphTcxt SubTitIc prupcrty
DccIaratiun
property SubTitle: TCrGraphTextType;
Typc
TCrGraphTextType = string[128];
Dcscriptiun
The SubTitle property specifies the sub title text that will appear directly under the main Title.
fxampIc
The following example retrieves the GraphText information from the Report, then changes the SubTitle for the
first Graph:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
if Crpe1.GraphText.Count > 0 then
Crpe1.GraphText[0].SubTitle := 'New Sub Title';
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphTcxt TitIc prupcrty
DccIaratiun
property Title: TCrGraphTextType;
Typc
TCrGraphTextType = string[128];
Dcscriptiun
The Title property specifies the main title text that will appear above the Graph.
VCI Re|etetce !!S
fxampIc
The following example retrieves the GraphText information from the Report, then changes the Title for the
first Graph:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
if Crpe1.GraphText.Count > 0 then
Crpe1.GraphText[0].Title := 'New Title';
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphTcxt XAxisTitIc prupcrty
DccIaratiun
property XAxisTitle: TCrGraphTextType;
Typc
TCrGraphTextType = string[128];
Dcscriptiun
The XAxisTitle property specifies the title text that will appear for the X axis. Not valid for Pie graphs.
fxampIc
The following example retrieves the GraphText information from the Report, then changes the XAxisTitle for
the first Graph:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
if Crpe1.GraphText.Count > 0 then
Crpe1.GraphText[0].XAxisTitle := 'New XAxis Title';
Crpe1.Output := toWindow;
Crpe1.Execute;}
GraphTcxt YAxisTitIc prupcrty
DccIaratiun
property YAxisTitle: TCrGraphTextType;
VCI Re|etetce !!6
Typc
TCrGraphTextType = string[128];
Dcscriptiun
The YAxisTitle property specifies the title text that will appear for the Y axis. Not valid for Pie graphs.
fxampIc
The following example retrieves the GraphText information from the Report, then changes the YAxisTitle for
the first Graph:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
if Crpe1.GraphText.Count > 0 then
Crpe1.GraphText[0].YAxisTitle := 'New YAxis Title';
Crpe1.Output := toWindow;
Crpe1.Execute;
GraphTcxt ZAxisTitIc prupcrty
DccIaratiun
property ZAxisTitle: TCrGraphTextType;
Typc
TCrGraphTextType = string[128];
Dcscriptiun
The ZAxisTitle property specifies the title text that will appear for the Z axis. This value is only valid for 3D
graphs.
fxampIc
The following example retrieves the GraphText information from the Report, then changes the ZAxisTitle for
the first Graph:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
if Crpe1.GraphText.Count > 0 then
Crpe1.GraphText[0].ZAxisTitle := 'New ZAxis Title';
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce !!7
GraphTcxt Mcthuds
GraphTcxt Add mcthud
DccIaratiun
procedure Add(GraphNumber: TCrGraphTextNumber);
Typc
TCrGraphTextNumber = integer;
Dcscriptiun
The Add method adds an item to the GraphText object and sets the internal index to that item. It requires a
Graph number as a parameter, which should be a number corresponding to a Graph in the Report. Graphs are
numbered starting from zero, from the top of the Report down, and left to right in each Section. If the Add
method is used, the steps to using GraphText are:
1 Add an item to the GraphText object (you must specify the Graph number).
2 Fill the item's properties (Title, SubTitle, etc.) with values.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
Grah numbers are correcl lor lhe currenl Reorl.
fxampIc
The Add method can be used to manually add an item to the GraphText object, instead of using Retrieve:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Graph number - must be same as in Report}
Crpe1.GraphText.Add(0);
{Section must also be specified when using Add}
Crpe1.GraphText.Section := 'PH';
Crpe1.GraphText.Title := 'Company Graph';
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce !!8
GraphTcxt CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the GraphText 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 GraphText object of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the GraphText of all the Subreports will require a looping procedure
that goes through each Subreport and applies the Clear method.
fxampIc
This code clears the GraphText properties for the main Report (assuming the default state of Subreports[0]):
Crpe1.GraphText.Clear;
This code clears the GraphText properties for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.GraphText.Clear;
end;
GraphTcxt CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeGraphText): boolean;
Dcscriptiun
The CopyFrom method copies the GraphText property values from another TCrpeGraphText object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
VCI Re|etetce !!0
fxampIc
The following example copies all the GraphText property values to a temporary TCrpeGraphText object:
var
tempGraphText : TCrpeGraphText;
begin
tempGraphText := TCrpeGraphText.Create;
tempGraphText.CopyFrom(Crpe1.GraphText);
{...later, when finished with the temp object...}
tempGraphText.Free;
end;
GraphTcxt Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the GraphText object. It is handy for
setting up loops to make similar changes to each item.
fxampIc
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.GraphText.Retrieve;
for cnt := 0 to (Crpe1.GraphText.Count - 1) do
Crpe1.GraphText[cnt].Title := 'Company Graph';
end;
GraphTcxt Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the GraphText object, and does not
need to be called in code.
VCI Re|etetce !46
GraphTcxt DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the GraphText object. The "nIndex" parameter
represents the number of the item in the GraphText object.
fxampIc
The Delete method can be used to manually remove an item from the GraphText object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Graph number - must be same as in Report}
Crpe1.GraphText.Add(0);
{Section must also be specified when using Add}
Crpe1.GraphText.Section := 'PH';
Crpe1.GraphText.Title := 'Company Graph';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.GraphText.Delete(0);
GraphTcxt Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
GraphTcxt Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
VCI Re|etetce !41
Dcscriptiun
The Retrieve method obtains the GraphText information from the Report and stores it in the GraphText object.
If no GraphText information was found, the call returns False. Be aware that calling Retrieve will first cause
the GraphText object to be cleared, so any current information stored in it will be removed.
NO7F: Snce lhe Grah7exl objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe Grah7exl
lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl lo oblan
lhe Grah7exl nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle lhrough lhe
Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale Grah7exl nlormalon lor each
Subreorl (see Fxamle).
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.GraphText.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
GraphTcxt ScctiunTypc mcthud
DccIaratiun
function SectionType: string;
Dcscriptiun
The SectionType method returns the Section Code without the subsection specifier. In other words, if the
Section Code for an item is GH1ac, the SectionType method would return GH; if the SectionCode is Da, the
SectionType method would return D.
VCI Re|etetce !42
The primary use for this method is to apply changes to all the Sections in an area, regardless of the sub-section
specifier. See the Example for an illustration.
fxampIc
The following example uses the SectionType method to apply conditional changes to Graphs. In this case,
there is a Graph in each of three sections (RH, GH1a, GH2a). Only the Graphs in the Group Headers should
be changed, so the SectionType method can be used in an expression to apply the changes:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphText.Retrieve;
for cnt := 0 to (Crpe1.GraphText.Count - 1) do
begin
{if the SectionType is GroupHeader, apply the change}
if (Crpe1.GraphText[cnt].SectionType = 'GH') then
Crpe1.GraphText[cnt].Title := 'Company Graph';
end;
end;
GraphTcxt Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the GraphText 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.
fxampIc
In this example, the GraphText settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.GraphText.Send;
VCI Re|etetce !4!
GraphTypc Prupcrtics
GraphTypc ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeGraphType;
Dcscriptiun
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 various items stored in the GraphType object, allowing the
object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript:
GraphType[2] is the same as GraphType.Item[2].
G Item returns a reference to itself, so the GraphType properties can be used right after the subscript:
GraphType[2].Style := SideBySide;
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphType.Retrieve;
{Set GraphType object to the 2nd graph}
Crpe1.GraphType.Item[1];
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphType.Retrieve;
{Set GraphType object to the 2nd graph}
Crpe1.GraphType[1];
GraphTypc ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current GraphType item number, or
set the GraphType object to another item.
VCI Re|etetce !44
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 (GraphType[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the GraphType object is pointing
to the first GraphType item:
if Crpe1.GraphType.ItemIndex <> 0 then
Crpe1.GraphType[0];
GraphTypc Numbcr prupcrty
DccIaratiun
property Number: TCrGraphTypeNumber;
Typc
TCrGraphTypeNumber = integer;
Dcscriptiun
The Number property specifies the Graph Number.
G If the Retrieve method is used to fill the GraphType object with information from the Report, each
GraphType item will have a unique Graph Number assigned by the VCL.
G If the manual Add method is used instead, a Graph number will have to be specified which corresponds
to the Print Engine method of numbering Graphs (see How Graphs are Numbered, Page 37).
The primary use of the Number property is as a look-up to point the GraphType object to the item with the
Graph number specified. The default array property, Item, however, provides an easier way to navigate
through the object.
fxampIc
This example retrieves the GraphType information from the Report and then changes the Style to 3D Bars:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphType.Retrieve;
if Crpe1.GraphType.Count > 0 then
VCI Re|etetce !4S
begin
{Set the GraphType object to Graph number 0}
Crpe1.GraphType.Number := 0;
Crpe1.GraphType.Style := ThreeDBars;
Crpe1.Execute;
end;
GraphTypc Scctiun prupcrty
DccIaratiun
property Section: string;
Dcscriptiun
The Section property contains the Section name of the item that the GraphType object is currently pointed to.
It indicates in which Section of the Report that the Graph is located.
Note that you cannot move a Graph from one Section to another by changing this property. It should primarily
be used as a read-only property after the GraphType information has been retrieved with the Retrieve method.
If the manual Add method is used to add items to the GraphType object, then Section will have to be assigned
the correct value in code.
The Section name syntax is the same as the Short Section Names used in the Crystal Reports Designer:
RH - Report Header
PH - Page Header
GH - Group Header
D - Details
GF - Group Footer
PF - Page Footer
RF - Report Footer
Lower-case letters: a, b, c, etc. are used to specify sub-sections. Numbers are used to designate different
Groups: GH1, GF2, etc. See About Section Names, Volume 1, Chapter 7, for more details on the syntax.
fxampIc
This example retrieves the GraphType information from the Report and then changes the Style to 3D Bars only
for those Graphs that reside in the Page Header:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphType.Retrieve;
for cnt := 0 to (Crpe1.GraphType.Count - 1) do
begin
if Crpe1.GraphType[cnt].Section = 'PH' then
Crpe1.GraphType[cnt].Style := ThreeDBars;
end;
Crpe1.Execute;
VCI Re|etetce !46
GraphTypc ScctiunAsCudc prupcrty
DccIaratiun
property SectionAsCode: smallint;
Dcscriptiun
The SectionAsCode property can be used to read and write the Section property via Print Engine Section Code
numbers. Since the Print Engine Section Codes are numeric, it is easier to use them in mathematical
expressions or relationships than to the actual Section names (GH1b, etc.).
See also: About Section Names, Volume 1, Chapter 7.
fxampIc
The following example uses the SectionAsCode property to apply conditional changes to Graphs. In this case,
there is a Graph in each of three Group Header sections (GH1a, GH2a, GH3a). Since the Section Code for GH1a
is 3000, GH2a is 3001, and GH3a is 3002, it is possible to do a simple mathematical calculation on the remainder
of the Section Code divided by 1000 to change the style of the Graphs only if it is not in GH1:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphType.Retrieve;
for cnt := 0 to (Crpe1.GraphType.Count - 1) do
begin
{if the remainder of the SectionCode divided by 1000
is greater than zero, then apply the change}
if (Crpe1.GraphType[cnt].SectionAsCode mod 1000 > 0) then
Crpe1.GraphType[cnt].Style := Pie;
end;
end;
GraphTypc StyIc prupcrty
DccIaratiun
property Style: TCrGraphType;
Typc
TCrGraphType = (SideBySide, ThreeDSide, StackedBar, ThreeDStacked, PercentBar,
ThreeDPercent, Line, Area, ThreeDBars, Pie, MultiplePie, WeightedPie,
UserDefined, UnknownGraph);
VCI Re|etetce !47
Dcscriptiun
The Style property determines the type of Graph that will be displayed in the Report. The different Styles are
illustrated below:
The UserDefined and UnknownGraph types represent the following:
UserDefined - The Graph has been edited in PG Editor. Some of the Graph changes via the VCL
may not affect options that have been customized in PG Editor.
UnknownGraph - The Print Engine cannot recognize the Graph. This shouldn't happen, but if it does, it is
likely that changes to the Graph via the VCL may not work properly. In this case, the
Report should be opened in Crystal Reports and re-saved, or the Graph should
be re-inserted.
fxampIc
This example retrieves the GraphType information from the Report and then changes the Style to 3D Bars:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphType.Retrieve;
if Crpe1.GraphType.Count > 0 then
begin
Crpe1.GraphType[0].Style := ThreeDBars;
Crpe1.Execute;
end;
VCI Re|etetce !48
GraphTypc Mcthuds
GraphTypc Add mcthud
DccIaratiun
procedure Add(GraphNumber: TCrGraphTypeNumber);
Typc
TCrGraphTypeNumber = integer;
Dcscriptiun
The Add method adds an item to the GraphType object and sets the internal index to that item. It requires a
Graph number as a parameter, which should be a number corresponding to a Graph in the Report. Graphs are
numbered starting from zero, from the top of the Report down, and left to right in each Section. If the Add
method is used, the steps to using GraphType are:
1 Add an item to the GraphType object (you must specify the Graph number).
2 Fill the item's properties (Section, Style, etc.) with values.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
Grah numbers are correcl lor lhe currenl Reorl.
fxampIc
The Add method can be used to manually add an item to the GraphType object, instead of using Retrieve:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Graph number - must be same as in Report}
Crpe1.GraphType.Add(0);
{Section must also be specified when using Add}
Crpe1.GraphType.Section := 'PH';
Crpe1.GraphType.Style := ThreeDBars;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce !40
GraphTypc CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the GraphType 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 GraphType object of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the GraphType of all the Subreports will require a looping procedure
that goes through each Subreport and applies the Clear method.
fxampIc
This code clears the GraphType properties for the main Report (assuming the default state of Subreports[0]):
Crpe1.GraphType.Clear;
This code clears the GraphType properties for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.GraphType.Clear;
end;
GraphTypc CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeGraphType): boolean;
Dcscriptiun
The CopyFrom method copies the GraphType property values from another TCrpeGraphType object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
VCI Re|etetce !S6
fxampIc
The following example copies all the GraphType property values to a temporary TCrpeGraphType object:
var
tempGraphType : TCrpeGraphType;
begin
tempGraphType := TCrpeGraphType.Create;
tempGraphType.CopyFrom(Crpe1.GraphType);
{...later, when finished with the temp object...}
tempGraphType.Free;
end;
GraphTypc Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the GraphType object. It is handy
for setting up loops to make similar changes to each item.
fxampIc
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.GraphType.Retrieve;
for cnt := 0 to (Crpe1.GraphType.Count - 1) do
Crpe1.GraphType[cnt].Style := ThreeDBars;
end;
GraphTypc Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the GraphType object, and does not
need to be called in code.
VCI Re|etetce !S1
GraphTypc DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the GraphType object. The "nIndex" parameter
represents the number of the item in the GraphType object.
fxampIc
The Delete method can be used to manually remove an item from the GraphType object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Graph number - must be same as in Report}
Crpe1.GraphType.Add(0);
{Section must also be specified when using Add}
Crpe1.GraphType.Section := 'PH';
Crpe1.GraphType.Style := ThreeDBars;
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.GraphType.Delete(0);
GraphTypc Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
GraphTypc Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
VCI Re|etetce !S2
Dcscriptiun
The Retrieve method obtains the GraphType information from the Report and stores it in the GraphType
object. If no GraphType information was found, the call returns False. Be aware that calling Retrieve will first
cause the GraphType object to be cleared, so any current information stored in it will be removed.
NO7F: Snce lhe Grah7ye objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe Grah7ye
lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl lo oblan
lhe Grah7ye nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle lhrough lhe
Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale Grah7ye nlormalon lor each
Subreorl (see Fxamle).
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphType.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.GraphType.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
GraphTypc ScctiunTypc mcthud
DccIaratiun
function SectionType: string;
Dcscriptiun
The SectionType method returns the Section Code without the subsection specifier. In other words, if the
Section Code for an item is GH1ac, the SectionType method would return GH; if the SectionCode is Da, the
SectionType method would return D.
VCI Re|etetce !S!
The primary use for this method is to apply changes to all the Sections in an area, regardless of the sub-section
specifier. See the Example for an illustration.
fxampIc
The following example uses the SectionType method to apply conditional changes to Graphs. In this case,
there is a Graph in each of three sections (RH, GH1a, GH2a). Only the Graphs in the Group Headers should
be changed, so the SectionType method can be used in an expression to apply the changes:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GraphType.Retrieve;
for cnt := 0 to (Crpe1.GraphType.Count - 1) do
begin
{if the SectionType is GroupHeader, apply the change}
if (Crpe1.GraphType[cnt].SectionType = 'GH') then
Crpe1.GraphType[cnt].Style := Pie;
end;
end;
GraphTypc Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the GraphType 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.
fxampIc
In this example, the GraphType settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.GraphType.Send;
VCI Re|etetce !S4
GruupCunditiun Prupcrtics
GruupCunditiun Cunditiun prupcrty
DccIaratiun
property Condition: TCrGroupCondition;
Typc
TCrGroupCondition = (AnyChange, dateDaily, dateWeekly, dateBiWeekly,
dateSemiMonthly, dateMonthly, dateQuarterly, dateSemiAnnually, dateAnnually,
boolToYes, boolToNo, boolEveryYes, boolEveryNo, boolNextIsYes, boolNextIsNo);
Dcscriptiun
The Condition property determines when a new Group is begun. Groups based on Date and Boolean fields
are the only ones that have specific Condition values. All other types of fields use AnyChange as the Group
Condition value.
For Groups based on Date fields, the options are:
For Groups based on Boolean fields, the options are:
Condlon Descrlon
dateDaily Triggers a grouping for every Day.
dateWeekly Triggers a grouping for every Week.
dateBiWeekly Triggers a grouping for every second Week.
dateSemiMonthly Triggers a grouping for every half Month.
dateMonthly Triggers a grouping for every Month.
dateQuarterly Triggers a grouping for every quarter Year.
dateSemiAnnually Triggers a grouping for every half Year.
dateAnnually Triggers a grouping for every Year.
Condlon Descrlon
boolToYes Triggers a grouping every time the Group field value changes from
No to Yes.
boolToNo Triggers a grouping every time the Group field value changes from
Yes to No.
boolEveryYes Triggers a grouping every time the Group field value is Yes.
VCI Re|etetce !SS
fxampIc
The code below sets the first Group of a Report to a date field, with the condition for the Group set to "daily":
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupCondition.Retrieve;
Crpe1.GroupCondition[0].Field := '{invoice.DATE}';
Crpe1.GroupCondition[0].Condition := dateDaily;
Crpe1.GroupCondition[0].Direction := gcDescending;
Crpe1.Output := toWindow;
Crpe1.Execute;
GruupCunditiun Dircctiun prupcrty
DccIaratiun
property Direction: TCrGroupDirection;
Typc
TCrGroupDirection = (gcDescending, gcAscending, gcOriginal, gcSpecified,
gcDefault);
Dcscriptiun
The Direction property determines how the Groups will be sorted. This does not affect the sorting of records
within the Group, just the sorting of the actual Groups themselves. For example, if your grouping field is
{company.STATE} then the Direction would determine if the first group was AK (gcAscending) or WY
(gcDescending).
The five Direction options are:
boolEveryNo Triggers a grouping every time the Group field value is No.
boolNextIsYes Triggers a grouping every time the next value in the Group field is
Yes.
boolNextIsNo Triggers a grouping every time the next value in the Group field is
No.
Direction Description
gcDescending Sorts data in descending order (Z to A, 9 to 1).
gcAscending Sorts data in ascending order (A to Z, 1 to 9).
Condlon Descrlon
VCI Re|etetce !S6
NO7F: In order lo use gcSecled, lhere musl be a secled order saved wlh lhe Reorl. Secled order
requres lhe crealon ol cuslom Grous, whch cannol be done al runlme, so l lhese Grous do nol exsl,
sellng lhe Condlon lo gcSecled wll resull n error S11, "Invald Sorl Dreclon".
fxampIc
The code below sets the first Group of a Report to a date field, with the condition for the Group set to "daily",
and the direction to "descending":
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupCondition.Retrieve;
Crpe1.GroupCondition[0].Field := '{invoice.DATE}';
Crpe1.GroupCondition[0].Condition := dateDaily;
Crpe1.GroupCondition[0].Direction := gcDescending;
Crpe1.Output := toWindow;
Crpe1.Execute;
GruupCunditiun FicId prupcrty
DccIaratiun
property Field: string;
Dcscriptiun
The Field property specifies the database field or formula field that will control grouping.
G Enclose field names in braces: {company.STATE}.
G If a formula field is the grouping field, use the @ sign before the formula name: {@FormulaName}.
fxampIc
The code below sets the first Group of a Report to a date field, with the condition for the Group set to "daily",
and the direction to "descending":
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupCondition.Retrieve;
Crpe1.GroupCondition[0].Field := '{invoice.DATE}';
Crpe1.GroupCondition[0].Condition := dateDaily;
Crpe1.GroupCondition[0].Direction := gcDescending;
Crpe1.Output := toWindow;
Crpe1.Execute;
gcOriginal Sorts data in its original order.
gcSpecified Sorts data in a specified order.
gcDefault No change from current Report settings.
Direction Description
VCI Re|etetce !S7
GruupCunditiun GruupTypc prupcrty
DccIaratiun
property GroupType: TCrGroupType;
Typc
TCrGroupType = (gtOther, gtDate, gtBoolean);
Dcscriptiun
The GroupType property specifies the data type of the grouping field.
NO7F: Il s morlanl lhal lhe Grou7ye malch lhe Condlon, .e. l Grou7ye s glBoolean, lhen lhe
Condlon musl be sel lo one ol lhe Boolean condlons, or an error wll occur.
fxampIc
The code below loops through all the GroupCondition items, and when it locates an item with GroupType of
Date, then it changes the Condition that triggers the Group to "daily":
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupCondition.Retrieve;
for cnt := 0 to (Crpe1.GroupCondition.Count - 1) do
begin
if Crpe1.GroupCondition[cnt].GroupType = gtDate then
Crpe1.GroupCondition[cnt].Condition := dateDaily;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
Data Type Description
gtDate The field is of Date type.
gtBoolean The field is of Boolean type.
gtOther The field is any other data type other than Date or Boolean.
VCI Re|etetce !S8
GruupCunditiun ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeGroupCondition;
Dcscriptiun
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 GroupCondition object, allowing
the object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript:
GroupCondition[2] is the same as GroupCondition.Item[2].
G Item returns a reference to itself, so the GroupCondition properties can be used right after the subscript:
GroupCondition[2].Direction := gcAscending;
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupCondition.Retrieve;
{Set GroupCondition to the 3rd Group}
Crpe1.GroupCondition.Item[2];
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupCondition.Retrieve;
{Set GroupCondition to the 3rd Group}
Crpe1.GroupCondition[2];
GruupCunditiun ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current GroupCondition item number,
or set the GroupCondition object to another item.
VCI Re|etetce !S0
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 (GroupCondition[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the GroupCondition object is
pointing to the first GroupCondition item:
if Crpe1.GroupCondition.ItemIndex <> 0 then
Crpe1.GroupCondition[0];
GruupCunditiun Numbcr prupcrty
DccIaratiun
property Number: TCrGroupConditionNumber;
Typc
TCrGroupConditionNumber = integer;
Dcscriptiun
The Number property specifies the Group Number. Unlike most of the other properties, Number is one-based,
therefore the first Group is number one (1).
G Number is a key property, and therefore serves as a lookup; that is, assigning it a value will cause the
GroupCondition object to point to the GroupCondition item that has a Number with the same value.
G Before using the Number property to navigate through the GroupCondition, the Retrieve method
should be called, or the manual Add method.
fxampIc
This sample retrieves the GroupCondition values from the Report, and uses the Number property to set the
first Group to the {company.STATE} field:
Crpe1.ReportName := 'C:\Company.rpt';
with Crpe1.GroupCondition do
begin
Retrieve;
VCI Re|etetce !66
Number := 1;
Field := '{company.STATE}';
Condition := AnyChange;
Direction := gcAscending;
end;
Crpe1.Execute;
GruupCunditiun Mcthuds
GruupCunditiun Add mcthud
DccIaratiun
procedure Add(GroupNumber: TCrGroupConditionNumber);
Typc
TCrGroupConditionNumber = integer;
Dcscriptiun
The Add method adds an item to the GroupCondition object and sets the internal index to that item. It requires
a GroupCondition number as a parameter, which should be a number corresponding to a Group in the Report.
G Unlike most other properties, Groups are numbered starting from one (1), although the
GroupCondition object is still zero-based (i.e. GroupCondition[0].Number usually equals 1).
If the Add method is used, the steps to using GroupCondition are:
1 Add an item to the GroupCondition object (you must specify the Group number).
2 Fill the item's properties (Field, Direction, etc.) with values.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
GrouCondlon numbers are correcl lor lhe currenl Reorl.
fxampIc
The Add method can be used to manually add an item to the GroupCondition object, instead of using Retrieve.
Remember that the first Group number that can be added is 1, not 0 as in most other cases:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Group Number}
Crpe1.GroupCondition.Add(1);
Crpe1.GroupCondition.Field := '{company.STATE}';
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce !61
GruupCunditiun CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the GroupCondition 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 is only applied to the GroupCondition object of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the GroupCondition of all the Subreports will require a looping
procedure that goes through each Subreport and applies the Clear.
fxampIc
This code clears the GroupCondition properties for the main Report (assuming the default state of
Subreports[0]):
Crpe1.GroupCondition.Clear;
This code clears the GroupCondition properties for all the Subreports:
147 cnt := 1 94 (Crpe1.Subreports.Count - 1) /4
begin
Crpe1.Subreports[cnt];
Crpe1.GroupCondition.Clear;
end;
GruupCunditiun CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeGroupCondition): boolean;
Dcscriptiun
The CopyFrom method copies the GroupCondition property values from another TCrpeGroupCondition
object. It is similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
VCI Re|etetce !62
fxampIc
The following example copies all the GroupCondition property values to a temporary TCrpeGroupCondition
object:
var
tempGroupCondition : TCrpeGroupCondition;
begin
tempGroupCondition := TCrpeGroupCondition.Create;
tempGroupCondition.CopyFrom(Crpe1.GroupCondition);
{...later, when finished with the temp object...}
tempGroupCondition.Free;
end;
GruupCunditiun Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the GroupCondition object. It is
handy for setting up loops to make similar changes to each item.
fxampIc
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.GroupCondition.Retrieve;
for cnt := 0 to (Crpe1.GroupCondition.Count - 1) do
Crpe1.GroupCondition[cnt].Direction := gcAscending;
end;
GruupCunditiun Crcatc mcthud
DccIaratiun
constructor Create;
VCI Re|etetce !6!
Dcscriptiun
The Create method is used internally in the Crystal component to create the GroupCondition object, and does
not need to be called in code.
GruupCunditiun DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the GroupCondition object. The "nIndex" parameter
represents the number of the item in the GroupCondition object, not the Group number. Group numbers start
with 1, whereas the first item in the GroupCondition object is item zero (0).
NO7F: Delele wll nol remove lhe GrouCondlon lrom lhe Reorl, l wll jusl remove l lrom lhe Cryslal VCI.
fxampIc
The Delete method can be used to manually remove an item from the GroupCondition object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Group Number - must be same as in Report}
Crpe1.GroupCondition.Add(1);
Crpe1.GroupCondition.Field := '{company.STATE}';
Crpe1.Output := toWindow;
Crpe1.Execute;
{Delete an item. Note that although the Group
Number specified was 1, the item to delete is
item 0 of the GroupCondition object}
Crpe1.GroupCondition.Delete(0);
GruupCunditiun Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
VCI Re|etetce !64
GruupCunditiun Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the GroupCondition information from the Report and stores it in the
GroupCondition object. If no GroupCondition information was found, the call returns False. Be aware that
calling Retrieve will first cause the GroupCondition object to be cleared, so any current information stored in
it will be removed.
NO7F: Snce lhe GrouCondlon objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe
GrouCondlon lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you
wanl lo oblan lhe GrouCondlon nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo
sle lhrough lhe Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale
GrouCondlon nlormalon lor each Subreorl (see Fxamle).
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupCondition.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.GroupCondition.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
VCI Re|etetce !6S
GruupCunditiun Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the GroupCondition 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.
fxampIc
In this example, the GroupCondition settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.GroupCondition.Send;
GruupOptiuns Prupcrtics
GruupOptiuns Cunditiun prupcrty
DccIaratiun
property Condition : TCrGroupCondition
Typc
TCrGroupCondition = (AnyChange, dateDaily, dateWeekly, dateBiWeekly,
dateSemiMonthly, dateMonthly, dateQuarterly, dateSemiAnnually, dateAnnually,
boolToYes, boolToNo, boolEveryYes, boolEveryNo, boolNextIsYes, boolNextIsNo);
Dcscriptiun
The Condition property determines when a new Group is begun. Groups based on Date and Boolean fields
are the only ones that have specific Condition values. All other types of fields use AnyChange as the Group
Condition value.
VCI Re|etetce !66
For Groups based on Date fields, the options are:
For Groups based on Boolean fields, the options are:
fxampIc
The code below sets the first Group of a Report to a date field, with the Condition for the Group set to "daily":
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupCondition.Retrieve;
Crpe1.GroupCondition[0].Field := '{invoice.DATE}';
Crpe1.GroupCondition[0].Condition := dateDaily;
Crpe1.GroupCondition[0].Direction := gcDescending;
Crpe1.Output := toWindow;
Crpe1.Execute;
Condition Description
dateDaily Triggers a grouping for every Day.
dateWeekly Triggers a grouping for every Week.
dateBiWeekly Triggers a grouping for every second Week.
dateSemiMonthly Triggers a grouping for every half Month.
dateMonthly Triggers a grouping for every Month.
dateQuarterly Triggers a grouping for every quarter Year.
dateSemiAnnually Triggers a grouping for every half Year.
dateAnnually Triggers a grouping for every Year.
Condition Description
boolToYes Triggers a grouping every time the Group field value changes from
No to Yes.
boolToNo Triggers a grouping every time the Group field value changes from
Yes to No.
boolEveryYes Triggers a grouping every time the Group field value is Yes.
boolEveryNo Triggers a grouping every time the Group field value is No.
boolNextIsYes Triggers a grouping every time the next value in the Group field is
Yes.
boolNextIsNo Triggers a grouping every time the next value in the Group field is
No.
VCI Re|etetce !67
GruupOptiuns Dircctiun prupcrty
DccIaratiun
property Direction: TCrGroupDirection
Typc
TCrGroupDirection = (gdDescending, gdAscending, gdOriginal, gdSpecified,
gdDefault);
Dcscriptiun
The Direction property determines how the Groups will be sorted. This does not affect the sorting of records
within the Group, just the sorting of the actual Groups themselves. For example, if your grouping field is
{company.STATE} then the Direction would determine if the first group was AK (gcAscending) or WY
(gcDescending).
The five Direction options are:
NO7F: In order lo use gcSecled, lhere musl be a secled order saved wlh lhe Reorl. Secled order
requres lhe crealon ol cuslom Grous, whch cannol be done al runlme, so l lhese Grous do nol exsl,
sellng lhe Condlon lo gcSecled wll resull n error S11, "Invald Sorl Dreclon".
fxampIc
The code below sets the first Group of a Report to a date field, with the Direction to "descending":
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupCondition.Retrieve;
Crpe1.GroupCondition[0].Field := '{invoice.DATE}';
Crpe1.GroupCondition[0].Condition := dateDaily;
Crpe1.GroupCondition[0].Direction := gcDescending;
Crpe1.Output := toWindow;
Crpe1.Execute;
Direction Description
gcDescending Sorts data in descending order (Z to A, 9 to 1).
gcAscending Sorts data in ascending order (A to Z, 1 to 9).
gcOriginal Sorts data in its original order.
gcSpecified Sorts data in a specified order.
gcDefault No change from current Report settings.
VCI Re|etetce !68
GruupOptiuns FicId prupcrty
DccIaratiun
property Field: string;
Dcscriptiun
The Field property specifies the database field or formula field that will control grouping.
G Enclose field names in braces: {company.STATE}.
G If a formula field is the grouping field, use the @ sign before the formula name: {@FormulaName}.
fxampIc
This example retrieves the GroupOptions values from the Report, and uses the Field property to set the first
Group to the {company.STATE} field:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the GroupOptions from the Report}
Crpe1.GroupOptions.Retrieve;
{Assign the values for Group Number 1}
Crpe1.GroupOptions[0].Field := '{company.STATE}';
Crpe1.GroupOptions[0].Condition := AnyChange;
Crpe1.GroupOptions[0].Direction := gcAscending;
Crpe1.Output := toWindow;
Crpe1.Execute;
GruupOptiuns GruupTypc prupcrty
DccIaratiun
property GroupType: TCrGroupType
Typc
TCrGroupType = (gtOther, gtDate, gtBoolean);
VCI Re|etetce !60
Dcscriptiun
The GroupType property specifies the data type of the grouping field.
NO7F: Il s morlanl lhal lhe Grou7ye malch lhe Condlon, .e. l Grou7ye s glBoolean, lhen lhe
Condlon musl be sel lo one ol lhe Boolean condlons, or an error wll occur.
fxampIc
The code below loops through all the GroupOptions items, and when it locates an item with GroupType of
Date, then it changes the Condition that triggers the Group to "daily":
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupOptions.Retrieve;
for cnt := 0 to (Crpe1.GroupOptions.Count - 1) do
begin
if Crpe1.GroupOptions[cnt].GroupType = gtDate then
Crpe1.GroupOptions[cnt].Condition := dateDaily;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
GruupOptiuns ltcm prupcrty
DccIaratiun
property Item[nIndex: integer]: TCrpeGroupOptions
Dcscriptiun
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 GroupOptions object, allowing the object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript:
GroupOptions[2] is the same as GroupOptions.Item[2].
G Item returns a reference to itself, so the GroupOptions properties can be used right after the subscript:
GroupOptions[2].Direction := gdDescending;
Data Type Description
gtDate The field is of Date type.
gtBoolean The field is of Boolean type.
gtOther The field is any other data type other than Date or Boolean.
VCI Re|etetce !76
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupOptions.Retrieve;
{Set GroupOptions object to the 2nd item}
Crpe1.GroupOptions.Item[1];
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupOptions.Retrieve;
{Set GroupOptions object to the 2nd item}
Crpe1.GroupOptions[1];
GruupOptiuns ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current GroupOptions item number,
or set the GroupOptions 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 (GroupOptions[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the GroupOptions object is
pointing to the first GroupOptions item:
if Crpe1.GroupOptions.ItemIndex <> 0 then
Crpe1.GroupOptions[0];
VCI Re|etetce !71
GruupOptiuns kccpTugcthcr prupcrty
DccIaratiun
property KeepTogether: TCrBoolean
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The KeepTogether property encapsulates the functionality of the "Keep Group Together" option which is
available when a Group is created or modified in the Seagate Crystal Reports designer. When set to cTrue, it
prevents a Group from splitting on Page Break (if possible).
fxampIc
This example shows how to set the RepeatGH and KeepTogether properties:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupOptions.Retrieve;
for cnt := 0 to (Crpe1.GroupOptions.Count - 1) do
begin
Crpe1.GroupOptions[cnt].RepeatGH := cTrue;
Crpe1.GroupOptions[cnt].KeepTogether := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
GruupOptiuns Numbcr prupcrty
DccIaratiun
property Number: TCrGroupOptionsNumber;
Typc
TCrGroupOptionsNumber = integer;
VCI Re|etetce !72
Dcscriptiun
The Number property specifies the Group Number. Unlike most of the other properties, Number is one-based,
therefore the first Group is number one (1). This was done to be consistent with the Section naming convention
wherein the first Group Header is GH1, etc. The GroupOptions object, however, is still zero-based, thus the
first item in GroupOptions is still GroupOptions[0].
G Number is a key property, and therefore serves as a lookup; that is, assigning it a value will cause the
GroupOptions object to point to the item that has a Group Number with the same value.
G Before using the Number property to navigate through the GroupOptions, the Retrieve method should
be called, or the manual Add method.
fxampIc
This example retrieves the GroupOptions values from the Report, and uses the Number property to set the
first Group to the {company.STATE} field:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the GroupOptions from the Report}
Crpe1.GroupOptions.Retrieve;
{Set the GroupOptions object to Group Number 1}
Crpe1.GroupOptions.Number := 1;
{Assign the values for Group Number 1}
Crpe1.GroupOptions.Field := '{company.STATE}';
Crpe1.GroupOptions.Condition := AnyChange;
Crpe1.GroupOptions.Direction := gcAscending;
Crpe1.Output := toWindow;
Crpe1.Execute;
GruupOptiuns RcpcatGH prupcrty
DccIaratiun
property RepeatGH: TCrBoolean
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
RepeatGH determines whether the Group Header will repeat on each new page of the Report when the
grouped records are split over more than one page.
VCI Re|etetce !7!
fxampIc
This example shows how to set the RepeatGH and KeepTogether properties:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupOptions.Retrieve;
for cnt := 0 to (Crpe1.GroupOptions.Count - 1) do
begin
Crpe1.GroupOptions[cnt].RepeatGH := cTrue;
Crpe1.GroupOptions[cnt].KeepTogether := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
GruupOptiuns TupNDiscardOthcrs prupcrty
DccIaratiun
property TopNDiscardOthers: TCrBoolean
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The TopNDiscardOthers property determines if the TopN grouping will put all other Groups that are outside
of the TopN/BottomN selection in a Group called "Others", or if they will be discarded. If TopNDiscardOthers
is set to cTrue, the other Groups will be discarded.
fxampIc
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;
VCI Re|etetce !74
GruupOptiuns TupNGruups prupcrty
DccIaratiun
property TopNGroups: smallint
Dcscriptiun
TopNGroups specifies how many groups will be included in the TopN/BottomN selection. The TopNOptions
property must be set to either tnTopN or tnBottomN for this property to have any effect.
fxampIc
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;
GruupOptiuns TupNOptiuns prupcrty
DccIaratiun
property TopNOptions: TCrTopNOptions
Typc
TCrTopNOptions = (tnUnsorted, tnSorted, tnTopN, tnBottomN, tnDefault);
VCI Re|etetce !7S
Dcscriptiun
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:
fxampIc
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;
GruupOptiuns TupNSurtFicId prupcrty
DccIaratiun
property TopNSortField: string
Dcscriptiun
The TopNSortField property specifies the formula text of the expression that will control the TopN sorting/
selection feature.
G TopNSortField is normally a summary field, and has the same syntax and purpose as the Field property
of GroupSortFields.
G TopNOptions must be set to one of the following in order for TopNSortField to take effect:
tnSorted, tnTopN, tnBottomN.
G The TopNSortField value will cause any other GroupSortFields for the specified Group to be deleted
when the Report is run.
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.
VCI Re|etetce !76
fxampIc
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;
GruupOptiuns Mcthuds
GruupOptiuns Add mcthud
DccIaratiun
procedure Add(GroupNumber: TCrGroupOptionsNumber);
Typc
TCrGroupOptionsNumber = integer;
Dcscriptiun
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:
1 Add an item to the GroupOptions object (you must specify the Group Number).
2 Fill the item's properties (Field, Condition, etc.) with values.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
Grou numbers are correcl lor lhe currenl Reorl.
VCI Re|etetce !77
fxampIc
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;
GruupOptiuns CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
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.
fxampIc
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;
VCI Re|etetce !78
GruupOptiuns CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeGroupOptions): boolean;
Dcscriptiun
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.
fxampIc
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;
GruupOptiuns Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
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.
fxampIc
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;
VCI Re|etetce !70
GruupOptiuns Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create constructor creates the GroupOptions object. It is used internally in the VCL component to create
the GroupOptions object when the component is created, and should not be called outside of the component.
GruupOptiuns DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the GroupOptions object. The "nIndex" parameter
represents the number of the item in the GroupOptions object, which should not be confused with the Group
Number value.
fxampIc
The Delete method can be used to manually remove an item from the GroupOptions object:
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;
{Specify the item number}
Crpe1.GroupOptions.Delete(0);
GruupOptiuns Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
VCI Re|etetce !86
Dcscriptiun
The Destroy method frees the GroupOptions object. It is used internally in the VCL component to destroy the
GroupOptions object when the component is destroyed, and should not be called outside of the component.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
GruupOptiuns Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the GroupOptions information from the Report and stores it in the
GroupOptions object. If no GroupOptions information was found, the call returns False. Be aware that calling
Retrieve will first cause the GroupOptions object to be cleared, so any current information stored in it will be
removed.
NO7F: Snce lhe GrouOlons objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe
GrouOlons lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you
wanl lo oblan lhe GrouOlons nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo
sle lhrough lhe Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale GrouOlons
nlormalon lor each Subreorl (see Fxamle).
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupOptions.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
VCI Re|etetce !81
begin
Crpe1.Subreports[cnt];
Crpe1.GroupOptions.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
GruupOptiuns Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the GroupOptions 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.
fxampIc
In this example, the GroupOptions settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.GroupOptions.Send;
GruupScIcctiun Prupcrtics
GruupScIcctiun FurmuIa prupcrty
DccIaratiun
property Formula: TCrpeString;
Typc
TCrpeString = class(TStringList)
VCI Re|etetce !82
Dcscriptiun
The Formula property specifies the actual GroupSelection Formula text.
When the Replace property is set to False, the GroupSelection Formula that is passed in to the Report is
appended with a Boolean "AND" to any characters in the GroupSelection Formula currently in the Report.
This includes comment lines (any text on a line with two forward slashes in front of it) and existing
GroupSelection Formulas. Therefore, care must be taken to make sure the GroupSelection Formula in the
Report is valid. When in doubt, use the Retrieve method and build the whole statement in Delphi, then replace
the current GroupSelection, by setting Replace to True.
See also: Using Variables with GroupSelection Formula, Page 44
fxampIc
The following example retrieves the current Group Selection Formula from the Report and adds an OR
condition:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the GroupSelection}
Crpe1.GroupSelection.Retrieve;
{Add an OR condition}
Crpe1.GroupSelection.Formula.Add(' OR
Maximum({company.BRANCHES},{company.STATE}) > 12');
{Replace the GroupSelection in the Report with the new one}
Crpe1.GroupSelection.Replace := True;
{Check the GroupSelection before running Report}
if Crpe1.GroupSelection.Check then
begin
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
GruupScIcctiun RcpIacc prupcrty
DccIaratiun
property Replace: boolean;
Dcscriptiun
The Replace property determines if the Group Selection Formula sent from the VCL will replace the one that
is already in the Report (if there is one), or if it will be ANDed on to the end. For example, if there is a Selection
Formula in the Report that reads:
{company.STATE} = "WA"
VCI Re|etetce !8!
And there is a Selection Formula in the VCL that reads:
{company.SALES} = 100000
If Replace is True, the Selection Formula in the Report (when it is run) will read:
{company.SALES} = 100000
If Replace is False, the Selection Formula in the Report (when it is run) will read:
{company.STATE} = "WA" AND {company.SALES} = 100000
By default, Replace is set to True.
fxampIc
The following example retrieves the current Group Selection Formula from the Report and adds an OR
condition. It then sends the Formula back in, replacing the one that is currently there:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the GroupSelection}
Crpe1.GroupSelection.Retrieve;
{Add an OR condition}
Crpe1.GroupSelection.Formula.Add(' OR
Maximum({company.BRANCHES},{company.STATE}) > 12');
{Replace the GroupSelection in the Report with the new one}
Crpe1.GroupSelection.Replace := True;
{Check the GroupSelection before running Report}
if Crpe1.GroupSelection.Check then
begin
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
GruupScIcctiun Mcthuds
GruupScIcctiun Chcck mcthud
DccIaratiun
function Check: boolean;
Dcscriptiun
The Check method can be used to check the syntax of a GroupSelection Formula before running the Report.
Check returns a boolean value:
True :GroupSelection Formula is good.
False :GroupSelection Formula has an error.
VCI Re|etetce !84
fxampIc
The following example retrieves the current Group Selection Formula from the Report and adds an OR
condition. It then sends the Formula back in, checking for the proper syntax:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the GroupSelection}
Crpe1.GroupSelection.Retrieve;
{Add an OR condition}
Crpe1.GroupSelection.Formula.Add(' OR
Maximum({company.BRANCHES},{company.STATE}) > 12');
{Replace the GroupSelection in the Report with the new one}
Crpe1.GroupSelection.Replace := True;
{Check the GroupSelection before running Report}
if Crpe1.GroupSelection.Check then
begin
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
GruupScIcctiun CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the GroupSelection object. It clears the Formula property
and sets the Replace property to True. 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 GroupSelection object of the current Report/Subreport specified in
the Subreports object. Therefore, to clear all the GroupSelection of all the Subreports will require a looping
procedure that goes through each Subreport and applies the Clear method.
fxampIc
This code clears the GroupSelection for the main Report (assuming the default state of Subreports[0]):
Crpe1.GroupSelection.Clear;
This code clears the GroupSelection for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.GroupSelection.Clear;
end;
VCI Re|etetce !8S
GruupScIcctiun CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeGroupSelectionFormula): boolean;
Dcscriptiun
The CopyFrom method copies the GroupSelection property values from another
TCrpeGroupSelectionFormula object. It is similar to Delphi's Assign method. It is useful for transferring or
temporary storage of values.
fxampIc
The following example copies all the GroupSelection property values to a temporary
TCrpeGroupSelectionFormula object:
var
tempGroupSelection : TCrpeGroupSelectionFormula;
begin
tempGroupSelection := TCrpeGroupSelectionFormula.Create;
tempGroupSelection.CopyFrom(Crpe1.GroupSelection);
{...later, when finished with the temp object...}
tempGroupSelection.Free;
03/;
GruupScIcctiun Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the GroupSelection object, and does
not need to be called in code.
VCI Re|etetce !86
GruupScIcctiun Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
GruupScIcctiun Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the Group Selection Formula from the Report and stores it in the Formula
property of the GroupSelection object. If successful, the call returns True. Be aware that calling Retrieve will
first cause the GroupSelection object to be cleared, so any current information stored in it will be removed and
the Replace property will be set back to default.
NO7F: Snce lhe GrouSeleclon objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe
GrouSeleclon lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you
wanl lo oblan lhe GrouSeleclon nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo
sle lhrough lhe Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale GrouSeleclon
nlormalon lor each Subreorl (see Fxamle).
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupSelection.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
VCI Re|etetce !87
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.GroupSelection.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
GruupScIcctiun Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the GroupSelection 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.
fxampIc
In this example, the GroupSelection settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.GroupSelection.Send;
GruupSurtFicIds Prupcrtics
GruupSurtFicIds DcIctcGSF prupcrty
DccIaratiun
property DeleteGSF: boolean;
VCI Re|etetce !88
Dcscriptiun
The DeleteGSF property can be used to remove a GroupSortField from a Report. The GroupSortField is not
actually removed from the Report until the Execute method is called. After Execute is called, the
GroupSortField is also removed from the VCL.
NO7F: DeleleGSF s nol lhe same as Delele. Delele removes a GrouSorlFeld lem lrom lhe GrouSorlFelds
objecl, nol lrom lhe Reorl.
fxampIc
This example will remove the second GroupSortField from a Report when that Report is run:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupSortFields.Retrieve;
Crpe1.GroupSortFields[1].DeleteGSF := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
GruupSurtFicIds Dircctiun prupcrty
DccIaratiun
property Direction: TCrSortDirection;
Typc
TCrSortDirection = (sdDescending, sdAscending, sdDefault);
Dcscriptiun
The Direction property determines the Sort Order, which can either be sdDescending (9..0, Z..A), sdAscending
(0..9, A..Z), or sdDefault (no change).
fxampIc
This example changes the Sort Order of the first GroupSortField to ascending:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupSortFields.Retrieve;
Crpe1.GroupSortFields[0].Direction := sdAscending;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce !80
GruupSurtFicIds FicId prupcrty
DccIaratiun
property Field: string;
Dcscriptiun
The Field property specifies the summary field that will control sorting. Summary fields are usually
constructed in this fashion:
SummaryFunction(DatabaseField,GroupingField)
so they usually look something like this:
Sum({company.SALES},{company.STATE})
This would read: "Sum of the Company's Sales per State". The last parameter must be a field that the Report
is grouped on.
G Enclose field names in braces: {company.STATE}.
G If a formula field is the grouping field, use the @ sign before the formula name: {@FormulaName}.
fxampIc
This example changes the second GroupSortField:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupSortFields.Retrieve;
Crpe1.GroupSortFields[1].Field := 'Sum({company.SALES},{company.STATE})';
Crpe1.Output := toWindow;
Crpe1.Execute;
GruupSurtFicIds ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeGroupSortFields;
VCI Re|etetce !06
Dcscriptiun
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 GroupSortFields object, allowing
the object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript:
GroupSortFields[2] is the same as GroupSortFields.Item[2].
G Item returns a reference to itself, so the GroupSortFields properties can be used right after the subscript:
GroupSortFields[2].Direction := sdAscending;
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupSortFields.Retrieve;
{Set GroupSortFields object to the 3rd item}
Crpe1.GroupSortFields.Item[2];
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupSortFields.Retrieve;
{Set GroupSortFields object to the 3rd item}
Crpe1.GroupSortFields[2];
GruupSurtFicIds ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current GroupSortFields item number,
or set the GroupSortFields 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 (GroupSortFields[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.
VCI Re|etetce !01
fxampIc
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];
GruupSurtFicIds Numbcr prupcrty
DccIaratiun
property Number: TCrGroupSortFieldsNumber;
Typc
TCrGroupSortFieldsNumber = integer;
Dcscriptiun
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.
fxampIc
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;
GruupSurtFicIds Mcthuds
GruupSurtFicIds Add mcthud
DccIaratiun
procedure Add(GroupSortFieldNumber: TCrGroupSortFieldsNumber);
VCI Re|etetce !02
Typc
TCrGroupSortFieldsNumber = integer;
Dcscriptiun
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:
1 Add an item to the GroupSortFields object (you must specify the GroupSortField number).
2 Fill the item's properties (Field, Direction, etc.) with values.
3 When 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.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
GrouSorlFeld numbers are correcl lor lhe currenl Reorl. However, lor addng new GrouSorlFelds lhal
are nol currenlly n lhe Reorl, lhe Add melhod musl be used.
fxampIc
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
VCI Re|etetce !0!
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;
GruupSurtFicIds CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
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.
fxampIc
This code clears the GroupSortFields properties for the main Report (assuming the default state of
Subreports[0]):
Crpe1.GroupSortFields.Clear;
VCI Re|etetce !04
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;
GruupSurtFicIds CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeGroupSortFields): boolean;
Dcscriptiun
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.
,250
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;
GruupSurtFicIds Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
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.
VCI Re|etetce !0S
fxampIc
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.GroupSortFields.Retrieve;
for cnt := 0 to (Crpe1.GroupSortFields.Count - 1) do
Crpe1.GroupSortFields[cnt].Direction := sdDescending;
end;
GruupSurtFicIds Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the GroupSortFields object, and does
not need to be called in code.
GruupSurtFicIds DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the GroupSortFields object. The "nIndex" parameter
represents the number of the item in the GroupSortFields object, which may not be the same as the
GroupSortFields Number value.
NO7F: Delele wll nol remove lhe GrouSorlFeld lrom lhe Reorl, l wll jusl remove l lrom lhe Cryslal VCI.
Sel lhe DeleleGSF roerly lo remove a GrouSorlFeld lrom lhe Reorl.
VCI Re|etetce !06
fxampIc
The Delete method can be used to manually remove an item from the GroupSortFields object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify a GroupSortFields Number}
Crpe1.GroupSortFields.Add(0);
Crpe1.GroupSortFields.Field := 'Sum({company.SALES},{company.STATE})';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.GroupSortFields.Delete(0);
GruupSurtFicIds Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
GruupSurtFicIds Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the GroupSortFields from the Report and stores them in the GroupSortFields
object. If no GroupSortFields were found, the call returns False. Be aware that calling Retrieve will first cause
the GroupSortFields object to be cleared, so any current information stored in it will be removed.
NO7F: Snce lhe GrouSorlFelds objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe
GrouSorlFelds lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you
wanl lo oblan lhe GrouSorlFelds nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo
sle lhrough lhe Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale
GrouSorlFelds nlormalon lor each Subreorl (see Fxamle).
VCI Re|etetce !07
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.GroupSortFields.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.GroupSortFields.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
GruupSurtFicIds Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the GroupSortFields 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.
fxampIc
In this example, the GroupSortFields settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.GroupSortFields.Send;
VCI Re|etetce !08
lugOnlnfu Prupcrtics
lugOnlnfu DatabascNamc prupcrty
DccIaratiun
property DatabaseName: string;
Dcscriptiun
This property contains the name of the Database being connected to. Most SQL Servers require this parameter
(Oracle is usually an exception to the rule).
fxampIc
This example shows how to retrieve LogOn information and then set it for each item:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.LogOnInfo.Retrieve;
for cnt := 0 to (Crpe1.LogOnInfo.Count - 1) do
begin
Crpe1.LogOnInfo[cnt].ServerName := 'Enterprise';
Crpe1.LogOnInfo[cnt].UserID := 'Kirk';
Crpe1.LogOnInfo[cnt].Password := 'captain';
Crpe1.LogOnInfo[cnt].DatabaseName := 'stats';
end;
Crpe1.Execute;
end;
lugOnlnfu DcscriptivcNamc prupcrty
DccIaratiun
property DescriptiveName: string;
Dcscriptiun
DescriptiveName is a runtime, read-only property that contains descriptive information about the Table that
the LogOnInfo item applies to. It will only have a value if the Retrieve method was used. The DLLName, and
TableType properties also provide more details that describe the Table.
VCI Re|etetce !00
If the Report uses one of Crystal's native SQL drivers to connect to the Table, the DescriptiveName will be
something like this:
Oracle7 SQL
Microsoft SQL Server
If the Report uses an ODBC driver to connect to the Table, the DescriptiveName will be the ODBC Data Source
name with "ODBC - " prefixed to it:
ODBC - OracleTest
ODBC - Interbase
fxampIc
The following code shows how to obtain the table description information from the LogOnInfo object:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.LogOnInfo.Retrieve;
if Crpe1.LogOnInfo.Count > 0 then
begin
Edit1.Text := Crpe1.LogOnInfo[0].TableType;
Edit2.Text := Crpe1.LogOnInfo[0].DescriptiveName;
Edit3.Text := Crpe1.LogOnInfo[0].DLLName;
end;
end;
lugOnlnfu DllNamc prupcrty
DccIaratiun
property DLLName: string;
Dcscriptiun
DLLName is a runtime, read-only property that contains descriptive information about the Table that the
LogOnInfo item applies to. It will only have a value if the Retrieve method was used. The DescriptiveName,
and TableType properties also provide more details that describe the Table.
If the Report uses one of Crystal's native SQL drivers to connect to the Table, the DLLName will be something
like this:
pdsora7.dll {Oracle}
pdssql.dll {MS SQL Server}
If the Report uses an ODBC driver to connect to the Table, the DLLName will be:
pdsodbc.dll
VCI Re|etetce 466
fxampIc
The following code shows how to obtain the table description information from the LogOnInfo object:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.LogOnInfo.Retrieve;
if Crpe1.LogOnInfo.Count > 0 then
begin
Edit1.Text := Crpe1.LogOnInfo[0].TableType;
Edit2.Text := Crpe1.LogOnInfo[0].DescriptiveName;
Edit3.Text := Crpe1.LogOnInfo[0].DLLName;
end;
end;
lugOnlnfu ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeLogOnInfo;
Dcscriptiun
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 various items stored in the LogOnInfo object, allowing the
object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript: LogOnInfo[2] is
the same as LogOnInfo.Item[2].
G Item returns a reference to itself, so the LogOnInfo properties can be used right after the subscript:
LogOnInfo[2].DatabaseName := 'MyDatabase';
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.LogOnInfo.Retrieve;
{Set LogOnInfo to the 3rd Table}
Crpe1.LogOnInfo.Item[2];
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.LogOnInfo.Retrieve;
{Set LogOnInfo to the 3rd Table}
Crpe1.LogOnInfo[2];
VCI Re|etetce 461
lugOnlnfu ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current LogOnInfo item number, or set
the LogOnInfo 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 (LogOnInfo[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the LogOnInfo object is pointing
to the first LogOnInfo item:
if Crpe1.LogOnInfo.ItemIndex <> 0 then
Crpe1.LogOnInfo[0];
lugOnlnfu Passwurd prupcrty
DccIaratiun
property Password: string;
Dcscriptiun
The Password property contains the user password required for logging on to a SQL Server. This is not stored
in the Report when it is saved (and therefore will not be returned by the Retrieve method), but must be
provided before running the Report.
VCI Re|etetce 462
fxampIc
This example shows how to retrieve LogOn information and then set it for each item:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.LogOnInfo.Retrieve;
for cnt := 0 to (Crpe1.LogOnInfo.Count - 1) do
begin
Crpe1.LogOnInfo[cnt].ServerName := 'Enterprise';
Crpe1.LogOnInfo[cnt].UserID := 'Kirk';
Crpe1.LogOnInfo[cnt].Password := 'captain';
Crpe1.LogOnInfo[cnt].DatabaseName := 'stats';
end;
Crpe1.Execute;
end;
lugOnlnfu ScrvcrNamc prupcrty
DccIaratiun
property ServerName: string;
Dcscriptiun
This property contains the name of the Server being connected to.
G If the Report was created using Crystal's native SQL drivers, this will be the actual Server name.
G If the Report was created using ODBC drivers, this will be the ODBC Data Source Name.
fxampIc
This example shows how to retrieve LogOn information and then set it for each item:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.LogOnInfo.Retrieve;
for cnt := 0 to (Crpe1.LogOnInfo.Count - 1) do
begin
Crpe1.LogOnInfo[cnt].ServerName := 'Enterprise';
VCI Re|etetce 46!
Crpe1.LogOnInfo[cnt].UserID := 'Kirk';
Crpe1.LogOnInfo[cnt].Password := 'captain';
Crpe1.LogOnInfo[cnt].DatabaseName := 'stats';
end;
Crpe1.Execute;
end;
lugOnlnfu TabIc prupcrty
DccIaratiun
property Table: TCrLogOnInfoTable;
Typc
TCrLogOnInfoTable = integer;
Dcscriptiun
The Table property contains the number of the Table in the LogOnInfo item. It uses a zero-based numbering
scheme, so the first Table in a Report is number 0. The Table property is the key lookup property for the
LogOnInfo object and therefore cannot be changed by direct assignment. For example:
Crpe1.LogOnInfo.Table := 2;
will cause the LogOnInfo object to look up and move to the item with a Table value of 2 (if the Retrieve method
was used to fill LogOnInfo, this would normally be the 3rd item). It will not overwrite the current Table
property with a new Table number.
fxampIc
This example illustrates the use of the Table property. Since the Retrieve method is used, we can be sure that
the first item has a Table number of zero, the second item has a Table number of one, etc.:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.LogOnInfo.Retrieve;
for cnt := 0 to (Crpe1.LogOnInfo.Count - 1) do
begin
{Set LogOnInfo to a specific item}
Crpe1.LogOnInfo.Table := cnt;
{Set the other properties for that item}
Crpe1.LogOnInfo.ServerName := 'Enterprise';
VCI Re|etetce 464
Crpe1.LogOnInfo.UserID := 'Kirk';
Crpe1.LogOnInfo.Password := 'captain';
Crpe1.LogOnInfo.DatabaseName := 'stats';
end;
Crpe1.Execute;
end;
lugOnlnfu TabIcTypc prupcrty
DccIaratiun
property TableType: TCrTableType;
Typc
TCrTableType = (ttUnknown, ttStandard, ttSQL);
Dcscriptiun
TableType is a runtime, read-only property that contains descriptive information about the Table that the
LogOnInfo item applies to. It will only have a value if the Retrieve method was used. The DLLName, and
DescriptiveName properties also provide more details that describe the Table.
TableType will be one of the following:
fxampIc
The following code shows how to obtain the table description information from the LogOnInfo object:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.LogOnInfo.Retrieve;
if Crpe1.LogOnInfo.Count > 0 then
begin
Edit1.Text := Crpe1.LogOnInfo[0].TableType;
Edit2.Text := Crpe1.LogOnInfo[0].DescriptiveName;
Edit3.Text := Crpe1.LogOnInfo[0].DLLName;
end;
end;
Table Type Description
ttSQL The Table is an SQL-type table, or a Table being accessed via ODBC.
ttStandard The Table is a PC-Type database (dBase, FoxPro, Access, Paradox,
etc.) using native database connections, for example, not via ODBC).
ttUnknown The TableType could not be identified.
VCI Re|etetce 46S
lugOnlnfu UscrlD prupcrty
DccIaratiun
property UserID: string;
Dcscriptiun
This property contains the user name required to log on to the SQL Server.
fxampIc
This example shows how to retrieve LogOn information and then set it for each item:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.LogOnInfo.Retrieve;
for cnt := 0 to (Crpe1.LogOnInfo.Count - 1) do
begin
Crpe1.LogOnInfo[cnt].ServerName := 'Enterprise';
Crpe1.LogOnInfo[cnt].UserID := 'Kirk';
Crpe1.LogOnInfo[cnt].Password := 'captain';
Crpe1.LogOnInfo[cnt].DatabaseName := 'stats';
end;
Crpe1.Execute;
end;
lugOnlnfu Mcthuds
lugOnlnfu Add mcthud
DccIaratiun
procedure Add(TableNumber: TCrLogOnInfoTable);
Typc
TCrLogOnInfoTable = integer;
VCI Re|etetce 466
Dcscriptiun
The Add method adds an item to the LogOnInfo object and sets the LogOnInfo internal index to that item. It
requires a Table number as a parameter, which should be a number corresponding to a Table in the Report.
Tables are numbered starting from zero. If the Add method is used, the steps to using LogOnInfo are:
1 Add an item to the LogOnInfo object (you must specify the Table number).
2 Fill the item's properties (ServerName, Password, etc.) with values.
3 When Execute is called, the properties will be sent to the Print Engine. Test can be used beforehand to
check the connection.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
7able numbers are correcl lor lhe currenl Reorl.
fxampIc
The following code illustrates the use of the Add and Delete methods to run a Report twice, each time with
different LogOn information (it is assumed in the example that there is only one table in the Report):
Crpe1.ReportName := 'C:\Company.rpt';
with Crpe1.LogOnInfo do
begin
Add(0); {Add a LogOnInfo item, first Table}
ServerName := 'oracleserver';
UserID := 'SCOTT';
Password := 'tiger';
DatabaseName := ''; {Not usually req'd for Oracle}
end;
Crpe1.Execute;
while not Crpe1.PrintEnded do
Application.ProcessMessages;
Crpe1.LogOnInfo.Delete(0);
with Crpe1.LogOnInfo do
begin
Add(0); {Add a LogOnInfo item, first Table}
ServerName := 'oracleserver2';
UserID := 'JACOB';
Password := 'zebra';
DatabaseName := ''; {Not usually req'd for Oracle}
end;
{Make sure the data is not saved from the first Execute}
Crpe1.DiscardSavedData := True;
Crpe1.Execute;
VCI Re|etetce 467
lugOnlnfu CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the LogOnInfo 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 LogOnInfo object of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the LogOnInfo of all the Subreports will require a looping procedure
that goes through each Subreport and applies the Clear method:
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.LogOnInfo.Clear;
end;
fxampIc
This code clears the LogOnInfo properties for the main Report (assuming the default state of Subreports[0]):
Crpe1.LogOnInfo.Clear;
This code clears the LogOnInfo properties for the second Subreport:
Crpe1.Subreports[2];
Crpe1.LogOnInfo.Clear;
lugOnlnfu CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeLogOnInfo): boolean;
Dcscriptiun
The CopyFrom method copies the LogOnInfo property values from another TCrpeLogOnInfo object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
VCI Re|etetce 468
fxampIc
The following example copies all the LogOnInfo property values to a temporary TCrpeLogOnInfo object:
var
tempLogOnInfo : TCrpeLogOnInfo;
begin
tempLogOnInfo := TCrpeLogOnInfo.Create;
tempLogOnInfo.CopyFrom(Crpe1.LogOnInfo);
{...later, when finished with the temp object...}
tempLogOnInfo.Free;
end;
lugOnlnfu Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the LogOnInfo object. It is handy
for setting up loops to make similar changes to each item.
fxampIc
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.LogOnInfo.Retrieve;
for cnt := 0 to (Crpe1.LogOnInfo.Count - 1) do
Crpe1.LogOnInfo[cnt].Password := 'mytrickypassword';
end;
lugOnlnfu Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component and does not need to be called in code.
VCI Re|etetce 460
lugOnlnfu DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the LogOnInfo object. The "nIndex" parameter
represents the number of the item in the LogOnInfo object.
fxampIc
The following code illustrates the use of the Add and Delete methods to run a Report twice, each time with
different LogOn information (it is assumed in the example that there is only one table in the Report):
Crpe1.ReportName := 'C:\Company.rpt';
with Crpe1.LogOnInfo do
begin
Add(0); {Add a LogOnInfo item, first Table}
ServerName := 'oracleserver';
UserID := 'SCOTT';
Password := 'tiger';
DatabaseName := ''; {Not usually req'd for Oracle}
end;
Crpe1.Execute;
while not Crpe1.PrintEnded do
Application.ProcessMessages;
Crpe1.LogOnInfo.Delete(0);
with Crpe1.LogOnInfo do
begin
Add(0); {Add a LogOnInfo item, first Table}
ServerName := 'oracleserver2';
UserID := 'JACOB';
Password := 'zebra';
DatabaseName := ''; {Not usually req'd for Oracle}
end;
{Make sure the data is not saved from the first Execute}
Crpe1.DiscardSavedData := True;
Crpe1.Execute;
VCI Re|etetce 416
lugOnlnfu Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
lugOnlnfu PrumptFurlugOn prupcrty
DccIaratiun
property PromptForLogOn: boolean;
Dcscriptiun
The PromptForLogOn property determines whether the VCL will create a LogOn dialog box to obtain the log on
parameters required to run a Report based on SQL tables or ODBC datasources. If PromptForLogOn is set to
True, and LogOnInfo.Send, or Crpe1.Execute is called, the VCL will present a LogOn dialog that looks like this:
The Connections listbox on the dialog contains a list of all unique connections required in the Report
(including Subreports). The other edit fields (ServerName, UserID, Password, and DatabaseName) hold the
required log on information. These can be edited. If the OK button is pressed, the log on information from the
edit fields is applied to the various tables in the Report, and the Report is run. If the Cancel button is pressed,
the execution of the Report stops.
VCI Re|etetce 411
If you would like the Prompt dialog box to contain different Server information than what is stored in the
Report, follow these steps:
1 Retrieve LogOnInfo from the Report.
2 Set PromptForLogOn to False.
3 Modify the LogOnInfo property values to the desired settings.
4 Call LogOnInfo.Send to send these parameters into the Report.
S Repeat steps 1 to 4 for any Subreports.
6 Set PromptForLogOn to True.
7 Call Crpe1.Execute.
NO7F: Il you wsh lo modly lhs dalog, lhe Form nlormalon s slored n URIOGON.DFM. 7he URIOGON.PAS
lle s n lhe Source`Dalogs dreclory, allhough l changes are made lo lhe URIOGON.PAS, lhey musl be coed
nlo lhe arorale seclon ol lhe UCDIAIOG.PAS lle n order lo be comled nlo lhe VCI.
fxampIc
The following example shows how to use the PromptForLogOn property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ConnectMethod := useLogOnInfo;
Crpe1.LogOnInfo.PromptForLogOn := True;
Crpe1.Output := toWindow;
{LogOn Prompt Dialog appears after Execute}
Crpe1.Execute;
lugOnlnfu Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the LogOnInfo information from the Report. Retrieve will create one LogOnInfo
item for each SQL table it finds in the Report. If LogOn information was not found, the call returns False. Be
aware that calling Retrieve will first cause the LogOnInfo object to be cleared, so any current information
stored in it will be removed.
NO7F: Snce lhe IogOnInlo objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe IogOnInlo
lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl lo oblan
lhe IogOnInlo sellngs lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle lhrough lhe
Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale IogOnInlo sellngs lor each
Subreorl (see Fxamle).
VCI Re|etetce 412
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.LogOnInfo.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.LogOnInfo.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
lugOnlnfu Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the LogOnInfo 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.
We strongly recommend 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.
fxampIc
In this example, the LogOnInfo settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.LogOnInfo.Send;
VCI Re|etetce 41!
lugOnlnfu Tcst mcthud
DccIaratiun
function Test: boolean;
Dcscriptiun
The Test method provides a way to test the connection before running the Report. With LogOnInfo, this can
be done on a table by table basis, since the Test can be applied to each item. Returns True if the connection was
successful, False if it was not.
fxampIc
This example illustrates the use of the Test method:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.LogOnInfo.Retrieve;
for cnt := 0 to (Crpe1.LogOnInfo.Count - 1) do
begin
Crpe1.LogOnInfo[cnt].UserID := 'Maxwell Smart';
Crpe1.LogOnInfo[cnt].Password := 'Agent86';
if Crpe1.LogOnInfo.Test then
ShowMessage('LogOn information is good: Table #' +
IntToStr(Crpe1.LogOnInfo[cnt].Table))
else
ShowMessage('LogOn information is not good: Table #' +
IntToStr(Crpe1.LogOnInfo[cnt].Table));
end;
lugOnScrvcr Prupcrtics
lugOnScrvcr DatabascNamc prupcrty
DccIaratiun
property DatabaseName: string;
Dcscriptiun
This property contains the name of the Database being connected to. Most SQL Servers require this parameter
(Oracle is usually an exception to the rule).
VCI Re|etetce 414
fxampIc
This example shows how to create a LogOnServer item manually, and fill the properties with values. Finally,
the LogOn method is called:
with Crpe1.LogOnServer do
begin
Add; {Create a LogOnServer item}
DLLName := 'PDSSQL.DLL'; {Crystal's Native MS SQL Server Driver}
ServerName := 'enterprise';
UserID := 'Kirk';
Password := 'captain';
DatabaseName := 'pubs';
if LogOn then
ShowMessage('The LogOn ID is: ' + IntToStr(Number))
else
ShowMessage('Error Logging on to Server');
end;
lugOnScrvcr DllNamc prupcrty
DccIaratiun
property DLLName: string;
Dcscriptiun
The DLLName property refers to the name of the Crystal database DLL used to make the LogOn connection.
This must be the same as the one defined in the Report. If ODBC drivers are being used to make the connection,
the DLL Name is:
'PDSODBC.DLL'
If Crystal's native SQL drivers are being used to make the connection, the DLL naming convention is:
'PDS*.DLL' {PDSORA7.DLL for Oracle, PDSSQL.DLL for MS SQL Server,
PDSSYB10.DLL for Sybase System 10/11, etc.}
Notice that the 16-bit naming convention can be used even for 32-bit drivers. The 32-bit names can also be used
(P2SODBC.DLL, etc.) if desired.
NO7F: 7o delermne lhe drver lhal lhe Reorl was desgned wlh, load lhe Reorl nlo Cryslal Reorls, go lo
lhe Dalabase menu n Cryslal Reorls 6.0 (or Fle [ Reorl Olons n Cryslal Reorls S.0) and seleclng lhe
"Converl Dalabase Drver" olon. 7he drver name s lsled aller lhe word "From:" n lhe dalog.
VCI Re|etetce 41S
fxampIc
This example shows how to create a LogOnServer item manually, and fill the properties with values. Finally,
the LogOn method is called:
with Crpe1.LogOnServer do
begin
Add; {Create a LogOnServer item}
DLLName := 'PDSORA7.DLL'; {Crystal's Native Oracle Driver}
ServerName := 'oracleserver';
UserID := 'SCOTT';
Password := 'tiger';
DatabaseName := ''; {Not usually req'd for Oracle}
if LogOn then
ShowMessage('The LogOn ID is: ' + IntToStr(Number))
else
ShowMessage('Error Logging on to Server');
end;
lugOnScrvcr ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeLogOnServer;
Dcscriptiun
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 LogOnServer object, allowing the
object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript: LogOnServer[2]
is the same as LogOnServer.Item[2].
G Item returns a reference to itself, so the LogOnServer properties can be used right after the subscript:
LogOnServer[2].DatabaseName := 'MyDatabase';
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\Company.rpt';
with Crpe1.LogOnServer do
begin
Add; {Create a LogOnServer item}
DLLName := 'PDSORA7.DLL'; {Crystal's Native Oracle Driver}
ServerName := 'oracleserver';
VCI Re|etetce 416
UserID := 'SCOTT';
Password := 'tiger';
DatabaseName := ''; {Not usually req'd for Oracle}
end;
with Crpe1.LogOnServer do
begin
Add; {Create a LogOnServer item}
DLLName := 'PDSORA7.DLL'; {Crystal's Native Oracle Driver}
ServerName := 'oracleserver2';
UserID := 'WILSON';
Password := 'giraffe';
DatabaseName := ''; {Not usually req'd for Oracle}
end;
{Set LogOnServer object back to first item}
Crpe1.LogOnServer.Item[0];
{Try Logging On}
if Crpe1.LogOnServer.LogOn then
ShowMessage('The LogOn ID is: ' + IntToStr(Number))
else
ShowMessage('Error Logging on to Server');
Crpe1.ReportName := 'C:\Company.rpt';
with Crpe1.LogOnServer do
begin
Add; {Create a LogOnServer item}
DLLName := 'PDSORA7.DLL'; {Crystal's Native Oracle Driver}
ServerName := 'oracleserver';
UserID := 'SCOTT';
Password := 'tiger';
DatabaseName := ''; {Not usually req'd for Oracle}
end;
with Crpe1.LogOnServer do
begin
Add; {Create a LogOnServer item}
DLLName := 'PDSORA7.DLL'; {Crystal's Native Oracle Driver}
ServerName := 'oracleserver2';
UserID := 'WILSON';
Password := 'giraffe';
DatabaseName := ''; {Not usually req'd for Oracle}
end;
{Set LogOnServer object back to first item}
Crpe1.LogOnServer[0];
{Try Logging On}
if Crpe1.LogOnServer.LogOn then
ShowMessage('The LogOn ID is: ' + IntToStr(Number))
else
ShowMessage('Error Logging on to Server');
VCI Re|etetce 417
lugOnScrvcr ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current LogOnServer item number, or
set the LogOnServer 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 (LogOnServer[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the LogOnServer object is
pointing to the first LogOnServer item:
if Crpe1.LogOnServer.ItemIndex <> 0 then
Crpe1.LogOnServer[0];
lugOnScrvcr Numbcr prupcrty
DccIaratiun
property Number: integer;
Dcscriptiun
Number is a read-only property that is filled with a value when the LogOn method is called. Before the LogOn
method is called, the Number property will have zero as a default value.
Each connection established via the LogOnServer's LogOn method will generate a unique LogOn number,
which is stored in the Number property. Therefore, if the Number value of a LogOnServer item is greater than
zero, it indicates that a connection has been established for that Server.
The IndexOf method can be used to locate a specific number within the LogOnServer object.
VCI Re|etetce 418
fxampIc
This example shows how to create a LogOnServer item manually, and fill the properties with values. Finally,
the LogOn method is called, which puts a LogOn ID value in the Number property:
with Crpe1.LogOnServer do
begin
Add; {Create a LogOnServer item}
DLLName := 'PDSORA7.DLL'; {Crystal's Native Oracle Driver}
ServerName := 'oracleserver';
UserID := 'SCOTT';
Password := 'tiger';
DatabaseName := ''; {Not usually req'd for Oracle}
if LogOn then
ShowMessage('The LogOn ID is: ' + IntToStr(Number))
else
ShowMessage('Error Logging on to Server');
end;
lugOnScrvcr Passwurd prupcrty
DccIaratiun
property Password: string;
Dcscriptiun
The Password property contains the user password required for logging on to a SQL Server. This is not stored
in the Report when it is saved (and therefore will not be returned by the Retrieve method), but must be
provided before running the Report.
fxampIc
This example shows how to create a LogOnServer item manually, and fill the properties with values. Finally,
the LogOn method is called:
with Crpe1.LogOnServer do
begin
Add; {Create a LogOnServer item}
DLLName := 'PDSORA7.DLL'; {Crystal's Native Oracle Driver}
ServerName := 'oracleserver';
UserID := 'SCOTT';
Password := 'tiger';
DatabaseName := ''; {Not usually req'd for Oracle}
if LogOn then
VCI Re|etetce 410
ShowMessage('The LogOn ID is: ' + IntToStr(Number))
else
ShowMessage('Error Logging on to Server');
end;
lugOnScrvcr ScrvcrNamc prupcrty
DccIaratiun
property ServerName: string;
Dcscriptiun
This property contains the name of the Server being connected to. If the Report was created using Crystal's
native SQL drivers, this will be the actual Server name. If the Report was created using ODBC drivers, this will
be the ODBC Data Source Name.
fxampIc
This example shows how to create a LogOnServer item manually, and fill the properties with values. Finally,
the LogOn method is called:
with Crpe1.LogOnServer do
begin
Add; {Create a LogOnServer item}
DLLName := 'PDSORA7.DLL'; {Crystal's Native Oracle Driver}
ServerName := 'oracleserver';
UserID := 'SCOTT';
Password := 'tiger';
DatabaseName := ''; {Not usually req'd for Oracle}
if LogOn then
ShowMessage('The LogOn ID is: ' + IntToStr(Number))
else
ShowMessage('Error Logging on to Server');
end;
lugOnScrvcr UscrlD prupcrty
DccIaratiun
property UserID: string;
Dcscriptiun
This property contains the user name required to log on to the SQL Server.
VCI Re|etetce 426
fxampIc
This example shows how to create a LogOnServer item manually, and fill the properties with values. Finally,
the LogOn method is called:
with Crpe1.LogOnServer do
begin
Add; {Create a LogOnServer item}
DLLName := 'PDSORA7.DLL'; {Crystal's Native Oracle Driver}
ServerName := 'oracleserver';
UserID := 'SCOTT';
Password := 'tiger';
DatabaseName := ''; {Not usually req'd for Oracle}
if LogOn then
ShowMessage('The LogOn ID is: ' + IntToStr(Number))
else
ShowMessage('Error Logging on to Server');
end;
lugOnScrvcr Mcthuds
lugOnScrvcr Add mcthud
DccIaratiun
procedure Add;
Dcscriptiun
The Add method adds an item to the LogOnServer object and sets the LogOnServer object index to that item.
If the Add method is used, the steps to using LogOnServer are:
1 Add an item to the LogOnServer object.
2 Fill the item's properties (ServerName, Password, etc.) with values.
3 Use the LogOn method to establish a connection.
NO7F: Allernalvely, l a Reorl has been secled n lhe ReorlName roerly, lhe Relreve melhod can be
used lo lll lhe IogOnServer wlh IogOn nlormalon lrom lhe Reorl, n whch case only lhe Password
roerly wll need lo be llled n belore callng lhe IogOn melhod.
VCI Re|etetce 421
fxampIc
The following code illustrates using the Add method to implement a LogOnServer connection:
with Crpe1.LogOnServer do
begin
Add; {Create a LogOnServer item}
DLLName := 'PDSORA7.DLL'; {Crystal's Native Oracle Driver}
ServerName := 'oracleserver';
UserID := 'SCOTT';
Password := 'tiger';
DatabaseName := ''; {Not usually req'd for Oracle}
if LogOn then
ShowMessage('The LogOn ID is: ' + IntToStr(Number))
else
ShowMessage('Error Logging on to Server');
end;
lugOnScrvcr CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the LogOnServer object. It will not automatically
LogOff any currently connected Servers before clearing the LogOnServer information that has been stored.
fxampIc
This line of code clears the LogOnServer properties:
Crpe1.LogOnServer.Clear;
lugOnScrvcr CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeLogOnServer): boolean;
Dcscriptiun
The CopyFrom method copies the LogOnServer property values from another TCrpeLogOnServer object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
VCI Re|etetce 422
fxampIc
The following example copies all the LogOnServer property values to a temporary TCrpeLogOnServer object:
var
tempLogOnServer : TCrpeLogOnServer;
begin
tempLogOnServer := TCrpeLogOnServer.Create;
tempLogOnServer.CopyFrom(Crpe1.LogOnServer);
{...later, when finished with the temp object...}
tempLogOnServer.Free;
end;
lugOnScrvcr Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the LogOnServer object.
fxampIc
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.LogOnServer.Retrieve;
for cnt := 0 to (Crpe1.LogOnServer.Count - 1) do
ListBox1.Items.Add(Crpe1.LogOnServer[cnt].ServerName;
end;
lugOnScrvcr Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component and does not need to be called in code.
VCI Re|etetce 42!
lugOnScrvcr DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to delete an item from the LogOnServer object. Note that Delete will not check
to see if there is still a connection opened by that item. Therefore, LogOff should be called first, if required.
fxampIc
The following code creates an item in the LogOnServer object, attempts a connection, logs off the connection
and deletes the item:
with Crpe1.LogOnServer do
begin
Add; {Create a LogOnServer item}
DLLName := 'PDSORA7.DLL'; {Crystal's Native Oracle Driver}
ServerName := 'oracleserver';
UserID := 'SCOTT';
Password := 'tiger';
DatabaseName := ''; {Not usually req'd for Oracle}
if not LogOn then
ShowMessage('Error Logging on Server')
else
begin
if not LogOff then
ShowMessage('Error Logging off Server');
end;
Crpe1.LogOnServer.Delete(Crpe1.LogOnServer.ItemIndex);
end;
lugOnScrvcr Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
VCI Re|etetce 424
lugOnScrvcr lndcxOf mcthud
DccIaratiun
function IndexOf(LogNumber: integer): integer;
Dcscriptiun
The IndexOf method takes a LogOn number as a parameter and returns the numeric position of the
LogOnServer item (in the LogOnServer object) that matches the LogOn number. It can be used to locate a
LogOnServer item that is to be logged off.
fxampIc
This example shows how to use the IndexOf method to locate an item in the LogOnServer object based on its
LogOn number value:
procedure LogOffByNumber(Num: integer);
begin
Num := Crpe1.LogOnServer.IndexOf(Num);
if not Crpe1.LogOnServer[Num].LogOff then
ShowMessage('LogOff failed');
end;
lugOnScrvcr lugOff mcthud
DccIaratiun
function LogOff: boolean;
Dcscriptiun
The LogOff method is used to terminate the connection to a Server that was logged onto using the LogOn
method. Returns True if the LogOff succeeded and False if the LogOff attempt failed.
NO7F: IogOll wll nol normally be successlul unless lhe Reorl lhal uses lhe conneclon s lrsl closed, by
elher changng lhe ReorlName, or usng lhe comonenls Close)ob melhod.
VCI Re|etetce 42S
fxampIc
This example shows how to use the IndexOf method to locate an item in the LogOnServer object based on its
LogOn number value, and then LogOff that item:
procedure LogOffByNumber(Num: integer);
begin
Num := Crpe1.LogOnServer.IndexOf(Num);
if not Crpe1.LogOnServer[Num].LogOff then
ShowMessage('LogOff failed');
end;
lugOnScrvcr lugOn mcthud
DccIaratiun
function LogOn: boolean;
Dcscriptiun
The LogOn method is used to create a connection to a SQL Server. Before LogOn can be called, the following
steps should be followed:
1 Add an item to the LogOnServer object, or use the Retrieve method.
2 Fill the item's properties (ServerName, Password, etc.) with relevant values (if Retrieve was used, only
the Password needs to be specified).
3 Use the LogOn method to establish a connection.
If the LogOn was successful, a unique ID number will be stored in the Number property. LogOn returns True
if the LogOn attempt succeeded.
fxampIc
This example shows how to create a LogOnServer item manually, and fill the properties with values. Finally,
the LogOn method is called, which puts a LogOn ID value in the Number property:
with Crpe1.LogOnServer do
begin
Add; {Create a LogOnServer item}
DLLName := 'PDSORA7.DLL'; {Crystal's Native Oracle Driver}
ServerName := 'oracleserver';
UserID := 'SCOTT';
Password := 'tiger';
DatabaseName := ''; {Not usually req'd for Oracle}
if LogOn then
ShowMessage('The LogOn ID is: ' + IntToStr(Number))
else
ShowMessage('Error Logging on to Server');
end;
VCI Re|etetce 426
lugOnScrvcr Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the LogOnServer information from the Report. Unlike most of the other methods
for LogOnServer, in order for the Retrieve call to work there must be a Report specified in the ReportName
property.
Retrieve will actually create one LogOnServer item for each unique set of LogOn information it finds in the
Report (it will also scan Subreport Tables). For example if there are two Tables in the Report going to two
different Servers, then Retrieve will add two items to the LogOnServer object.
G Be aware that calling Retrieve will clear the LogOnServer object of any previous information.
G It is not necessary to retrieve Subreports first. If they have not yet been retrieved, LogOnServer.Retrieve
will automatically retrieve them.
G If LogOn information was not found, the call returns False.
fxampIc
The following code illustrates the use of the Retrieve method to obtain unique LogOnServer information from
all the Tables in the Report and any Subreports. It is not necessary to retrieve Subreports first, since
LogOnServer will do this automatically if it has not been done yet:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.LogOnServer.Retrieve;
{Put the ServerNames in a ListBox}
for cnt := 0 to (Crpe1.LogOnServer.Count - 1) do
ListBox1.Items.Add(Crpe1.LogOnServer[cnt].ServerName);
end;
Margins Prupcrtics
Margins Buttum prupcrty
DccIaratiun
property Bottom: TCrMarginTwips;
VCI Re|etetce 427
Typc
TCrMarginTwips = -2..PE_SM_DEFAULT;
Cunstant
PE_SM_DEFAULT = $8000; {32768 in decimal}
Dcscriptiun
The Bottom property determines the bottom margin of the Report. It is listed in Twips (1 inch = 1440 twips).
The property can be assigned any number from 0 to 32767, or -1 to use the current margin value as contained
in the Report, or -2 (same effect as 32768) for a default margin value based on the current Printer.
fxampIc
The code below sets the Bottom Margin:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Margins.Bottom := 20;
Crpe1.Execute;
Margins lcft prupcrty
DccIaratiun
property Left: TCrMarginTwips;
Typc
TCrMarginTwips = -2..PE_SM_DEFAULT;
Cunstant
PE_SM_DEFAULT = $8000; {32768 in decimal}
Dcscriptiun
The Left property determines the left margin of the Report. It is listed in Twips (1 inch = 1440 twips). The
property can be assigned any number from 0 to 32767, or -1 to use the current margin value as contained in
the Report, or -2 (same effect as 32768) for a default margin value based on the current Printer.
VCI Re|etetce 428
fxampIc
The code below sets the Left Margin:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Margins.Left := 20;
Crpe1.Execute;
Margins Right prupcrty
DccIaratiun
property Right: TCrMarginTwips;
Typc
TCrMarginTwips = -2..PE_SM_DEFAULT;
Cunstant
PE_SM_DEFAULT = $8000; {32768 in decimal}
Dcscriptiun
The Right property determines the right margin of the Report. It is listed in Twips (1 inch = 1440 twips). The
property can be assigned any number from 0 to 32767, or -1 to use the current margin value as contained in
the Report, or -2 (same effect as 32768) for a default margin value based on the current Printer.
fxampIc
The code below sets the Right Margin:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Margins.Right := 20;
Crpe1.Execute;
Margins Tup prupcrty
DccIaratiun
property Top: TCrMarginTwips;
Typc
TCrMarginTwips = -2..PE_SM_DEFAULT;
VCI Re|etetce 420
Cunstant
PE_SM_DEFAULT = $8000; {32768 in decimal}
Dcscriptiun
The Top property determines the top margin of the Report. It is listed in Twips (1 inch = 1440 twips). The
property can be assigned any number from 0 to 32767, or -1 to use the current margin value as contained in
the Report, or -2 (same effect as 32768) for a default margin value based on the current Printer.
fxampIc
The code below sets the Top Margin:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Margins.Top := 20;
Crpe1.Execute;
Margins Mcthuds
Margins CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to set the Margins properties to their default values:
Left := -1;
Right := -1;
Top := -1;
Bottom := -1;
It is called automatically if the Clear method is called for the main component, but may be called in code as
needed.
fxampIc
This line of code clears the Margins properties:
Crpe1.Margins.Clear;
VCI Re|etetce 4!6
Margins CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeMargins): boolean;
Dcscriptiun
The CopyFrom method copies the Margins property values from another TCrpeMargins object. It is similar to
Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the Margins property values to a temporary TCrpeMargins object:
var
tempMargins : TCrpeMargins;
begin
tempMargins := TCrpeMargins.Create;
tempMargins.CopyFrom(Crpe1.Margins);
{...later, when finished with the temp object...}
tempMargins.Free;
end;
Margins Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component and does not need to be called in code.
Margins Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
VCI Re|etetce 4!1
Dcscriptiun
The Retrieve method obtains the Margins information from the Report. Returns True if the call succeeded.
NO7F: Snce lhe Margns objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe Margns lor lhe
Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl lo oblan lhe Margns
sellngs lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle lhrough lhe Subreorls objecl and
call Relreve lor each lem. 7he VCI wll slore searale Margn sellngs lor each Subreorl (see Fxamle).
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Margins.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.Margins.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
Margins Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the Margins 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.
VCI Re|etetce 4!2
fxampIc
In this example, the Margins settings are sent from the Crystal component to the Crystal Reports Print Engine
DLL. This is normally handled automatically in the Execute method:
Crpe1.Margins.Send;
Pagcs Prupcrtics
Pagcs ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: string;
Dcscriptiun
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 Pages object, allowing the object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript: Pages[2] is the
same as Pages.Item[2].
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
{Set Window to view 3rd page}
Crpe1.Pages.Item[2];
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
{Set Window to view 3rd page}
Crpe1.Pages[2];
Pagcs ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
VCI Re|etetce 4!!
Dcscriptiun
ItemIndex is a Run-time only property which can be used to read the current Page (same as GetDisplayed), or
set the current Page (same as GoToPage).
fxampIc
This code sample illustrates the use of ItemIndex to show and set the page displayed:
var
pg1: integer;
begin
{Get the Displayed page number}
pg1 := Crpe1.Pages.ItemIndex;
{Show the next page}
Crpe1.Pages.ItemIndex := pg1 + 1;
end;
Pagcs Mcthuds
Pagcs Cuunt mcthud
DccIaratiun
function Count: SmallInt;
Dcscriptiun
Count returns the number of Pages in the Report. This will return 0 until Execute is called.
fxampIc
The following code shows how to get the number of Pages in a Report using the Count property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
ShowMessage(IntToStr(Crpe1.Pages.Count));
Pagcs First mcthud
DccIaratiun
procedure First;
VCI Re|etetce 4!4
Dcscriptiun
The First method causes the Preview Window to go to the first Page of the Report. This method can be used
to simulate the action of the First Page button on the Preview Window.
fxampIc
The following code shows how to use the First method to go to the first Page of a Report:
Crpe1.ReportName := 'D:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.Pages.First;
Pagcs GctDispIaycd mcthud
DccIaratiun
function GetDisplayed: Word;
Dcscriptiun
GetDisplayed will return the number of the currently active (or previewed) Page.
fxampIc
The following code shows how to get the Displayed Page of a Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
ShowMessage(IntToStr(Crpe1.Pages.GetDisplayed));
Pagcs Gctlatcst mcthud
DccIaratiun
function GetLatest: Word;
Dcscriptiun
GetLatest will return the number of the highest Page that has been built so far. When going to Preview Window,
all the database records are read, but only the Pages required are built (to speed up the display for large Reports).
This is why the Page count display always starts with "Page 1 of 1+". As the Next Page button is pressed, each
page will be built and added to the count, or if the Last Page button is pressed, all the Pages will be built.
VCI Re|etetce 4!S
fxampIc
The following code shows how to get the Latest Page of a Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
ShowMessage(IntToStr(Crpe1.Pages.GetLatest));
Pagcs GctStart mcthud
DccIaratiun
function GetStart: Word;
Dcscriptiun
GetStart will return the number of the first Page that was built when the Report was run. When going to
Preview Window, this will always be 1, but when going to Printer, if the PrintOptions.StartPage value is
greater than 1, GetStart will return that value.
fxampIc
The following code shows how to get the Start Page of a Report. When going to Printer, this value can be
something other than 1:
Crpe1.ReportName := 'D:\Company.rpt';
Crpe1.Output := toPrinter;
Crpe1.PrintOptions.StartPage := 2;
Crpe1.Execute;
ShowMessage(IntToStr(Crpe1.Pages.GetStart));
Pagcs GuTuPagc mcthud
DccIaratiun
procedure GoToPage(const Value: smallint);
Dcscriptiun
The GoToPage method causes the Preview Window to go to the specified Page of the Report. Specifying a Page
number that is greater than the number of Pages in the current Report will result in an error: "Error 550: Invalid
Page Number".
VCI Re|etetce 4!6
fxampIc
The following code shows how to use the GoToPage property to set the displayed Page:
Crpe1.ReportName := 'D:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.Pages.GoToPage(3)
Pagcs last mcthud
DccIaratiun
procedure Last;
Dcscriptiun
The Last method causes the Preview Window to go to the last Page of the Report. This method can be used to
simulate the action of the Last Page button on the Preview Window.
fxampIc
The following code shows how to use the Last method to go to the last Page of a Report:
Crpe1.ReportName := 'D:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.Pages.Last;
Pagcs Ncxt mcthud
DccIaratiun
procedure Next;
Dcscriptiun
The Next method causes the Preview Window to go to the next Page of the Report. This method can be used
to simulate the action of the Next Page button on the Preview Window.
VCI Re|etetce 4!7
fxampIc
The following code shows how to use the Next method to go to the next Page of a Report:
Crpe1.ReportName := 'D:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.Pages.Next;
Pagcs Prcviuus mcthud
DccIaratiun
procedure Previous;
Dcscriptiun
The Previous method causes the Preview Window to go to the previous Page of the Report. This method can
be used to simulate the action of the Previous Page button on the Preview Window.
fxampIc
The following code shows how to use the Previous method to go to the previous Page of a Report:
Crpe1.ReportName := 'D:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.Pages.GoToPage(3);
Crpe1.Pages.Previous;
ParamFicIds Prupcrtics
ParamFicIds AsBuuIcan prupcrty
DccIaratiun
property AsBoolean: boolean;
Dcscriptiun
The AsBoolean property is run-time only and can be used to read and write the ParamFields.Value property
with native Delphi boolean values. Whereas the Value property holds the ParamFields value as a string,
AsBoolean will return the value as a boolean type, or can be written to with a boolean type.
VCI Re|etetce 4!8
fxampIc
This example uses the AsBoolean property to pass in a native Delphi boolean variable to the ParamFields
Value property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].AsBoolean := True;
Crpe1.Execute;
ParamFicIds AsCurrcncy prupcrty
DccIaratiun
property AsCurrency: currency;
Dcscriptiun
The AsCurrency property is run-time only and can be used to read and write the ParamFields.Value property
with native Delphi currency values. Whereas the Value property holds the ParamFields value as a string,
AsCurrency will return the value as a currency type, or can be written to with a currency type.
fxampIc
This example uses the AsCurrency property to pass in a native Delphi currency variable to the ParamFields
Value property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].AsCurrency := 1.23;
Crpe1.Execute;
ParamFicIds AsDatc prupcrty
DccIaratiun
property AsDate: TDateTime;
Dcscriptiun
The AsDate property is run-time only and can be used to read and write the ParamFields.Value property with
native Delphi DateTime values. Whereas the Value property holds the ParamFields value as a string, AsDate
will return the value as a datetime type, or can be written to with a datetime type.
VCI Re|etetce 4!0
fxampIc
This example uses the AsDate property to pass in a native Delphi datetime variable to the ParamFields Value
property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].AsDate := Now;
Crpe1.Execute;
ParamFicIds AsDatcTimc prupcrty
DccIaratiun
property AsDateTime: TDateTime;
Dcscriptiun
The AsDateTime property is a run-time property that allows for reading and writing of the Value property
(which is a string type) using native Delphi TDateTime values. This property should only be used if the
ParamField is actually specified as DateTime (the ParamType is pfDateTime).
fxampIc
This example uses the AsDateTime property to pass in a native Delphi datetime variable to the ParamFields
Value property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].AsDateTime := Now;
Crpe1.Execute;
ParamFicIds AsNumbcr prupcrty
DccIaratiun
property AsNumber: double;
Dcscriptiun
The AsNumber property is run-time only and can be used to read and write the ParamFields.Value property
with native Delphi number values. Whereas the Value property holds the ParamFields value as a string,
AsNumber will return the value as a number type, or can be written to with a number type.
VCI Re|etetce 446
fxampIc
This example uses the AsNumber property to pass in a native Delphi number variable to the ParamFields
Value property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].AsNumber := 1;
Crpe1.Execute;
ParamFicIds AsTimc prupcrty
DccIaratiun
property AsTime: TDateTime;
Dcscriptiun
The AsTime property is run-time only and can be used to read and write the ParamFields.Value property with
native Delphi DateTime values. Whereas the Value property holds the ParamFields value as a string, AsTime
will return the value as a datetime type, or can be written to with a datetime type.
fxampIc
This example uses the AsTime property to pass in a native Delphi datetime variable to the ParamFields Value
property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].AsTime := Now;
Crpe1.Execute;
ParamFicIds CurrcntVaIuc prupcrty
DccIaratiun
property CurrentValue: string
Dcscriptiun
The CurrentValue property indicates the Parameter Value that was last entered into the Parameter Field
Prompt Dialog.
G The Retrieve method must be used first, before CurrentValue will contain anything.
G If the Report does not have Saved Data, CurrentValue will be an empty string until the Report is run at
least once (Note that in this case, Retrieve must be called again after the Report has been run in order to
show the last value sent to the Parameter Field).
VCI Re|etetce 441
NO7F: CurrenlValue s ncluded rmarly as a relerence roerly, and s nol used when lhe ParamFelds are
senl lo lhe Prnl Fngne, so changes lo l wll nol be rellecled when lhe Reorl s run. Inslead, any changes
desred should be made lo lhe Value roerly.
Ncw Fcaturcs fur SCR 7.0
With Seagate Crystal Reports 7.0, multiple Current Values are possible for a Parameter Field. These are
handled via the CurrentValues property, which is a StringList.
fxampIc
This example copies the CurrentValue to the Value property for the first ParamField. This only makes sense if
the Report has already been run once, or it has Saved Data:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].Value := Crpe1.ParamFields[0].CurrentValue;
Crpe1.ParamFields[0].ShowDialog := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds CurrcntVaIucs prupcrty
DccIaratiun
property CurrentValues: TCrpeString;
Typc
TCrpeString = class(TStringList)
Dcscriptiun
CurrentValues is a StringList that contains multiple values that are to be passed to a Crystal Parameter Field.
CurrentValues will only apply if the ParamField.Info.ValueType = vtDiscrete. Otherwise, the Ranges object
will apply.
Assuming that the Info.ValueType is vtDiscrete, when the Retrieve method of the ParamFields object is called,
the CurrentValues stringlist will contain any current values that have been set for a ParamField. Normally
there would not be any, unless the Report has Saved Data, or it has just been run once already.
The most common use of CurrentValues would be to pass multiple values into a ParamField when the
Parameter prompt dialog is going to be bypassed. In this case, the values should be added to the
CurrentValues stringlist, and the ShowDialog property should be set to False. Note that if the
ParamField.Info.AllowMultipleValues property is False, only the first item in the CurrentValues stringlist will
be used in the Report. On the other hand, if AllowMultipleValues is true, then all the values will be used in
the Report. In this case, the Report must be designed to handle a ParamField which has an array of values in
it (see the CRW.HLP for information on using arrays in formulas).
VCI Re|etetce 442
NO7F: 7o read and wrle CurrenlValues usng nalve Delh lyes (boolean, currency, dalelme, elc.), use lhe
lollowng melhods:
Reading
StrToBoolean
StrToDate
StrToDateTime
StrToFloating
StrToTime
Writing
BooleanToStr
DateTimeToStr
DateToStr
FloatingToStr
TimeToStr
Extracting Parts
ExDateStr
ExDateTimeStr
ExTimeStr
fxampIc
This example sets 2 CurrentValues for the first ParamField. These will be passed directly into the Report,
bypassing the Crystal Parameter prompt dialog:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
{Use values instead of ranges}
Crpe1.ParamFields[0].Info.ValueType := vtDiscrete;
{Allow more than one value, ie. an array}
Crpe1.ParamFields[0].Info.AllowMultipleValues := cTrue;
Crpe1.ParamFields[0].ShowDialog := False;
{Clear it, just in case...}
Crpe1.ParamFields[0].CurrentValues.Clear;
Crpe1.ParamFields[0].CurrentValues[0] := 'Atkinson';
Crpe1.ParamFields[0].CurrentValues[1] := 'Jones';
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds DcfauItVaIuc prupcrty
DccIaratiun
property DefaultValue: string
VCI Re|etetce 44!
Dcscriptiun
The DefaultValue property indicates the Default Prompting Value that was entered for a Parameter Field
when the Parameter was created in Crystal Reports.
G The Retrieve method must be used first, before DefaultValue will contain anything.
G The DefaultValue is automatically copied to the Value property when the Retrieve method is called.
G If the Report has already been run at least once, and the ShowDialog property was set to True,
DefaultValue will indicate the value that appeared (before being edited) in the Parameter Prompt
dialog (Note that in this case, Retrieve must be called again after the Report has been run in order to
show the last default value).
NO7F: DelaullValue s ncluded rmarly as a relerence roerly, and s nol used when lhe ParamFelds are
senl lo lhe Prnl Fngne, so changes lo l wll nol be rellecled when lhe Reorl s run. Inslead, any changes
desred should be made lo lhe Value roerly.
Ncw Fcaturcs fur SCR 7.0
With Seagate Crystal Reports 7.0, multiple Default Values are possible for a Parameter Field. These are
handled via the DefaultValues property, which is a StringList.
fxampIc
This example displays the DefaultValue for the first ParamField:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
ShowMessage(Crpe1.ParamFields[0].DefaultValue);
ParamFicIds DcfauItVaIucs prupcrty
DccIaratiun
property DefaultValues: TCrpeString;
Typc
TCrpeString = class(TStringList)
Dcscriptiun
DefaultValues is a StringList that contains multiple values that are to be passed as possible choices to a Crystal
Parameter Field. These values will not actually be used in the Parameter until the user selects them when the
Parameter prompt dialog appears. If you do not want the Parameter prompt dialog to appear, you should use
the CurrentValues property instead.
VCI Re|etetce 444
When the Retrieve method of the ParamFields object is called, the DefaultValues stringlist will contain any
default values that have been entered as options for a Parameter. Normally this would have been done when
the Parameter was created in the Report, but could also be those items that were sent in as default values from
a previous run of the Report (provided the Report is still in memory).
The most common use of DefaultValues would be to edit or add to the list of multiple values that will be
available for the user to choose from when the Parameter prompt dialog appears. In this case, the ShowDialog
property should be set to True.
NO7F: 7o read and wrle DelaullValues usng nalve Delh lyes (boolean, currency, dalelme, elc.), use lhe
lollowng melhods:
Reading
StrToBoolean
StrToDate
StrToDateTime
StrToFloating
StrToTime
Writing
BooleanToStr
DateTimeToStr
DateToStr
FloatingToStr
TimeToStr
Extracting Parts
ExDateStr
ExDateTimeStr
ExTimeStr
fxampIc
This example sets 2 DefaultValues for the first ParamField. These will be offered as choices when the
Parameter prompt dialog appears:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].ShowDialog := True;
{Clear it, just in case...}
Crpe1.ParamFields[0].DefaultValues.Clear;
Crpe1.ParamFields[0].DefaultValues[0] := 'Atkinson';
Crpe1.ParamFields[0].DefaultValues[1] := 'Jones';
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 44S
ParamFicIds fditMask prupcrty
DccIaratiun
property EditMask: string;
Dcscriptiun
The EditMask property can be used to control the type of data that can be input into the Crystal Parameter
prompt dialog's edit field. It is only applicable to string-type parameters (ParamType = pfString).
The EditMask can be any of a set of masking characters used to restrict the values that can be entered. Some
of the Edit Mask characters require that a character be entered in their place, while others are optional
placeholders, and still others act as separator characters.
For example, if the EditMask is 000099, a parameter value with four digits, five digits, or six digits can be
entered by the user, since the "9" EditMask character does not require the entry of a character. However,
since "0" does require such an entry, a parameter value with less than four digits cannot be entered.
A - allows an alphanumeric character and requires the entry of a character in the parameter value.
a - allows an alphanumeric character and does not require the entry of a character in the parameter value.
0 - allows a digit [0 to 9] and requires the entry of a character in the parameter value.
9 - allows a digit or a space, and does not require the entry of a character in the parameter value.
# - allows a digit, space, or plus/minus sign, and does not require the entry of a character in the
parameter value.
L - allows a letter [A to Z], and requires the entry of a character in the parameter value.
? - allows a letter, and does not require the entry of a character in the parameter value.
& - allows any character or space, and requires the entry of a character in the parameter value.
C - allows any character or space, and does not require the entry of a character in the parameter value.
.,:;-/ - separator characters.
Inserting separator characters into the EditMask is similar to hard coding the formatting for the Parameter
field. When the field is placed on the report, the separator character will appear in the field object frame, like
this: LLLL/0000. This example depicts an edit mask that requires four letters followed by four numbers.
< - causes subsequent characters to be converted to lowercase.
> - causes subsequent characters to be converted to uppercase.
\ - causes the subsequent character to be displayed as a literal. For example, the Edit Mask "\A" would
display a parameter value of "A." If the Edit Mask is "00\A00," then a valid parameter value would
consist of two digits, the letter "A," and then two additional digits.
VCI Re|etetce 446
Password - if the EditMask is set to "Password", the Parameter prompt dialog will show
only "****" characters in the edit field. In this way, conditional formulas can be created
specifying that certain sections of the report will be visible only when certain user
passwords are entered.
fxampIc
This example sets an EditMask for the first ParamField, "parameter1". The mask is to be used for a State
abbreviation, "CA", "WA", etc.:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].ShowDialog := True;
{Requires two letters, they will be converted to uppercase}
Crpe1.ParamFields[0].EditMask := '>LL';
Crpe1.Selection.Formula.Text := '{company.STATE} = {?parameter1}';
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds lnfu prupcrty
DccIaratiun
property Info : TCrpeParamFieldInfo;
Typc
TCrpeParamFieldInfo = class(TPersistent)
Dcscriptiun
Only available with Seagate Crystal Reports 7 and higher. The Info sub-class contains 7 properties that refer
to extra Parameter Field options.
G The AllowEditing property determines if the Parameter Field can be edited in the Prompt Dialog.
G The AllowMultipleValues property determines if the Parameter Field will accept more than one value.
G The AllowNull property determines if the Parameter Field will accept a null value; that is, whether it can be
left blank in the Prompt Dialog. This property only applies to Stored Procedure Parameters, which are now
read through the ParamFields object, instead of SQL.Params as with former versions of Crystal Reports.
G The PartOfGroup property determines if the Parameter Field is grouped with other Parameter Fields. If
it is, it will appear on the same tab of the Prompt Dialog as the other Parameters it is grouped with.
G The GroupNum property specifies the Group number that the Parameter Field belongs to. This only
applies if PartOfGroup is set to cTrue.
VCI Re|etetce 447
G The MutuallyExclusiveGroup property goes along with the previous two properties, and determines if
a Grouped Parameter Field will be mutually exclusive. A Parameter is mutually exclusive if when
selecting one of it's values, the other Parameters in the Group are de-selected.
G The ValueType property specifies whether the Parameter Field uses Discrete values or Ranges.
G The Retrieve method will fetch the Parameter Field Info for the current Parameter specified in the
ParamField object, and will set the Info properties accordingly.
G The Clear method will set the Info properties to default values.
G The CopyFrom method will copy the Info property values from another Info object. ParamFields Info
Example
This example retrieves the ParamFields values from the Report, and sets the first ParamField to allow editing,
and to disallow multiple values:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].Info.AllowEditing := cTrue;
Crpe1.ParamFields[0].Info.AllowMultipleValues := cFalse;
Crpe1.ParamFields[0].ShowDialog := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds lnfu AIIuwfditing prupcrty
DccIaratiun
property AllowEditing: TCrBoolean;
Dcscriptiun
This property determines if the Parameter Field can be edited in the Prompt Dialog. If it is set to cFalse, the
user will have to choose one of the DefaultValues from the drop-down list in the Parameter Field Prompt
Dialog.
fxampIc
This example retrieves the ParamFields values from the Report, and sets the first ParamField to allow editing,
and to disallow multiple values:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].Info.AllowEditing := cTrue;
Crpe1.ParamFields[0].Info.AllowMultipleValues := cFalse;
Crpe1.ParamFields[0].ShowDialog := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 448
ParamFicIds lnfu AIIuwMuItipIcVaIucs prupcrty
DccIaratiun
property AllowMultipleValues: TCrBoolean;
Dcscriptiun
This property determines if the Parameter Field will accept more than one value. If it is set to cTrue, an extra
ListBox will appear in the Prompt Dialog to which the user can add multiple values to be sent into the
Parameter. When multiple values are passed into a Parameter Field, the Parameter is treated as an array of
values, as in this example:
["Smith", "Jones", "Brown"]
fxampIc
This example retrieves the ParamFields values from the Report, and sets the first ParamField to allow editing,
and to disallow multiple values:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].Info.AllowEditing := cTrue;
Crpe1.ParamFields[0].Info.AllowMultipleValues := cFalse;
Crpe1.ParamFields[0].ShowDialog := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds lnfu AIIuwNuII prupcrty
DccIaratiun
property AllowNull: TCrBoolean;
Dcscriptiun
This property specifies whether the Parameter Field will accept a null value; that is, whether it can be left blank
in the Prompt Dialog. This property only applies to Stored Procedure Parameters, which from Crystal Reports
7 and up, are now read through the ParamFields object, instead of SQL.Params (as with Crystal Reports 6 and
lower).
VCI Re|etetce 440
fxampIc
This example retrieves the ParamFields values from the Report, and sets the first ParamField to allow editing,
and to disallow multiple values:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].Info.AllowEditing := cTrue;
Crpe1.ParamFields[0].Info.AllowMultipleValues := cFalse;
Crpe1.ParamFields[0].ShowDialog := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds lnfu GruupNum prupcrty
DccIaratiun
property GroupNum: smallint;
Dcscriptiun
The GroupNum property specifies the Group that the Parameter Field belongs to. This only applies if
PartOfGroup is set to cTrue.
Noles on Groung: Groung ol Paramelers only ales lo Boolean Parameler Felds. Wlh Groung,
mullle Boolean Parameler Felds can be lrealed as a Grou, whereby lhey wll all aear on lhe same lab ol
lhe Parameler Feld roml dalog. 7he ParlOlGrou roerly lurns lhe groung lealure on or oll lor a
Parameler Feld. 7he GrouNum roerly delermnes whch Grou a groued Parameler belongs lo.
Groued Paramelers wll be resenled n a dro-down lsl. Il MuluallyFxclusveGrou s sel lo cFalse, more
lhan one lem can be selecled lrom lhe dro-down lsl and added lo a lslbox. All Paramelers added lo lhe
lslbox wll have a 7rue value, all lhose nol n lhe lslbox wll have a False value. Il MuluallyFxclusveGrou s
sel lo c7rue, lhen only lhe Parameler selecled n lhe dro-down lsl wll have a 7rue value, and all olher
Boolean Paramelers n lhal Grou wll have a False value.
fxampIc
This example retrieves the ParamFields values from the Report, and sets the first ParamField to allow editing,
and to disallow multiple values:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].Info.AllowEditing := cTrue;
Crpe1.ParamFields[0].Info.AllowMultipleValues := cFalse;
Crpe1.ParamFields[0].ShowDialog := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 4S6
ParamFicIds lnfu MutuaIIyfxcIusivcGruup prupcrty
DccIaratiun
property MutuallyExclusiveGroup: TCrBoolean;
Dcscriptiun
This property determines if a Grouped Parameter Field will be mutually exclusive. A Parameter is mutually
exclusive if only one member of the Group can be selected, and when selecting it, the other Parameters in the
Group are de-selected.
Noles on Groung: Groung ol Paramelers only ales lo Boolean Parameler Felds. Wlh Groung,
mullle Boolean Parameler Felds can be lrealed as a Grou, whereby lhey wll all aear on lhe same lab ol
lhe Parameler Feld roml dalog. 7he ParlOlGrou roerly lurns lhe groung lealure on or oll lor a
Parameler Feld. 7he GrouNum roerly delermnes whch Grou a groued Parameler belongs lo.
Groued Paramelers wll be resenled n a dro-down lsl. Il MuluallyFxclusveGrou s sel lo cFalse, more
lhan one lem can be selecled lrom lhe dro-down lsl and added lo a lslbox. All Paramelers added lo lhe
lslbox wll have a 7rue value, all lhose nol n lhe lslbox wll have a False value. Il MuluallyFxclusveGrou s
sel lo c7rue, lhen only lhe Parameler selecled n lhe dro-down lsl wll have a 7rue value, and all olher
Boolean Paramelers n lhal Grou wll have a False value.
fxampIc
This example retrieves the ParamFields values from the Report, and sets the first ParamField to allow editing,
and to disallow multiple values:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].Info.AllowEditing := cTrue;
Crpe1.ParamFields[0].Info.AllowMultipleValues := cFalse;
Crpe1.ParamFields[0].ShowDialog := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds lnfu PartOfGruup prupcrty
DccIaratiun
property PartOfGroup: TCrBoolean;
VCI Re|etetce 4S1
Dcscriptiun
The PartOfGroup property determines if the Parameter Field is grouped with other Parameter Fields. If it is,
it will appear on the same tab of the Prompt Dialog as the other Parameters it is grouped with.
Noles on Groung: Groung ol Paramelers only ales lo Boolean Parameler Felds. Wlh Groung,
mullle Boolean Parameler Felds can be lrealed as a Grou, whereby lhey wll all aear on lhe same lab ol
lhe Parameler Feld roml dalog. 7he ParlOlGrou roerly lurns lhe groung lealure on or oll lor a
Parameler Feld. 7he GrouNum roerly delermnes whch Grou a groued Parameler belongs lo.
Groued Paramelers wll be resenled n a dro-down lsl. Il MuluallyFxclusveGrou s sel lo cFalse, more
lhan one lem can be selecled lrom lhe dro-down lsl and added lo a lslbox. All Paramelers added lo lhe
lslbox wll have a 7rue value, all lhose nol n lhe lslbox wll have a False value. Il MuluallyFxclusveGrou s
sel lo c7rue, lhen only lhe Parameler selecled n lhe dro-down lsl wll have a 7rue value, and all olher
Boolean Paramelers n lhal Grou wll have a False value.
fxampIc
This example retrieves the ParamFields values from the Report, and sets the first ParamField to allow editing,
and to disallow multiple values:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].Info.AllowEditing := cTrue;
Crpe1.ParamFields[0].Info.AllowMultipleValues := cFalse;
Crpe1.ParamFields[0].ShowDialog := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds lnfu VaIucTypc prupcrty
DccIaratiun
property ValueType: TCrParamInfoValueType;
Typc
TCrParamInfoValueType = (vtRanges, vtDiscrete);
VCI Re|etetce 4S2
Dcscriptiun
The ValueType property specifies whether the Parameter Field uses Discrete values or Ranges. The difference
between Discrete and Range values are illustrated below:
Discrete Values
String : "CA"
Number : 12
Currency : 22.33
Date : 1998,01,01
Boolean : False
Range Values
String : "CA" to "WA"
Number : 12 to 24
Currency : 22.33 to 33.33
Date : Date(1998,01,01) to Date(1998,01,31)
Boolean: Range Values not available for Boolean
NO7F: 7he AllowMullleValues roerly delermnes whelher lhere can be more lhan one value assed n a
ParamFeld. In lhe case ol Dscrele Values, lhs would mean an array ol values, .e.: ["CA", "AK", "WA"]. In
lhe case ol Range values, lhs would mean an array ol ranges, .e.: ["CA" lo "II", "PA" lo "WA"].
fxampIc
This example retrieves the ParamFields values from the Report, and sets the first ParamField to allow editing,
and to disallow multiple values:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].Info.AllowEditing := cTrue;
Crpe1.ParamFields[0].Info.AllowMultipleValues := cFalse;
Crpe1.ParamFields[0].ShowDialog := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds lnfu CIcar mcthud
DccIaratiun
procedure Clear;
VCI Re|etetce 4S!
Dcscriptiun
This method can be used to clear the internal memory of the Info 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 Info object of the current ParamField, and the current Report/
Subreport specified in the Subreports object. Therefore, to clear all the ParamField Info of all the ParamFields
in all the Subreports, will require a looping procedure that goes through each Subreport and applies the Clear
method to each ParamField.
fxampIc
This code clears the ParamField Info for the first ParamField in the main Report (assuming the default state of
Subreports[0]):
Crpe1.ParamFields[0].Info.Clear;
NO7F: Usng ParamFelds.Clear nslead, wll clear all lhe Inlo lor all lhe ParamFelds al once.
ParamFicIds lnfu CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeParamFieldInfo): boolean;
Dcscriptiun
The CopyFrom method copies the Info property values from another TCrpeParamFieldInfo object. It is similar
to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the Info property values to a temporary TCrpeParamFieldInfo object:
var
tempInfo : TCrpeParamFieldInfo;
begin
tempInfo := TCrpeParamFieldInfo.Create;
tempInfo.CopyFrom(Crpe1.Paramfields.Info);
{...later, when finished with the temp object...}
tempInfo.Free;
end;
VCI Re|etetce 4S4
ParamFicIds lnfu Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the Info object, and does not need to
be called in code, unless you are using the CopyFrom method to store Info data to a temporary object:
var
tempInfo : TCrpeParamFieldInfo;
begin
tempInfo := TCrpeParamFieldInfo.Create;
tempInfo.CopyFrom(Crpe1.ParamFields.Info);
end;
ParamFicIds lnfu Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the Parameter Field Info information (for the current ParamFields item) from the
Report and stores it in the Info object. If Parameter Field Info was not found, the call returns False.
NO7F: 7hs melhod s aulomalcally called nlernally n lhe ParamFelds.Relreve melhod, and so wll nol
normally be requred n code.
fxampIc
In this code example, the first ParamField item is manually created using the Add method. The Add method
requires the Parameter Name (assumed as "Parameter1" in this example) and the Report Name (blank for the
main Report). Then the ParamField Info property values are retrieved:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Add('Parameter1', '');
Crpe1.ParamFields[0].Info.Retrieve;
VCI Re|etetce 4SS
ParamFicIds lnfu Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the Info 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), or when
ParamFields.Send is called.
We strongly recommend 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.
fxampIc
In this example, the ParamFields Info settings for the first ParamField are sent from the Crystal component to
the Crystal Reports Print Engine DLL. This is normally handled automatically for each ParamField in the
ParamFields.Send method which is in turn called by the Execute method:
Crpe1.ParamFields[0].Info.Send;
ParamFicIds ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeParamFields;
Dcscriptiun
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 various items stored in the ParamFields object, allowing the
object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript: ParamFields[2] is
the same as ParamFields.Item[2].
G Item returns a reference to itself, so the ParamFields properties can be used right after the subscript:
ParamFields[2].Value := '100';
VCI Re|etetce 4S6
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
{Set ParamFields to the 3rd Parameter field}
Crpe1.ParamFields.Item[2];
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
{Set ParamFields to the 3rd Parameter field}
Crpe1.ParamFields[2];
ParamFicIds ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current ParamFields item number, or
set the ParamFields 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 (ParamFields[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the ParamFields object is
pointing to the first ParamFields item:
if Crpe1.ParamFields.ItemIndex <> 0 then
Crpe1.ParamFields[0];
ParamFicIds Namc prupcrty
DccIaratiun
property Name: TCrParameterFieldName;
VCI Re|etetce 4S7
Typc
TCrParameterFieldName = string[255];
Dcscriptiun
The Name property is the key property for the ParamFields sub-class. It contains the Name of the Parameter
Field. It is a look-up property and therefore cannot be directly written to. If the Retrieve method is used, the
Name property is automatically filled when the ParamFields are retrieved and when the ParamFields object
is pointed to one of the retrieved items. To write to it indirectly, use the Add method.
When the Name property is changed, all of the properties of the ParamFields object are updated to look at that
particular ParamField.
Note that it is also possible, and often easier, to navigate through the various ParamFields items by using the
default Item property, or the ItemIndex property.
fxampIc
This example illustrates the use of the Name property to navigate through the ParamFields object:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
{Set ParamFields object to item 'FirstParam' name}
Crpe1.ParamFields.Name := 'FirstParam';
{Set ParamFields item Value}
Crpe1.ParamFields.Value := 'CA';
Crpe1.Output := toWindow;
Crpe1.Execute;
Note that since there is an internal index in the ParamFields object (and most of the other Crystal VCL sub-
class objects), it is not necessary to specify a subscript (i.e. ParamFields[0].Value) every time a property is set.
Once the sub-class object is pointing to a certain item, the other properties apply to that item, whether the
subscript is specified or not.
ParamFicIds NccdsCurrcntVaIuc prupcrty
DccIaratiun
property NeedsCurrentValue: boolean;
Dcscriptiun
NeedsCurrentValue is a read-only property that will only have a meaningful value if the Retrieve method is
used to fetch the ParamField items from the Report. It indicates whether a ParamField item requires a value
or not. Any ParamFields that are created as a result of a Subreport link, or that are not used in the Report, will
return False for NeedsCurrentValue. These ParamFields do not require values, and will not prompt for values
when a Report is run.
VCI Re|etetce 4S8
fxampIc
This example checks the NeedsCurrentValue property before assigning a ParamField Value:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
for cnt := 0 to (Crpe1.ParamFields.Count - 1) do
begin
if Crpe1.ParamFields[cnt].NeedsCurrentValue = True then
Crpe1.ParamFields[cnt].Value := 'CA';
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ParamFicIds ParamSuurcc prupcrty
DccIaratiun
property ParamSource: TCrParamFieldSource;
Typc
TCrParamFieldSource = (psReport, psStoredProc, psQuery);
Dcscriptiun
The ParamSource property is a read-only property that reveals the source of the Parameter. With the release
of SCR 7, the ParamFields class now handles Crystal Reports Parameter Fields, Stored Procedure Parameters,
and Crystal Query Parameter Fields, and this property provides a way to distinguish between them. The
Retrieve method must be called before this property will have a meaningful value.
fxampIc
This example feeds all the Stored Procedure Parameter names to a ListBox:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
VCI Re|etetce 4S0
for cnt := 0 to (Crpe1.ParamFields.Count - 1) do
begin
if Crpe1.ParamFields[cnt].ParamSource = psStoredProc then
ListBox1.Items.Add(Crpe1.ParamFields[cnt].Name);
end;
end;
ParamFicIds ParamTypc prupcrty
DccIaratiun
property ParamType: TCrParameterFieldType;
Typc
TCrParamFieldType = (pfNumber, pfCurrency, pfBoolean, pfDate, pfString,
pfDateTime, pfTime, pfInteger, pfColor, pfChar, pfLong, pfNoValue);
Dcscriptiun
ParamType is a read-only property that will only have a meaningful value if the Retrieve method is used to
obtain ParamFields items from the Report. It indicates what data type the Value property is expecting.
NO7F: Il s nol ossble lo change lhe lye ol a ParamFeld al runlme. 7hs musl be done wlhn lhe Cryslal
Reorls desgner.
fxampIc
The ParamType property can be used to check the type of Value the ParamField item expects:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
for cnt := 0 to (Crpe1.ParamFields.Count - 1) do
begin
case Crpe1.ParamFields[cnt].ParamType of
pfNumber : Crpe1.ParamFields[cnt].AsNumber := 1;
pfCurrency : Crpe1.ParamFields[cnt].AsCurrency := 1.23;
pfBoolean : Crpe1.ParamFields[cnt].AsBoolean := True;
pfDate : Crpe1.ParamFields[cnt].AsDate := Now;
pfString : Crpe1.ParamFields[cnt].Value := 'CA';
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 466
ParamFicIds Prumpt prupcrty
DccIaratiun
property Prompt: string;
Dcscriptiun
The Prompt property specifies the prompting text, if any, that will appear on the Parameter Prompt dialog box.
This will be either the prompting text assigned when the Parameter field was first inserted into the Report, or
the prompting text that was set from code.
If the ShowDialog property is false, then the Prompt dialog box will not appear, so there is no need, in that
case, to set the Prompt property.
fxampIc
This example changes the Prompt property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].ShowDialog := True;
Crpe1.ParamFields[0].Prompt := 'Enter the State:';
Crpe1.ParamFields[0].Value := 'CA';
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds Rangcs prupcrty
DccIaratiun
property Ranges: TCrpeParamFieldRanges;
Typc
TCrpeParamFieldRanges = class(TPersistent)Description
Only available with SCR 7 and higher. The Ranges object is an extension of ParamFields that adds range
capability to the Parameter values that can be passed to a Report. Ranges are different from regular Parameters
in that they have a starting and ending value, instead of just a single value.
When a Report is designed, the Parameter field can be set up as having Discrete (single) values, or having
Range (start and end) values. This can be changed at runtime via the ParamField.Info.ValueType property.
The ValueType of a ParamField must be vtRanges in order for the Range object properties to have an effect.
VCI Re|etetce 461
Ranges are similar to "Current" values, in that there will be no range values in a Report unless it has been run
already, or it has Saved Data. Therefore, passing values via the Ranges object is normally not done unless you
want to bypass the Crystal Reports Parameter Field dialog for that particular Parameter. If the Parameter
dialog is to appear, then possible choices for the start and end range values should be passed via the
ParamField.DefaultValues property.
G The Retrieve method will fetch the Ranges values from the Report and fill the Ranges object with
corresponding items.
G The Count method returns the number of Ranges items currently contained in the Ranges object.
G The Number property specifies Range Number of the item that the Ranges object is currently pointing
to.
G The Item and ItemIndex properties can be used to navigate through the Ranges object.
G The RangeStart property determines the starting value of the Range.
G The RangeEnd property determines the ending value of the Range.
G The RangeBounds property determines how Crystal Reports will treat the values that match the range;
that is, whether the values that fall within the Range include the RangeStart and RangeEnd values, or
exclude them.
G The Clear method removes all items from the Ranges object.
G The Add and Delete methods provide a manual alternative to Retrieve/Clear for adding and deleting
items from the Ranges object.
ParamFicIds Rangcs fxampIc
The following example illustrates the use of the Ranges object:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the Parameters}
Crpe1.ParamFields.Retrieve;
{ByPass the Parameter Prompt Dialog}
Crpe1.ParamFields[0].ShowDialog := False;
{Make sure ValueType is set to Ranges}
Crpe1.ParamFields[0].Info.ValueType := vtRanges;
{Clear Ranges, just to be safe}
Crpe1.ParamFields[0].Ranges.Clear;
{Add a Range}
Crpe1.ParamFields[0].Ranges.Add(0);
Crpe1.ParamFields[0].Ranges[0].RangeStart := 'CA';
Crpe1.ParamFields[0].Ranges[0].RangeEnd := 'WA';
Crpe1.ParamFields[0].Ranges[0].RangeBounds := IncludeStartAndEnd;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 462
ParamFicIds Rangcs ltcm prupcrty
DccIaratiun
property Item[nIndex: integer]: TCrpeParamFieldRanges;
Dcscriptiun
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 Ranges object, allowing the object to be treated like an array.
G Item is a default property, it does not need to be specified when using the subscript: Ranges[2] is the
same as Ranges.Item[2].
G Item returns a reference to itself, so the Ranges properties can be used right after the subscript:
Ranges[2].RangeBounds := IncludeStartAndEnd;
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
{Set Ranges to the 1st Range}
Crpe1.ParamFields[0].Ranges.Item[0];
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
{Set Ranges to the 1st Range}
Crpe1.ParamFields[0].Ranges[0];
ParamFicIds Rangcs ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current Ranges item number, or set the
Ranges 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 (Expressions[2], for example), or whenever the key property (if applicable)
is assigned a new lookup value (key properties are things like Expressions.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.
VCI Re|etetce 46!
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the Ranges object is pointing to
the first Range:
if Crpe1.ParamFields[0].Ranges.ItemIndex <> 0 then
Crpe1.ParamFields[0].Ranges[0];
ParamFicIds Rangcs Numbcr prupcrty
DccIaratiun
property Number: TCrRangeNumber;
Typc
TCrRangeNumber = integer;
Dcscriptiun
The Number property specifies the Range Number of the item that the Ranges object is currently pointing to.
fxampIc
This example retrieves the ParamFields values from the Report (the Range values are retrieved with the
ParamFields), and uses the Number property to set the first Range:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the ParamFields from the Report}
Crpe1.ParamFields.Retrieve;
if Crpe1.ParamFields[0].Ranges.Count > 0 then
begin
{Set the ParamFields Ranges object to the first Range}
Crpe1.ParamFields[0].Ranges.Number := 0;
{Assign the values for the first Range}
Crpe1.ParamFields[0].Ranges.RangeStart := 'CA';
Crpe1.ParamFields[0].Ranges.RangeEnd := 'WA';
Crpe1.ParamFields[0].Ranges.RangeBounds := IncludeStartAndEnd;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 464
ParamFicIds Rangcs RangcBuunds prupcrty
DccIaratiun
property RangeBounds: TCrRangeBounds;
Typc
TCrRangeBounds = (IncludeStartAndEnd, IncludeStartOnly, IncludeEndOnly,
ExcludeStartAndEnd);
Dcscriptiun
The RangeBounds property determines whether the limit of values that can be entered into the Parameter
include the RangeStart and RangeEnd values, or exclude them. When using the Add method, the default
setting for RangeBounds is IncludeStartAndEnd.
fxampIc
The following example illustrates the use of the Ranges object:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the Parameters}
Crpe1.ParamFields.Retrieve;
{ByPass the Parameter Prompt Dialog}
Crpe1.ParamFields[0].ShowDialog := False;
{Make sure ValueType is set to Ranges}
Crpe1.ParamFields[0].Info.ValueType := vtRanges;
{Clear Ranges, just to be safe}
Crpe1.ParamFields[0].Ranges.Clear;
{Add a Range}
Crpe1.ParamFields[0].Ranges.Add(0);
Crpe1.ParamFields[0].Ranges[0].RangeStart := 'CA';
Crpe1.ParamFields[0].Ranges[0].RangeEnd := 'WA';
Crpe1.ParamFields[0].Ranges[0].RangeBounds := IncludeStartAndEnd;
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds Rangcs Rangcfnd prupcrty
DccIaratiun
property RangeEnd: string;
VCI Re|etetce 46S
Dcscriptiun
The RangeEnd property determines the starting value of the Range. Depending on the setting of the
RangeBounds property, the actual Range (as Crystal Reports sees it) will either include the RangeEnd value,
or exclude it.
fxampIc
The following example illustrates the use of the Ranges object:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the Parameters}
Crpe1.ParamFields.Retrieve;
{ByPass the Parameter Prompt Dialog}
Crpe1.ParamFields[0].ShowDialog := False;
{Make sure ValueType is set to Ranges}
Crpe1.ParamFields[0].Info.ValueType := vtRanges;
{Clear Ranges, just to be safe}
Crpe1.ParamFields[0].Ranges.Clear;
{Add a Range}
Crpe1.ParamFields[0].Ranges.Add(0);
Crpe1.ParamFields[0].Ranges[0].RangeStart := 'CA';
Crpe1.ParamFields[0].Ranges[0].RangeEnd := 'WA';
Crpe1.ParamFields[0].Ranges[0].RangeBounds := IncludeStartAndEnd;
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds Rangcs RangcStart prupcrty
DccIaratiun
property RangeStart: string;
Dcscriptiun
The RangeStart property determines the starting value of the Range. Depending on the setting of the
RangeBounds property, the actual Range (as Crystal Reports sees it) will either include the RangeStart value,
or exclude it.
VCI Re|etetce 466
fxampIc
The following example illustrates the use of the Ranges object:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the Parameters}
Crpe1.ParamFields.Retrieve;
{ByPass the Parameter Prompt Dialog}
Crpe1.ParamFields[0].ShowDialog := False;
{Make sure ValueType is set to Ranges}
Crpe1.ParamFields[0].Info.ValueType := vtRanges;
{Clear Ranges, just to be safe}
Crpe1.ParamFields[0].Ranges.Clear;
{Add a Range}
Crpe1.ParamFields[0].Ranges.Add(0);
Crpe1.ParamFields[0].Ranges[0].RangeStart := 'CA';
Crpe1.ParamFields[0].Ranges[0].RangeEnd := 'WA';
Crpe1.ParamFields[0].Ranges[0].RangeBounds := IncludeStartAndEnd;
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds Rangcs Add mcthud
DccIaratiun
procedure Add(RangeNumber: TCrRangeNumber);
Typc
TCrRangeNumber = integer;
Dcscriptiun
The Add method adds an item to the Ranges object and sets the internal index to that item. It requires a Range
number (zero based) as a parameter.
The steps to using the Add method with Ranges are:
1 Add an item to the Ranges object (you must specify the Range Number).
2 Fill the item's properties (RangeStart, RangeEnd, and RangeBounds) with values.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il lhe Parameler s sel u lo execl a sngle Range (ParamFelds.Inlo.AllowMullleValues s sel lo
cFalse), lhen only one Range lem wll be requred. Il lhe Parameler s sel u lo execl an array ol Ranges
(ParamFelds.Inlo.AllowMullleValues s sel lo c7rue), lhen as many Range lems as desred can be added lo
lhe Ranges objecl.
VCI Re|etetce 467
fxampIc
The Add method can be used to manually add an item to the Ranges object:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
{Specify Range Number}
Crpe1.ParamFields[0].Ranges.Add(0);
Crpe1.ParamFields[0].Ranges[0].RangeStart := 'CA';
Crpe1.ParamFields[0].Ranges[0].RangeEnd := 'WA';
Crpe1.ParamFields[0].Ranges[0].RangeBounds := IncludeStartAndEnd;
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds Rangcs CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the ParamField Ranges 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, or if the Paramfield.Clear method is called, but may be called in code as desired.
fxampIc
This code clears the ParamField Ranges for the first ParamField in the main Report (assuming the default state
of Subreports[0]):
Crpe1.ParamFields[0].Ranges.Clear;
NO7F: Usng ParamFelds.Clear nslead, wll clear all lhe Ranges lor all lhe ParamFelds al once.
ParamFicIds Rangcs CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeParamFieldRanges): boolean;
Dcscriptiun
The CopyFrom method copies the Ranges property values from another TCrpeParamFieldRanges object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
VCI Re|etetce 468
fxampIc
The following example copies all the Ranges property values to a temporary TCrpeParamFieldRanges object:
var
tempRanges : TCrpeParamFieldRanges;
begin
tempRanges := TCrpeParamFieldRanges.Create;
tempRanges.CopyFrom(Crpe1.ParamFields.Ranges);
{...later, when finished with the temp object...}
tempRanges.Free;
end;
ParamFicIds Rangcs Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the Ranges object. It is handy for
setting up loops to make similar changes to each item.
fxampIc
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.ParamFields.Retrieve;
if Crpe1.ParamFields[0].Ranges.Count > 0 then
begin
for cnt := 0 to (Crpe1.ParamFields[0].Ranges.Count - 1) do
Crpe1.ParamFields[0].Ranges[cnt].RangeBounds := IncludeStartAndEnd;
end;
end;
ParamFicIds Rangcs Crcatc mcthud
DccIaratiun
constructor Create;
VCI Re|etetce 460
Dcscriptiun
The Create method is used internally in the Crystal component to create the Ranges object, and does not need
to be called in code, unless you are using the CopyFrom method to store Ranges data to a temporary object:
var
tempRanges : TCrpeParamFieldRanges;
begin
tempRanges := TCrpeParamFieldRanges.Create;
tempRanges.CopyFrom(Crpe1.ParamFields.Ranges);
end;
ParamFicIds Rangcs DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the Ranges object. The "nIndex" parameter represents
the order of the item in the Ranges object, which should not be confused with the Range Number value.
fxampIc
The Delete method can be used to manually remove an item from the Ranges object:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
{Specify Range Number}
Crpe1.ParamFields[0].Ranges.Add(0);
Crpe1.ParamFields[0].Ranges[0].RangeStart := 'CA';
Crpe1.ParamFields[0].Ranges[0].RangeEnd := 'WA';
Crpe1.ParamFields[0].Ranges[0].RangeBounds := IncludeStartAndEnd;
Crpe1.Output := toWindow;
Crpe1.Execute;
{Specify the item number}
Crpe1.ParamFields[0].Ranges.Delete(0);
ParamFicIds Rangcs Dcstruy mcthud
DccIaratiun
destructor Destroy;
VCI Re|etetce 476
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
ParamFicIds Rangcs Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the Parameter Field Ranges information (for the current ParamFields item) from
the Report and stores it in the Ranges object. If Ranges information was not found, the call returns False. If
there are no Ranges items in the Report, they can be added using the manual Add method.
fxampIc
In this code example, the first ParamField item is manually created using the Add method. The Add method
requires the Parameter Name (assumed as "Parameter1" in this example) and the Report Name (blank for the
main Report). Then the ParamField Ranges property values are retrieved:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Add('Parameter1', '');
Crpe1.ParamFields[0].Ranges.Retrieve;
ParamFicIds Rangcs Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the Ranges 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), or when
ParamFields.Send is called.
VCI Re|etetce 471
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.
fxampIc
In this example, the ParamFields Ranges settings for the first ParamField are sent from the Crystal component
to the Crystal Reports Print Engine DLL. This is normally handled automatically for each ParamField in the
ParamFields.Send method which is in turn called by the Execute method:
Crpe1.ParamFields[0].Ranges.Send;
ParamFicIds RcpurtNamc prupcrty
DccIaratiun
property ReportName: string;
Dcscriptiun
ReportName is a runtime, read-only property that specifies which Report the Parameter applies to. It will only
contain a meaningful value if the Retrieve method is used to fetch the ParamFields items. Any Parameters that
apply to the main Report will have a blank value for ReportName.
NO7F: For Subreorls, lhe ReorlName roerly holds lhe same value as lhe Reorl7lle and Subreorls.Name
roerles. Il lhe Reorl7lle lor a Subreorl s changed, l s recommended lhal lhe Subreorls and ParamFelds
objecls be cleared and reloaded belore allemlng lo run lhe Reorl lwce n a row.
fxampIc
In this example, because there are two Parameter fields with the same name (one in the main Report and one
in the Subreport), the ReportName property is checked to distinguish the ParamFields:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
for cnt := 0 to Crpe1.ParamFields.Count - 1 do
begin
if Crpe1.ParamFields[cnt].ReportName = 'Sub1' then
Crpe1.ParamFields[cnt].Value := 'CA';
else
Crpe1.ParamFields[cnt].Value := 'WA';
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
VCI Re|etetce 472
ParamFicIds ShuwDiaIug prupcrty
DccIaratiun
property ShowDialog: boolean;
Dcscriptiun
The ShowDialog property determines if the Parameter prompt dialog box will appear or not. There are two
ways to use Parameter Fields at runtime:
1. Pass a value directly into the Parameter without seeing the Parameter prompt dialog box. In this case,
ShowDialog should be set to False.
2. Change the default value that the Parameter contains, but show the Parameter prompt dialog anyway to
allow the user to change it. In this case, ShowDialog should be set to True.
The default value for ShowDialog is False.
fxampIc
In the example below, one Parameter field will not be prompted for, and the other one will. When the prompt
dialog box appears, 'WA' will be the default value:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
{Change value and do not prompt for this one}
Crpe1.ParamFields[0].Value := 'CA';
Crpe1.ParamFields[0].ShowDialog := False;
{Change value but prompt for this one}
Crpe1.ParamFields[1].Value := 'WA';
Crpe1.ParamFields[1].ShowDialog := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds VaIuc prupcrty
DccIaratiun
property Value: string;
VCI Re|etetce 47!
Dcscriptiun
The Value property specifies the value that is to be passed into the Parameter field. This must be formatted as
a string, regardless of the ParamType. Here are some examples which show how to pass each Parameter type:

There are six other properties that can be used to read and write the Value property using native Delphi types:
AsNumber, AsCurrency, AsBoolean, AsDate, AsDateTime, AsTime.
NO7F: Wlh SCR 7, mullle delaull and currenl values can be assed as Paramelers. A delaull value s one
lhal wll aear n lhe Parameler roml dalog lor ossble seleclon by lhe user. A currenl value s one lhal
s a Parameler value lhal has already been selecled and assed nlo a Reorl Parameler, elher by lhe
rogrammng lronl-end, or by lhe user seleclng an lem n lhe Parameler dalog.
With the last Crystal 6 version of the VCL, only the Value property was of concern, and if the ShowDialog
property was set to True, the Value property was passed to the Report as a default value; if the ShowDialog
property was set to False, the Value property was passed into the Report as a current value.
However, with this new release, since it is possible to have multiple default and current values, a simple string
property is not good enough to handle this. So two new StringList properties were added: DefaultValues and
CurrentValues. If the DefaultValues or CurrentValues properties of the ParamFields object have values in
them, these will take precedence over what may be stored or set in the Value property.
NO7F: Very Imorlanl! Because DelaullValues and CurrenlValues wll lake recedence over lhe Value
roerly, l would be a good dea lo coy lhe Value roerly nlo lhe DelaullValues[0] slrng, or lhe
CurrenlValues[0] slrng, lo make sure lhe slrng slored n lhe Value roerly gels assed n lo lhe Reorl
wlhoul beng overwrllen by DelaullValues[0] or CurrenlValues[0].
Param7ye Value
pfNumber '235'
pfCurrency '2.35'
pfBoolean 'True'
pfDate '1999,01,30' {YYYY,MM,DD}
pfString 'Vancouver'
pfDateTime '1999,01,30 1:12:14' {YYYY,MM,DD HH:MM:SS} {SCR 7 only}
pfTime '1:12:14' {HH:MM:SS} {SCR 7 only}
VCI Re|etetce 474
fxampIc
This example illustrates the Value and AsDate, etc. properties to set Parameter Field values:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
Crpe1.ParamFields[0].Value := 'CA';
Crpe1.ParamFields[1].AsDate := Now;
Crpe1.ParamFields[2].AsNumber := 3;
Crpe1.ParamFields[3].AsBoolean := True;
Crpe1.ParamFields[4].AsCurrency := 1.23;
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds VaIuclimit prupcrty
DccIaratiun
property ValueLimit: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The ValueLimit, ValueMin, and ValueMax properties work together. They provide a way of limiting the input
in the Parameter prompt dialog edit field. ValueLimit simply determines whether the ValueMin and
ValueMax properties are active or not. If ValueLimit is set to cFalse, the ValueMin and ValueMax properties
will be ignored.
With string Parameters, ValueMin and ValueMax limit the length of the string that can be input. With other
types, ValueMin and ValueMax contain the actual minimum and maximum values that can be entered.
NO7F:
G Value lmls, and lhe FdlMask roerly are mulually exclusve. Il an FdlMask s delned, value lmls wll
be gnored.
G Value lmls do nol aly lo Boolean Paramelers.
VCI Re|etetce 47S
fxampIc
This example sets a ValueLimit for two ParamFields, a string and a datetime parameter:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
{String Parameter: Entry Limit of 1 to 3 characters long}
Crpe1.ParamFields[0].ShowDialog := True;
Crpe1.ParamFields[0].ValueLimit := cTrue;
Crpe1.ParamFields[0].ValueMin := '1';
Crpe1.ParamFields[0].ValueMax := '3';
{DateTime Parameter: Entry must be between min and max datetime}
Crpe1.ParamFields[1].ShowDialog := True;
Crpe1.ParamFields[1].ValueLimit := cTrue;
Crpe1.ParamFields[1].ValueMin := '1998,01,01 12:00:00';
Crpe1.ParamFields[1].ValueMax := '1999,01,01 12:00:00';
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds VaIucMax prupcrty
DccIaratiun
property ValueMax: string;
Dcscriptiun
The ValueLimit, ValueMin, and ValueMax properties work together. They provide a way of limiting the input
in the Parameter prompt dialog edit field. ValueLimit simply determines whether the ValueMin and
ValueMax properties are active or not. If ValueLimit is set to cFalse, the ValueMin and ValueMax properties
will be ignored.
With string Parameters, ValueMin and ValueMax limit the length of the string that can be input. With other
types, ValueMin and ValueMax contain the actual minimum and maximum values that can be entered.
NO7F:
G Value lmls, and lhe FdlMask roerly are mulually exclusve. Il an FdlMask s delned, value lmls wll
be gnored.
G Value lmls do nol aly lo Boolean Paramelers.
VCI Re|etetce 476
fxampIc
This example sets a ValueLimit for two ParamFields, a string and a datetime parameter:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
{String Parameter: Entry Limit of 1 to 3 characters long}
Crpe1.ParamFields[0].ShowDialog := True;
Crpe1.ParamFields[0].ValueLimit := cTrue;
Crpe1.ParamFields[0].ValueMin := '1';
Crpe1.ParamFields[0].ValueMax := '3';
{DateTime Parameter: Entry must be between min and max datetime}
Crpe1.ParamFields[1].ShowDialog := True;
Crpe1.ParamFields[1].ValueLimit := cTrue;
Crpe1.ParamFields[1].ValueMin := '1998,01,01 12:00:00';
Crpe1.ParamFields[1].ValueMax := '1999,01,01 12:00:00';
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds VaIucMin prupcrty
DccIaratiun
property ValueMin: string;
Dcscriptiun
The ValueLimit, ValueMin, and ValueMax properties work together. They provide a way of limiting the input
in the Parameter prompt dialog edit field. ValueLimit simply determines whether the ValueMin and
ValueMax properties are active or not. If ValueLimit is set to cFalse, the ValueMin and ValueMax properties
will be ignored.
With string Parameters, ValueMin and ValueMax limit the length of the string that can be input. With other
types, ValueMin and ValueMax contain the actual minimum and maximum values that can be entered.
NO7F:
G Value lmls, and lhe FdlMask roerly are mulually exclusve. Il an FdlMask s delned, value lmls wll
be gnored.
G Value lmls do nol aly lo Boolean Paramelers.
VCI Re|etetce 477
fxampIc
This example sets a ValueLimit for two ParamFields, a string and a datetime parameter:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
{String Parameter: Entry Limit of 1 to 3 characters long}
Crpe1.ParamFields[0].ShowDialog := True;
Crpe1.ParamFields[0].ValueLimit := cTrue;
Crpe1.ParamFields[0].ValueMin := '1';
Crpe1.ParamFields[0].ValueMax := '3';
{DateTime Parameter: Entry must be between min and max datetime}
Crpe1.ParamFields[1].ShowDialog := True;
Crpe1.ParamFields[1].ValueLimit := cTrue;
Crpe1.ParamFields[1].ValueMin := '1998,01,01 12:00:00';
Crpe1.ParamFields[1].ValueMax := '1999,01,01 12:00:00';
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds Mcthuds
ParamFicIds Add mcthud
DccIaratiun
procedure Add(ParameterName: TCrParameterFieldName; ReportName:
TCrParamFieldReportName);
Typc
TCrParameterFieldName = string[255];
TCrParamFieldReportName = string[128];
Dcscriptiun
The Add method adds an item to the ParamFields object and sets the internal index to that item. It requires a
Parameter Field name and a Report Name as parameters, which should correspond to a Parameter Field Name
in the Report and a valid Report Name (the Main Report does not have a Report Name -- use an empty string).
If the Add method is used instead of Retrieve, the steps to using ParamFields are:
1 Add an item to the ParamFields object (you must specify the Parameter Field name and Report Name).
2 Fill the item's properties (Value, Prompt, etc.) with values.
VCI Re|etetce 478
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
Parameler numbers are correcl lor lhe currenl Reorl.
fxampIc
The Add method can be used to manually add an item to the ParamFields object, instead of using Retrieve:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Parameter Name - must be same as in Report}
Crpe1.ParamFields.Add('Parameter1');
Crpe1.ParamFields.Value := 'CA';
Crpe1.Output := toWindow;
Crpe1.Execute;
ParamFicIds CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the ParamFields 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 ParamFields object of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the ParamFields of all the Subreports will require a looping procedure
that goes through each Subreport and applies the Clear method:
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.ParamFields.Clear;
end;
fxampIc
This code clears the ParamFields properties for the main Report (assuming the default state of Subreports[0]):
Crpe1.ParamFields.Clear;
This code clears the ParamFields properties for the second Subreport:
Crpe1.Subreports[2];
Crpe1.ParamFields.Clear;
VCI Re|etetce 470
ParamFicIds CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeParamFields): boolean;
Dcscriptiun
The CopyFrom method copies the ParamFields property values from another TCrpeParamFields object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the ParamFields property values to a temporary TCrpeParamFields object:
var
tempParamFields : TCrpeParamFields;
begin
tempParamFields := TCrpeParamFields.Create;
tempParamFields.CopyFrom(Crpe1.ParamFields);
{...later, when finished with the temp object...}
tempParamFields.Free;
end;
ParamFicIds Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the ParamFields object. It is handy
for setting up loops to make similar changes to each item.
fxampIc
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.ParamFields.Retrieve;
for cnt := 0 to (Crpe1.ParamFields.Count - 1) do
Crpe1.ParamFields[cnt].Value := 'CA';
end;
VCI Re|etetce 486
ParamFicIds Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the ParamFields object, and does not
need to be called in code.
ParamFicIds DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the ParamFields object. The "nIndex" parameter
represents the number of the item in the ParamFields object.
NO7F: Delele wll nol remove lhe Parameler Feld lrom lhe Reorl, l wll jusl remove l lrom lhe Cryslal VCI.
fxampIc
The Delete method can be used to manually remove an item from the ParamFields object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Parameter Name - must be same as in Report}
Crpe1.ParamFields.Add('Parameter1');
Crpe1.ParamFields.Value := 'CA';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.ParamFields.Delete(0);
ParamFicIds Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
VCI Re|etetce 481
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
ParamFicIds lndcxOf mcthud
DccIaratiun
function IndexOf(ParameterName: TCrParamFieldName): integer;
Typc
TCrParamFieldName = string[255];
Dcscriptiun
The IndexOf method takes a Parameter name and returns the index position of the Parameter item in the
current ParamFields object.
After the Retrieve method has been called, the ParamFields object contains one item for each ParamField in
the Report. The IndexOf method can be used to determine if a given Parameter Name actually exists in the
ParamFields object before trying to access it.
fxampIc
The following code illustrates the use of the IndexOf method to locate a specific ParamField item by it's name:
var
nItem: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ParamFields.Retrieve;
{Find "Param1"}
nItem := Crpe1.ParamFields.IndexOf('Param1');
{If it exists...}
if nItem > -1 then
begin
with Crpe1.ParamFields[nItem] do
begin
Value := 'CA';
VCI Re|etetce 482
ShowDialog := False;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ParamFicIds Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the Parameter Field information from the Report and adds one item to the
ParamFields object for each Parameter in the Report. If Parameter Fields were not found, the call returns False.
Be aware that calling Retrieve will first cause the ParamFields object to be cleared, so any current information
stored in it will be removed.
Rctricving frum thc Main Rcpurt
ParamFields are treated slightly differently by the Print Engine than most of the other properties. Calling
Retrieve for the main Report will return all the ParamFields from the main Report, as well as all the ParamFields
from any Subreports. This is because Parameter fields are considered in a certain sense to be part of the main
Report, since refreshing the main Report in Crystal Reports will cause the Parameter prompt dialog to display
all of the Parameters that require values, whether they are located in the main Report, or in a Subreport.
When retrieving ParamFields for a main Report, any Parameters in a Subreport, that are linked to the main
Report, will still be retrieved, but the NeedsCurrentValue property will read False, which means that these
Parameter fields do not require values to be set in code, since they will obtain their values from the link to the
main Report, when the Report is run.
Rctricving frum a Subrcpurt
In most cases, you will want to work with the Parameters as returned in the main Report ParamFields object.
However, if you are going to be running Subreports separate from the main Report (see SubExecute), the
ParamFields should be retrieved for that Subreport specifically. In other words, the Subreports object should
be pointing to the Subreport that is going to be run, before Paramfields.Retrieve is called. This will cause the
ParamFields object for that Subreport to be filled with information on the Parameter fields that apply
specifically to that Subreport. In such a case, any Parameter fields that are linked to the main Report will
appear as unlinked, since they are expecting a value, and will not be getting the value from the main Report
when the Subreport is run as stand-alone.
VCI Re|etetce 48!
fxampIc
The following code will retrieve all the Parameter fields in a Report, whether they are in a main Report or a
Subreport. Note that ParamFields behave slightly differently in this respect than other objects:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the ParamFields}
Crpe1.ParamFields.Retrieve;
The next example shows how to retrieve only the Parameter fields that apply to a specific Subreport. This should
only be necessary if the Subreport is going to be run as a stand-alone Report, separate from the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the Subreports items}
Crpe1.Subreports.Retrieve;
{Allow Subreports to be run stand-alone}
Crpe1.Subreports.SubExecute := True;
{Set the Crpe to point to the 2nd Subreport}
Crpe1.Subreports[2];
{Retrieve the ParamFields for the 2nd Subreport}
Crpe1.ParamFields.Retrieve;
ParamFicIds Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the ParamFields 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 recommend 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.
fxampIc
In this example, the ParamFields settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.ParamFields.Send;
VCI Re|etetce 484
PrintDatc Prupcrtics
PrintDatc Day prupcrty
DccIaratiun
property Day: Word;
Dcscriptiun
This property sets the Day portion of the PrintDate. Enter a Day value from 1 to 31. When setting PrintDate,
all three properties (Day, Month, Year) must be greater than 0 for the new PrintDate to take effect.
fxampIc
The following sample sets the PrintDate to January 1, 1999:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.PrintDate.Day := 1;
Crpe1.PrintDate.Month := 1;
Crpe1.PrintDate.Year := 1999;
Crpe1.Execute;
PrintDatc Munth prupcrty
DccIaratiun
property Month: Word;
Dcscriptiun
This property sets the Month portion of the PrintDate. Enter a Month value from 1 to 12, where January = 1
and December = 12. When setting PrintDate, all three properties (Day, Month, Year) must be greater than 0 for
the new PrintDate to take effect.
fxampIc
The following sample sets the PrintDate to January 1, 1999:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.PrintDate.Day := 1;
Crpe1.PrintDate.Month := 1;
Crpe1.PrintDate.Year := 1999;
Crpe1.Execute;
VCI Re|etetce 48S
PrintDatc Ycar prupcrty
DccIaratiun
property Year: Word;
Dcscriptiun
This property sets the Year portion of the PrintDate. Enter the Year as a four-digit number. When setting
PrintDate, all three properties (Day, Month, Year) must be greater than 0 for the new PrintDate to take effect.
fxampIc
The following sample sets the PrintDate to January 1, 1999:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.PrintDate.Day := 1;
Crpe1.PrintDate.Month := 1;
Crpe1.PrintDate.Year := 1999;
Crpe1.Execute;
PrintDatc Mcthuds
PrintDatc CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to set the PrintDate properties to their default values:
Day := 0;
Month := 0;
Year := 0;
It is called automatically if the Clear method is called for the main component, but may be called in code as
needed.
fxampIc
This line of code clears the PrintDate properties:
Crpe1.PrintDate.Clear;
VCI Re|etetce 486
PrintDatc CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpePrintDate): boolean;
Dcscriptiun
The CopyFrom method copies the PrintDate property values from another TCrpePrintDate object. It is similar
to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the PrintDate property values to a temporary TCrpePrintDate object:
var
tempPrintDate : TCrpePrintDate;
begin
tempPrintDate := TCrpePrintDate.Create;
tempPrintDate.CopyFrom(Crpe1.PrintDate);
{...later, when finished with the temp object...}
tempPrintDate.Free;
end;
PrintDatc Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the PrintDate information from the Report. Returns True if the call succeeded.
NO7F: Snce lhe PrnlDale objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe PrnlDale lor
lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl lo oblan lhe
PrnlDale sellngs lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle lhrough lhe Subreorls
objecl and call Relreve lor each lem. 7he VCI wll slore searale PrnlDale sellngs lor each Subreorl.
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Margins.Retrieve;
VCI Re|etetce 487
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.Margins.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
PrintDatc Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the PrintDate 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.
fxampIc
In this example, the PrintDate settings are sent from the Crystal component to the Crystal Reports Print Engine
DLL. This is normally handled automatically in the Execute method:
Crpe1.PrintDate.Send;
VCI Re|etetce 488
Printcr Prupcrtics
Printcr Drivcr prupcrty
DccIaratiun
property Driver: TCrPrinterName;
Typc
TCrPrinterName = string[80];
Dcscriptiun
The Driver property contains the Driver name of the Printer.
Traditionally, the Crystal VCL used to require the Name, Driver, Port and Mode properties to be set before it
would change the Printer for a Report. With the new Crystal component, however, this is not required. The
only property that needs to be specified is the Name. The component will automatically fill in the other values
(if the Printer Name is valid), when the component's Execute method is called.
If the Retrieve method is used, the Driver property will contain the Driver name for the Printer that was
specified in the Report (or the default printer if the Printer specified in the Report is not valid). Alternatively,
the GetCurrent method can be called right after showing Delphi's PrintDialog, and it will also fill the Printer
properties with values corresponding to the selected Printer.
fxampIc
This code uses the Printer properties to change Printers to one selected via the Print Dialog. It also makes sure
that the Orientation defined in the Report is preserved.
procedure RunReport;
var
lpPrinter, lpDriver, lpPort : pChar;
hMode : THandle;
pMode : PDevMode;
nOrientation : integer;
begin
{Set ReportName}
Crpe1.ReportName := 'C:\Company.rpt';
{Get Printer settings from Report}
Crpe1.Printer.Retrieve;
{Check the Orientation}
hMode := Crpe1.Printer.Mode;
pMode := GlobalLock(hMode);
VCI Re|etetce 480
case pMode^.dmOrientation of
DMORIENT_PORTRAIT : nOrientation := 0;
DMORIENT_LANDSCAPE : nOrientation := 1;
end;
GlobalUnlock(hMode);
{Allocate memory for Printer property variables}
try
lpPrinter := StrAlloc(255);
lpDriver := StrAlloc(255);
lpPort := StrAlloc(255);
except
if lpPrinter <> nil then
StrDispose(lpPrinter);
if lpDriver <> nil then
StrDispose(lpDriver);
if lpPort <> nil then
StrDispose(lpPort);
Exit;
end;
{Show the PrintDialog}
if PrintDialog1.Execute then {if OK was clicked}
begin
{Get Selected Printer; could also use Crpe1.SelectPrinter}
Printer.GetPrinter(lpPrinter, lpDriver, lpPort, hMode);
{Set PrinterName}
Crpe1.Printer.Name := StrPas(lpPrinter);
{Set PrinterDriver: Check for Null - Win95 32-bit problem}
if Length(StrPas(lpDriver)) <> 0 then
Crpe1.Printer.Driver := StrPas(lpDriver)
else
Crpe1.Printer.Driver := StrPas(lpPrinter);
Set PrinterPort}
Crpe1.Printer.Port := StrPas(lpPort);
{Set PrinterMode}
Crpe1.Printer.Mode := hMode;
{Make sure the Orientation remains as in Report}
pMode := GlobalLock(hMode);
case nOrientation of
0: pMode^.dmOrientation := DMORIENT_PORTRAIT;
1: pMode^.dmOrientation := DMORIENT_LANDSCAPE;
end;
GlobalUnlock(hMode);
VCI Re|etetce 406
{Run the Report}
Crpe1.Execute;
end;
StrDispose(lpPort);
StrDispose(lpDriver);
StrDispose(lpPrinter);
end;
The above code can be greatly simplified by using some of the other Printer object methods & properties:
procedure RunReport;
begin
{Set ReportName}
Crpe1.ReportName := 'C:\test.rpt';
{Preserve Orientation from Report}
Crpe1.Printer.PreserveRptSettings[prOrientation];
{Prompt for Printer at Execute}
Crpe1.Printer.ShowDialog := True;
{Run the Report}
Crpe1.Execute;
end;
Printcr Mudc prupcrty
DccIaratiun
property Mode: integer;
Dcscriptiun
The Mode property specifies a handle to the DevMode structure associated with a certain Printer. This handle
is normally obtained via Delphi's "Printer.GetPrinter" method. Not that it is no longer necessary to fill in a
value for this property, since the Crystal component will obtain this information internally provided a valid
value is specified in the Name property.
Traditionally, the Crystal VCL used to require the Name, Driver, Port and Mode properties to be set before it
would change the Printer for a Report. With the new Crystal component, however, this is not required. The
only property that needs to be specified is the Name. The component will automatically fill in the other values
(if the Printer Name is valid), when the component's Execute method is called.
If the Retrieve method is used, the Mode property will contain the Mode value for the Printer that was
specified in the Report (or the default printer if the Printer specified in the Report is not valid). Alternatively,
the GetCurrent method can be called right after showing Delphi's PrintDialog, and it will also fill the Printer
properties with values corresponding to the selected Printer.Methods.
VCI Re|etetce 401
fxampIc
The following example shows how to use the Mode property to check DevMode settings for the Printer
properties saved with the Report (Orientation in this case). Note that PMode could be used instead, which
would eliminate the need for GlobalLock/GlobalUnlock:
var
hMode : THandle;
pMode : PDevMode;
nOrientation : integer;
begin
{Set ReportName}
Crpe1.ReportName := 'C:\Company.rpt';
{Get Printer settings from Report}
Crpe1.Printer.Retrieve;
{Check the Orientation}
hMode := Crpe1.Printer.Mode;
pMode := GlobalLock(hMode);
case pMode^.dmOrientation of
DMORIENT_PORTRAIT : nOrientation := 0;
DMORIENT_LANDSCAPE : nOrientation := 1;
end;
GlobalUnlock(hMode);
end;
Printcr Namc Prupcrty
DccIaratiun
property Name: TCrPrinterName;
Typc
TCrPrinterName = string[80];
Dcscriptiun
The Name property contains the Printer name of the Printer.
Traditionally, the Crystal VCL used to require the Name, Driver, Port and Mode properties to be set before it
would change the Printer for a Report. With the new Crystal component, however, this is not required. The
only property that needs to be specified is the Name. The component will automatically fill in the other values
(if the Printer Name is valid), when the component's Execute method is called.
VCI Re|etetce 402
If the Retrieve method is used, the Name property will contain the Printer name for the Printer that was
specified in the Report (or the default printer if the Printer specified in the Report is not valid). Alternatively,
the GetCurrent method can be called right after showing Delphi's PrintDialog, and it will also fill the Printer
properties with values corresponding to the selected Printer.
Additionally, the Name can be specified directly from the Delphi Printers array (you will need to add the
Printers unit to the Uses clause before you can use the Printers array):
Crpe1.Printer.Name := Printer.Printers[2];
fxampIc
To change Printers, only the Name property needs to be set (although it will not cause any problems if Driver,
Port and Mode properties are set as well). The rest will be retrieved within the VCL:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Printer.Name := 'HP Laserjet 4';
Crpe1.Execute;
This code uses the Printer properties to change Printers to one selected via the Print Dialog. It also makes sure
that the Orientation defined in the Report is preserved.
procedure RunReport;
var
lpPrinter, lpDriver, lpPort : pChar;
hMode : THandle;
pMode : PDevMode;
nOrientation : integer;
begin
{Set ReportName}
Crpe1.ReportName := 'C:\Company.rpt';
{Get Printer settings from Report}
Crpe1.Printer.Retrieve;
{Check the Orientation}
hMode := Crpe1.Printer.Mode;
pMode := GlobalLock(hMode);
case pMode^.dmOrientation of
DMORIENT_PORTRAIT : nOrientation := 0;
DMORIENT_LANDSCAPE : nOrientation := 1;
end;
GlobalUnlock(hMode);
{Allocate memory for Printer property variables}
try
lpPrinter := StrAlloc(255);
lpDriver := StrAlloc(255);
lpPort := StrAlloc(255);
except
VCI Re|etetce 40!
if lpPrinter <> nil then
StrDispose(lpPrinter);
if lpDriver <> nil then
StrDispose(lpDriver);
if lpPort <> nil then
StrDispose(lpPort);
Exit;
end;
{Show the PrintDialog}
if PrintDialog1.Execute then {if OK was clicked}
begin
{Get Selected Printer; could also use Crpe1.SelectPrinter}
Printer.GetPrinter(lpPrinter, lpDriver, lpPort, hMode);
{Set PrinterName}
Crpe1.Printer.Name := StrPas(lpPrinter);
{Set PrinterDriver: Check for Null - Win95 32-bit problem}
if Length(StrPas(lpDriver)) <> 0 then
Crpe1.Printer.Driver := StrPas(lpDriver)
else
Crpe1.Printer.Driver := StrPas(lpPrinter);
{Set PrinterPort}
Crpe1.Printer.Port := StrPas(lpPort);
{Set PrinterMode}
Crpe1.Printer.Mode := hMode;
{Make sure the Orientation remains as in Report}
pMode := GlobalLock(hMode);
case nOrientation of
0: pMode^.dmOrientation := DMORIENT_PORTRAIT;
1: pMode^.dmOrientation := DMORIENT_LANDSCAPE;
end;
GlobalUnlock(hMode);
{Run the Report}
Crpe1.Execute;
end;
StrDispose(lpPort);
StrDispose(lpDriver);
StrDispose(lpPrinter);
end;
The above code can be greatly simplified by using some of the other Printer object methods & properties:
procedure RunReport;
begin
{Set ReportName}
Crpe1.ReportName := 'C:\test.rpt';
VCI Re|etetce 404
{Preserve Orientation from Report}
Crpe1.Printer.PreserveRptSettings[prOrientation];
{Prompt for Printer at Execute}
Crpe1.Printer.ShowDialog := True;
{Run the Report}
Crpe1.Execute;
end;
Printcr Oricntatiun Prupcrty
DccIaratiun
property Orientation: TCrOrientation;
Typc
TCrOrientation = (orDefault, orPortrait, orLandscape);
Dcscriptiun
The Orientation property can be used to specify a particular orientation for the Report. To preserve the
Orientation as it was when the Report was designed, use the PreserveRptSettings property.
fxampIc
This example illustrates the use of the Orientation property:
{Set ReportName}
Crpe1.ReportName := 'C:\Company.rpt';
{Set the Orientation to Landscape}
Crpe1.Printer.Orientation := orLandscape;
{Run the Report to Window}
Crpe1.Output := toWindow;
Crpe1.Execute;
Printcr PMudc Prupcrty
DccIaratiun
property PMode: Pointer;
VCI Re|etetce 40S
Dcscriptiun
The PMode property specifies a pointer to the DevMode structure associated with a certain Printer, and can
be used to control DevMode-specific properties. Note that it is no longer necessary to fill in a value for this
property, since the Crystal component will obtain this information internally provided a valid value is
specified in the Name property.
The Retrieve method will also fill the PMode property with a value from the Printer settings saved with the
current Report, or the GetCurrent method can be used right after showing the Delphi PrintDialog to obtain the
Printer information and fill the Printer properties with values.
fxampIc
The following example shows how to use the PMode property to check DevMode settings for the Printer
properties saved with the Report (Orientation in this case):
Crpe1.ReportName := 'C:\Company.rpt';
{Get Printer settings from Report}
Crpe1.Printer.Retrieve;
{Check the Orientation}
case Crpe1.Printer.PMode^.dmOrientation of
DMORIENT_PORTRAIT : ShowMessage('Orientation is Portrait');
DMORIENT_LANDSCAPE : ShowMessage('Orientation is Landscape');
end;
Printcr Purt Prupcrty
DccIaratiun
property Port: TCrPrinterName;
Typc
TCrPrinterName = string[80];
Dcscriptiun
The Port property contains the Port name of the Printer.
Traditionally, the Crystal VCL used to require the Name, Driver, Port and Mode properties to be set before it
would change the Printer for a Report. With the new Crystal component, however, this is not required. The
only property that needs to be specified is the Name. The component will automatically fill in the other values
(if the Printer Name is valid), when the component's Execute method is called.
VCI Re|etetce 406
If the Retrieve method is used, the Port property will contain the Port name for the Printer that was specified
in the Report (or the default printer if the Printer specified in the Report is not valid). Alternatively, the
GetCurrent method can be called right after showing Delphi's PrintDialog, and it will also fill the Printer
properties with values corresponding to the selected Printer.
NO7F: Do nol alleml lo sel lhe Porl roerly lo FIIF: l lhe Prnler Drver has nol been sel u lhal way. Il
wll nol work. Cryslal Reorls 7 has bull-n suorl lor rnlng lo FIIF va lhe OululFleName roerly ol
lhe PrnlOlons class. For Cryslal S and 6 users, see Sellng Porl lo FIIF.
fxampIc
This code uses the Printer properties to change Printers to one selected via the Print Dialog. It also makes sure
that the Orientation defined in the Report is preserved.
procedure RunReport;
var
lpPrinter, lpDriver, lpPort : pChar;
hMode : THandle;
pMode : PDevMode;
nOrientation : integer;
begin
{Set ReportName}
Crpe1.ReportName := 'C:\Company.rpt'
{Get Printer settings from Report}
Crpe1.Printer.Retrieve;
{Check the Orientation}
hMode := Crpe1.Printer.Mode;
pMode := GlobalLock(hMode);
case pMode^.dmOrientation of
DMORIENT_PORTRAIT : nOrientation := 0;
DMORIENT_LANDSCAPE : nOrientation := 1;
end;
GlobalUnlock(hMode);
{Allocate memory for Printer property variables}
try
lpPrinter := StrAlloc(255);
lpDriver := StrAlloc(255);
lpPort := StrAlloc(255);
except
if lpPrinter <> nil then
StrDispose(lpPrinter);
if lpDriver <> nil then
StrDispose(lpDriver);
if lpPort <> nil then
StrDispose(lpPort);
Exit;
end;
VCI Re|etetce 407
{Show the PrintDialog}
if PrintDialog1.Execute then {if OK was clicked}
begin
{Get Selected Printer; could also use Crpe1.SelectPrinter}
Printer.GetPrinter(lpPrinter, lpDriver, lpPort, hMode);
{Set PrinterName}
Crpe1.Printer.Name := StrPas(lpPrinter);
{Set PrinterDriver: Check for Null - Win95 32-bit problem}
if Length(StrPas(lpDriver)) <> 0 then
Crpe1.Printer.Driver := StrPas(lpDriver)
else
Crpe1.Printer.Driver := StrPas(lpPrinter);
{Set PrinterPort}
Crpe1.Printer.Port := StrPas(lpPort);
{Set PrinterMode}
Crpe1.Printer.Mode := hMode;
{Make sure the Orientation remains as in Report}
pMode := GlobalLock(hMode);
case nOrientation of
0: pMode^.dmOrientation := DMORIENT_PORTRAIT;
1: pMode^.dmOrientation := DMORIENT_LANDSCAPE;
end;
GlobalUnlock(hMode);
{Run the Report}
Crpe1.Execute;
end;
StrDispose(lpPort);
StrDispose(lpDriver);
StrDispose(lpPrinter);
end;
The above code can be greatly simplified by using some of the other Printer object methods & properties:
procedure RunReport;
begin
{Set ReportName}
Crpe1.ReportName := 'C:\Company.rpt';
{Preserve Orientation from Report}
Crpe1.Printer.PreserveRptSettings[prOrientation];
{Prompt for Printer at Execute}
Crpe1.Printer.ShowDialog := True;
{Run the Report}
Crpe1.Execute;
end;
VCI Re|etetce 408
Printcr PrcscrvcRptScttings prupcrty
DccIaratiun
property PreserveRptSettings: TCrPreserveRptSettings;
Typc
TCrPreserveRptSettings = set of TCrPreserveRptSet;
TCrPreserveRptSet = (prOrientation, prPaperSize, prPaperSource);
Dcscriptiun
PreserveRptSettings is used to keep certain Printer-related settings (Orientation, Paper Size, Paper Source) as
they were when the Report was designed, even though another Printer is specified which may not have the
same values specified by default. To take full advantage of this property (and the Orientation property)
requires some understanding of the Printer Setup dialog box in the Crystal Reports designer:
Oricntatiun
This section of the Printer Setup dialog box determines whether the Report is Portrait or Landscape. This
setting can be preserved as it is in the Report by adding prOrientation to the PreserveRptSettings set:
Crpe1.Printer.PreserveRptSettings := [prOrientation];
VCI Re|etetce 400
Papcr Sizc
This section of the Printer Setup dialog box determines what the Paper Size of the Report will be. This setting
can be preserved as it is in the Report by adding prPaperSize to the PreserveRptSettings set:
Crpe1.Printer.PreserveRptSettings := [prPaperSize];
Papcr Suurcc
This section of the Printer Setup dialog box determines what the Paper Source on the Printer will be (i.e. which
Paper bin is used). This setting can be preserved as it is in the Report by adding prPaperSource to the
PreserveRptSettings set:
Crpe1.Printer.PreserveRptSettings := [prPaperSource];
Preserving Paper Source may not function correctly yet on Windows NT 4.0 (see the Note below).
DcfauIt Prupcrtics
This checkbox specifies whether the Report will obtain the DevMode properties from the specified Printer, of
whether it will save it's own specific settings. It is important if you plan to control or preserve Orientation,
Paper Size, and Paper Source, that this box is UNchecked. Notice that if any of the Orientation or Paper items
(in the Print Setup dialog box) are changed or edited, Default Properties will automatically be unchecked.
Nu Printcr
This checkbox specifies whether the Report will have any specific Printer information saved with it or not. If
this box is checked, it will be impossible to obtain any Printer specific information from the Report at runtime.
Make sure it is UNchecked, or PreserveRptSettings and Retrieve will not work as expected.
NO7F: 7here s currenlly a small roblem wlh PreserveRlSellngs lor rPaerSource and Wndows N7 4.0.
In N74, lhe dmDelaullSource roerly ol lhe DevMode slruclure cannol be modled. 7he Paer Source (Bn)
can be assocaled wlh a cerlan Page Sze by lhe N7 Admnslralor (n lhe Wndows Conlrol Panel Prnler
Selu). 7herealler, any documenls rnled wlh lhal Page Sze aulomalcally go lo lhe Bn assocaled wlh lhal
sze, regardless ol any olher bn sellng. 7herelore, l aears lhal Paer Source has lo be changed usng olher
Wndows API calls, whch we have nol yel mlemenled n lhe VCI.
fxampIc
The following code example uses the PreserveRptSettings property to preserve the PaperSize as defined in the
Report, regardless of which Printer is chosen (note: this will only work if the Printer chosen supports that Page
Size):
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toPrinter;
with Crpe1.Printer do
begin
{Set Name to 3rd Printer in Printers list}
Name := Printer.Printers[2];
{Set Orientation to Landscape}
VCI Re|etetce S66
Orientation := orLandscape;
{Preserve PaperSize as set in Report}
PreserveRptSettings := [prPaperSize];
{Do not show the PrintDialog on Execute}
ShowDialog := False;
end;
Crpe1.Execute;
Printcr ShuwDiaIug prupcrty
DccIaratiun
property ShowDialog: Boolean;
Dcscriptiun
The ShowDialog property can be used to bring up the Delphi Print dialog, which allows the user to change
Printer property values. This dialog box looks like this:
It is the same as calling the ShowPrintDlg method, except that whereas ShowPrintDlg causes the Print dialog
box to appear as soon as it is called, ShowDialog calls the Print dialog only when the Crystal component's
Execute method is called.
In practical terms, you would use ShowDialog if you always want the user to be prompted for a Printer choice
before the Report runs. If you only want the Print dialog to show optionally, if a button is pressed for example,
then use the ShowPrintDlg method in the button click event.
With ShowDialog set to True, the Print dialog box will appear whenever the Send method is called. The Send
method is automatically called whenever the Execute method for the component is called.
VCI Re|etetce S61
If you want the Print dialog box to appear with a specific printer selected, set the Delphi Printers.PrinterIndex
to the Printer desired, and call the GetCurrent method before calling Execute. When the Print dialog box
appears, it will have that Printer selected by default.
fxampIc
The following code illustrates how to use the ShowDialog property of the Printer object:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toPrinter;
Crpe1.Printer.ShowDialog := True;
{When Execute is called, the Printer dialog will appear}
Crpe1.Execute;
Here is the same example, but in this case, we want the Printer dialog to appear with a certain Printer pre-
selected:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toPrinter;
Crpe1.Printer.ShowDialog := True;
{Set the Delphi Printers list to the 4th Printer}
Printers.PrinterIndex := 3;
{When Execute is called, the Printer dialog will appear}
Crpe1.Execute;
Printcr Mcthuds
Printcr CIcar Mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
The Clear method can be used to set the Printer properties back to their default values:
Name := '';
Port := '';
Driver := '';;
Mode := 0;
PMode := nil;
Orientation := orDefault;
PreserveRptSettings := [];
It is called automatically if the Clear method is called for the main component, but may be called in code as
needed.
VCI Re|etetce S62
fxampIc
This line of code clears the Printer properties:
Crpe1.Printer.Clear;
Printcr CupyFrum Mcthud
DccIaratiun
function CopyFrom(Source: TCrpePrinter): boolean;
Dcscriptiun
The CopyFrom method copies the Printer property values from another TCrpePrinter object. It is similar to
Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the Printer property values to a temporary TCrpePrinter object:
var
tempPrinter : TCrpePrinter;
begin
tempPrinter := TCrpePrinter.Create;
tempPrinter.CopyFrom(Crpe1.Printer);
{...later, when finished with the temp object...}
tempPrinter.Free;
end;
Printcr Crcatc Mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the Printer object, and does not need
to be called in code.
VCI Re|etetce S6!
Printcr GctCurrcnt Mcthud
DccIaratiun
function GetCurrent: boolean;
Dcscriptiun
The GetCurrent method obtains the current Printer information and fills the component's Printer properties
(Name, Driver, Port, Mode and PMode) with values.
G GetCurrent would normally be called after setting the PrinterIndex of the Delphi "Printer.Printers"
array, or after displaying the PrintDialog.
G Returns True if the call succeeded.
fxampIc
The following example illustrates the use of the GetCurrent method to obtain the current Printer information
after setting the Printer.Printers array:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toPrinter;
{Set Printer array to 3rd Printer}
Printer.PrinterIndex := 2;
{Fetch the Printer Info into the VCL}
Crpe1.Printer.GetCurrent;
Crpe1.Execute;
This example shows the use of the GetCurrent method after a PrintDialog is called:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toPrinter;
{Show the PrintDialog}
if PrintDialog1.Execute then
begin
{Fetch the Selected Printer Info into the VCL}
Crpe1.Printer.GetCurrent;
Crpe1.Execute;
end;
VCI Re|etetce S64
Printcr Rctricvc Mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the Printer information from the Report. If the Printer specified in the Report
does not exist on the current computer, the default Printer information will be returned. Returns True if the
call succeeded.
fxampIc
The following example retrieves the Printer settings from a Report, and changes the Orientation setting if
needed:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Destination := toPrinter;
Crpe1.Printer.Retrieve;
if Crpe1.Printer.Orientation <> orPortrait then
Crpe1.Printer.Orientation := orPortrait;
Crpe1.Execute;
Printcr Scnd Mcthud
DccIaratiun
function Send: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The Send method sends the Printer 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 can be called
manually in order to force a display of the Print Dialog if ShowDialog is set to True, but it would be better to
use the ShowPrintDlg method instead. There are three possible return values for Send:
G cFalse- Cancel was chosen on the Print Dialog (ShowDialog is set to True).
G cTrue- The Printer properties were sent to the Print Engine successfully.
VCI Re|etetce S6S
G cDefault- The Printer properties were not sent because the properties had not changed from the Report
settings, or there was an error (an error would normally raise an exception).
NO7F: We slrongly recommend lhal you leave SendOnFxecule lo 7rue, and lel lhe Cryslal Reorls comonenl
send lhe values lo lhe Prnl Fngne. Il you sel lhe SendOnFxecule roerly lo False, each Sub-class and each
roerly lhal does nol belong lo a Sub-class musl be manually senl belore callng lhe Fxecule melhod. 7hs
lealure s manly rovded lor debuggng uroses.
fxampIc
In this example, the Printer settings are sent from the Crystal component to the Crystal Reports Print Engine
DLL. This is normally not necessary since it is handled automatically in the Execute method:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Printer.Name := 'HP Laserjet 4';
Crpe1.Printer.Send;
Crpe1.Execute;
Printcr ShuwPrintDIg Mcthud
DccIaratiun
function ShowPrintDlg: boolean;
Dcscriptiun
The ShowPrintDlg method causes the Printer dialog box to appear so that the user can select the Printer
options directly from the dialog. The dialog box looks like this:
VCI Re|etetce S66
Any options selected on the dialog box will automatically update the components Printer and PrintOptions
properties when the OK button is clicked. If Cancel is chosen, the Crystal component will not be updated.
Another way of doing the same thing is to set the ShowDialog property to True. This will cause the same
dialog box to appear, but it will not appear until the Execute method for the main component is called. If this
method is used, and Cancel is selected from the Dialog, the Report will not be processed (i.e. Execute will be
exited before running the Report to completion).
If you do not want the user to see the PrintOptions part of the dialog, run the Delphi PrintDialog instead, and
use the GetCurrent method after the dialog is closed. If you only want them to change the PrintOptions
properties and not the Printer properties, set the PrintOptions property PromptForOptions to True.
fxampIc
The following code illustrates one way of using the ShowPrintDlg method:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toPrinter;
if Crpe1.Printer.ShowPrintDlg then
Crpe1.Execute;
PrintOptiuns Prupcrtics
PrintOptiuns CuIIatiun prupcrty
DccIaratiun
property Collation: TCrCollation;
Typc
TCrCollation = (Uncollated, Collated, DefaultCollation);
Dcscriptiun
Collation is applicable when printing out more than one copy of a Report. It determines if the pages will be
printed out by Report, or by page.
For example, if printing out two copies of a 3-page Report, setting Collation to Collated will cause all the pages
to be printed out for the first copy, then all the pages for the next copy. Setting Collation to Uncollated will
cause two copies of page 1 to be printed, then two copies of page 2, then two copies of page 3.
The default VCL setting for Collation is DefaultCollation.
NO7F: 7hs roerly only ales l Oulul s loPrnler.
VCI Re|etetce S67
fxampIc
This code example changes the PrintOption properties to print out two copies of pages 2 & 3 from the Report,
collated:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toPrinter;
with Crpe1.PrintOptions do
begin
Collation := Collated;
Copies := 2;
StartPage := 2;
StopPage := 3;
end;
Crpe1.Execute;
PrintOptiuns Cupics prupcrty
DccIaratiun
property Copies: Word;
Dcscriptiun
Copies determines how many copies of a Report will be printed.
The default VCL setting for Copies is 1.
To leave Copies unchanged from the Report setting, set Copies to 0.
NO7F: 7hs roerly only ales l Oulul s loPrnler.
fxampIc
This code example changes the PrintOption properties to print out two copies of pages 2 & 3 from the Report,
collated:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toPrinter;
with Crpe1.PrintOptions do
begin
Collation := Collated;
Copies := 2;
StartPage := 2;
StopPage := 3;
end;
Crpe1.Execute;
VCI Re|etetce S68
PrintOptiuns OutputFiIcNamc prupcrty
NO7F: 7hs roerly requres Seagale Cryslal Reorls 7.0 or hgher.
DccIaratiun
property OutputFileName: TCrPrintFileName;
Typc
TCrPrintFileName = string; {limited to 512 characters}
Dcscriptiun
The OutputFileName property can be used to print a Report to File. It must not exceed 512 characters in length.
fxampIc
This code example changes the PrintOption properties to print to a file:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toPrinter;
Crpe1.PrintOptions.OutputFileName := 'C:\Company.prn';
Crpe1.Execute;
PrintOptiuns PrumptFurOptiuns prupcrty
DccIaratiun
property PromptForOptions: boolean
Dcscriptiun
The PromptForOptions property can be used to bring up a dialog box that will prompt the user for the various
PrintOption property values. This dialog box is the same that appears when the Print button on the Preview
Window is clicked, and looks like this:
VCI Re|etetce S60
The dialog box will appear whenever the Send method is called (provided that PromptForOptions is set to
True). The Send method is automatically called whenever the Execute method for the component is called.
However it may be called manually as well.
This may be desirable in the event that you wish the PrintOptions dialog box to appear with certain default
options other than those stored in the current Report. In such a case, the PrintOptions properties can first be
set to the desired values, then sent into the Report, and then when the dialog later appears, it will be pre-set
to those values. See the Example for code details.
fxampIc
The following code illustrates how to use the PromptForOptions property of the PrintOptions object. The
PrintOptions dialog will appear with the values that are specified in the original Report, which may not be the
same as what are specified in the Crystal component. In order to get the dialog to appear with the current VCL
options, we set the Options in the VCL, and then do a Send. This updates the Report with the new values, and
then when the dialog appears, it has those values as default. Note that normally it is not necessary to call Send
since this is done at Execute
This particular case is an exception:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toPrinter;
{First we turn off the Prompt}
Crpe1.PrintOptions.PromptForOptions := False;
{Set the Options we want}
Crpe1.PrintOptions.Copies := 3;
Crpe1.PrintOptions.Collation := Collated;
Crpe1.PrintOptions.StartPage := 2;
{Send those values into the Report}
Crpe1.PrintOptions.Send;
{Now turn the Prompt on}
Crpe1.PrintOptions.PromptForOptions := True;
{When Execute is called, the PrintOptions dialog will appear}
Crpe1.Execute;
Here is the same example, but in this case, we are not worried about what defaults the PrintOptions dialog
appears with, so there is no need to do a Send:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toPrinter;
Crpe1.PrintOptions.PromptForOptions := True;
{When Execute is called, the PrintOptions dialog will appear}
Crpe1.Execute;
VCI Re|etetce S16
PrintOptiuns StartPagc prupcrty
DccIaratiun
property StartPage: Word;
Dcscriptiun
StartPage determines which page the printing will start with.
The default VCL setting for StartPage is zero (0).
Setting StartPage to zero (0) will cause printing to begin with the first page of the Report.
NO7F: 7hs roerly only ales l Oulul s loPrnler.
fxampIc
This code example changes the PrintOption properties to print out two copies of pages 2 & 3 from the Report,
collated:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toPrinter;
with Crpe1.PrintOptions do
begin
Collation := Collated;
Copies := 2;
StartPage := 2;
StopPage := 3;
end;
Crpe1.Execute;
PrintOptiuns StupPagc prupcrty
DccIaratiun
property StopPage: Word;
Dcscriptiun
StopPage determines which page the printing will stop with.
The default VCL setting for StopPage is zero (0).
Setting StopPage to zero (0), or 65535, will cause printing to go from the StartPage to the last page of the Report.
NO7F: 7hs roerly only ales l Oulul s loPrnler.
VCI Re|etetce S11
fxampIc
This code example changes the PrintOption properties to print out two copies of pages 2 & 3 from the Report,
collated:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toPrinter;
with Crpe1.PrintOptions do
begin
Collation := Collated;
Copies := 2;
StartPage := 2;
StopPage := 3;
end;
Crpe1.Execute;
PrintOptiuns Mcthuds
PrintOptiuns CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
The Clear method can be used to set the PrintOptions properties back to their default values:
Copies := TCRPE_DEFAULT_PRINTERCOPIES; {1}
Collation := DefaultCollation; {No change}
OutputFileName := '';
PromptForOptions := False;
StartPage := TCRPE_DEFAULT_STARTPAGE; {0}
StopPage := TCRPE_DEFAULT_STOPPAGE; {0}
It is called automatically if the Clear method is called for the main component, but may be called in code as
needed.
fxampIc
This line of code clears the PrintOptions properties:
Crpe1.PrintOptions.Clear;
VCI Re|etetce S12
PrintOptiuns CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpePrintOptions): boolean;
Dcscriptiun
The CopyFrom method copies the PrintOptions property values from another TCrpePrintOptions object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the PrintOptions property values to a temporary TCrpePrintOptions object:
var
tempPrintOptions : TCrpePrintOptions;
begin
tempPrintOptions := TCrpePrintOptions.Create;
tempPrintOptions.CopyFrom(Crpe1.PrintOptions);
{...later, when finished with the temp object...}
tempPrintOptions.Free;
end;
PrintOptiuns Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component and does not need to be called in code.
PrintOptiuns Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
VCI Re|etetce S1!
Dcscriptiun
The Retrieve method obtains the PrintOptions information from the Report. Returns True if the call succeeded.
fxampIc
The following example retrieves the PrintOptions settings from a Report, and changes the Collation setting if
needed:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Destination := toPrinter;
Crpe1.PrintOptions.Retrieve;
if Crpe1.PrintOptions.Copies > 1 then
Crpe1.PrintOptions.Collation := Collated;
Crpe1.Execute;
PrintOptiuns Scnd mcthud
DccIaratiun
function Send: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The Send method sends the PrintOptions 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. There are three
possible return values:
cFalse - Cancel was chosen on the PrintOptions dialog (PromptForOptions is set to True).
cTrue - The PrintOptions were sent to the Print Engine successfully.
cDefault - The PrintOptions were not sent because the properties had not changed from the Report
settings, or there was an error (an error would normally raise an exception).
If PromptForOptions is set to True, the Send method can be used to trigger the display of the PrintOptions
dialog before Execute is called, although it is not necessary, since Execute will call the Print Options' Send
method anyway. If you decide to use the Send method before Execute is called, be sure to turn
PromptForOptions off after the dialog box appears, or else it will appear again later when Execute is called.
NO7F: Il s slrongly recommended lhal you leave SendOnFxecule lo 7rue, and lel lhe Cryslal Reorls
comonenl send lhe values lo lhe Prnl Fngne. Il you sel lhe SendOnFxecule roerly lo False, each Sub-class
and each roerly lhal does nol belong lo a Sub-class musl be manually senl belore callng lhe Fxecule
melhod. 7hs lealure s manly rovded lor debuggng uroses.
VCI Re|etetce S14
fxampIc
In this example, the PrintOptions settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toPrinter;
Crpe1.PrintOptions.PromptForOptions := True;
{If Cancel was not chosen on the prompt dialog}
if Crpe1.PrintOptions.Send <> cFalse then
Crpe1.Execute;
Rccurds Mcthuds
Rccurds Printcd mcthud
DccIaratiun
function Printed: LongInt;
Dcscriptiun
The Printed method returns the number of Records that have been printed as the Report is processing. When
going to Preview Window, only the first Page will be initially drawn, so this method will return the number
of Records that have been printed on the first Page only. As the Pages are navigated, the Printed method will
increment to include the new Records that are printed for each Page.
Rccurds Rcad mcthud
DccIaratiun
function Read: LongInt;
Dcscriptiun
The Read method returns the number of Records that have been read as the Report is processing.
VCI Re|etetce S1S
Rccurds ScIcctcd mcthud
DccIaratiun
function Selected: LongInt;
Dcscriptiun
The Selected method returns the number of Records that have been selected as the Report is processing. The
value returned by this method will be dependant on the Selection Formula in the Report. If there is no Record
Selection, Selected will return the same value as Read.
The ProgressDialog can be replaced with a User-Defined dialog by setting ProgressDialog property to False,
and creating a dialog that displays the values of the Records object after the Report has been started (Execute
was called).
RcpurtOptiuns Prupcrtics
RcpurtOptiuns CasclnscnsitivcSQlData prupcrty
DccIaratiun
property CaseInsensitiveSQLData: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The CaseInsensitiveSQLData property specifies whether or not the SQL field names used in the Report will be
treated with case-sensitivity.
fxampIc
This example sets the CaseInsensitiveSQLData property of ReportOptions:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ReportOptions.CaseInsensitiveSQLData := cTrue;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce S16
RcpurtOptiuns CunvcrtDatcTimcTypc prupcrty
DccIaratiun
property ConvertDateTimeType: TCrDateTimeType;
Typc
TCrDateTimeType = (dtConvertToString, dtConvertToDate, dtKeepAsDateTime,
dtDefault);
Dcscriptiun
The ConvertDateTimeType property specifies how DateTime fields will be treated in a Report: as DateTime
values, as DateTime String values, or just as Date (no Time).
fxampIc
This example sets the ConvertDateTimeType property of ReportOptions:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ReportOptions.ConvertDateTimeType := dtConvertToString;
Crpe1.Output := toWindow;
Crpe1.Execute;
RcpurtOptiuns CunvcrtNuIIFicIdTuDcfauIt prupcrty
DccIaratiun
property ConvertNullFieldToDefault: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The ConvertNullFieldToDefault property specifies how Null field values will be treated in a Report: as they
are (null), or as a default value (empty string for string fields, zero for numeric fields, etc.). If Null fields are
not converted to default, extra care must be taken in Formulas and Selection Formulas to test for Null values,
otherwise a null value can cause a formula to stop processing as soon as the null is encountered.
VCI Re|etetce S17
fxampIc
This example sets the ConvertNullFieldToDefault property of ReportOptions:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ReportOptions.ConvertNullFieldToDefault := cTrue;
Crpe1.Output := toWindow;
Crpe1.Execute;
RcpurtOptiuns CrcatcGruupTrcc prupcrty
DccIaratiun
property CreateGroupTree: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The CreateGroupTree property determines if the GroupTree panel on the Preview Window will be available
or not.
This setting should be used in conjunction with the WindowButtonBar.GroupTree property: if
CreateGroupTree is cFalse, the WindowButtonBar.GroupTree will have no effect; if CreateGroupTree is cTrue,
then WindowButtonBar.GroupTree can be used to control whether the GroupTree will appear or not.
fxampIc
This example sets the CreateGroupTree property of ReportOptions:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ReportOptions.CreateGroupTree := cTrue;
Crpe1.WindowButtonBar.GroupTree := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
RcpurtOptiuns NuDataFurHiddcnObjccts prupcrty
DccIaratiun
property NoDataForHiddenObjects: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
VCI Re|etetce S18
Dcscriptiun
The NoDataForHiddenObjects property determines whether data will be saved for parts of the Report that are
in hidden sections.
This will mainly be of concern if a Report is being exported to Crystal Reports format, in which case it will
have Saved Data. This saved-data Report can be run from an application without having access to the original
database, since all the data required to show the Report is saved with it.
When this exported Report is run later, it is possible to provide drill-down capability
(WindowButtonBar.AllowDrillDown). If that is done, it will be necessary for the Report to have saved data for
the hidden sections, so that the drill down will not cause the Report to attempt to read the database. So, before
exporting the Report, make sure NoDataForHiddenObjects is set to cFalse.
On the other hand, if drill-down will not be offered, make sure NoDataForHiddenObjects is set to cTrue, so
that the resulting exported RPT's file size will be smaller.
fxampIc
This example sets the NoDataForHiddenObjects property of ReportOptions so that an exported RPT will have
Saved Data for all objects in all sections of the Report, even the hidden ones:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ReportOptions.NoDataForHiddenObjects := cFalse;
{This next one is just a formality: all exported RPT have Saved Data}
Crpe1.ReportOptions.SaveDataWithReport := cTrue;
{Save Summaries also: optional}
Crpe1.ReportOptions.SaveSummariesWithReport := cTrue;
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := CrystalReportRPT;
Crpe1.Export.FileName := 'C:\SavedData.rpt';
Crpe1.Execute;
RcpurtOptiuns PcrfurmGruupingOnScrvcr prupcrty
DccIaratiun
property PerformGroupingOnServer: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The PerformGroupingOnServer property specifies whether the grouping of data for a Report will take place
on the Server or not. This option only applies to Reports based off an SQL or ODBC datasource.
VCI Re|etetce S10
fxampIc
This example sets the PerformGroupingOnServer property of ReportOptions:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ReportOptions.PerformGroupingOnServer := cTrue;
Crpe1.Output := toWindow;
Crpe1.Execute;
RcpurtOptiuns PrintfngincfrrurMcssagcs prupcrty
DccIaratiun
property PrintEngineErrorMessages: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The PrintEngineErrorMessages property determines if the Print Engine will put up it's own error dialogs, on
top of the VCL's error handling. The built-in Print Engine error messages are often more descriptive than the
standard error messages returned by the Print Engine to an application. It may be desirable to turn this option
on when doing development, but it normally should be turned off when the application is finally deployed.
fxampIc
This example sets the PrintEngineErrorMessages property of ReportOptions:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ReportOptions.PrintEngineErrorMessages := cTrue;
Crpe1.Output := toWindow;
Crpe1.Execute;
RcpurtOptiuns SavcDataWithRcpurt prupcrty
DccIaratiun
property SaveDataWithReport: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
VCI Re|etetce S26
Dcscriptiun
The SaveDataWithReport property determines if a Report will save the actual data used from the database
with the Report when the Report is saved. Since saving is not possible at runtime, this property is not
particularly useful at this time. It is possible to export a Report to RPT format, but the exported RPT will have
Saved Data by default anyway.
fxampIc
This example sets the SaveDataWithReport property of ReportOptions:
Crpe1.ReportName := 'C:\Company.rpt';
{Save Data for Subreports, etc. in hidden sections}
Crpe1.ReportOptions.NoDataForHiddenObjects := cFalse;
{This next one is just a formality: all exported RPT have Saved Data}
Crpe1.ReportOptions.SaveDataWithReport := cTrue;
{Save Summaries also: optional}
Crpe1.ReportOptions.SaveSummariesWithReport := cTrue;
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := CrystalReportRPT;
Crpe1.Export.FileName := 'C:\SavedData.rpt';
Crpe1.Execute;
RcpurtOptiuns SavcSummaricsWithRcpurt prupcrty
DccIaratiun
property SaveSummariesWithReport: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The SaveSummariesWithReport property determines if the data calculated from summary fields in the Report
is stored in the RPT file when the Report is saved. Since saving is not directly possible at runtime, this property
is only useful when a Report is exported to RPT format.
VCI Re|etetce S21
fxampIc
This example sets the SaveSummariesWithReport property of ReportOptions:
Crpe1.ReportName := 'C:\Company.rpt';
{Save Data for Subreports, etc. in hidden sections}
Crpe1.ReportOptions.NoDataForHiddenObjects := cFalse;
{This next one is just a formality: all exported RPT have Saved Data}
Crpe1.ReportOptions.SaveDataWithReport := cTrue;
{Save Data calculated in Summaries}
Crpe1.ReportOptions.SaveSummariesWithReport := cTrue;
Crpe1.Output := toExport;
Crpe1.Export.Destination := toFile;
Crpe1.Export.FileType := CrystalReportRPT;
Crpe1.Export.FileName := 'C:\SavedData.rpt';
Crpe1.Execute;
RcpurtOptiuns TransIatcDOSMcmus prupcrty
DccIaratiun
property TranslateDOSMemos: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The TranslateDOSMemos property determines how dBase memo fields with upper ASCII characters are
handled, whether they are translated to corresponding ANSI character values, or not.
fxampIc
This example sets the TranslateDOSMemos property of ReportOptions:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ReportOptions.TranslateDOSMemos := cTrue;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce S22
RcpurtOptiuns TransIatcDOSStrings prupcrty
DccIaratiun
property TranslateDOSStrings: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The TranslateDOSStrings property determines how dBase string fields with upper ASCII characters are
handled, whether they are translated to corresponding ANSI character values, or not.
fxampIc
This example sets the TranslateDOSStrings property of ReportOptions:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ReportOptions.TranslateDOSStrings := cTrue;
Crpe1.Output := toWindow;
Crpe1.Execute;
RcpurtOptiuns UsclndcxFurSpccd prupcrty
DccIaratiun
property UseIndexForSpeed: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The UseIndexForSpeed property specifies if an index or a SQL Server will be used to speed up processing of
a Record Selection. Usually it is desirable to leave this option on, but it can cause problems with dBase indexes
that use expressions or functions (which are not supported by Crystal's xBase driver).
VCI Re|etetce S2!
fxampIc
This example turns off the UseIndexForSpeed property of ReportOptions:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ReportOptions.UseIndexForSpeed := cFalse;
Crpe1.Output := toWindow;
Crpe1.Execute;
RcpurtOptiuns VcrifyOnfvcryPrint prupcrty
DccIaratiun
property VerifyOnEveryPrint: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The VerifyOnEveryPrint property determines whether the database structure will be re-read every time the
Report runs. It is useful to have this option turned on during development, where database field-types or
lengths may change frequently. If the database structure is fixed, and will not change, this option can be turned
off for slightly faster processing of the Report.
NO7F: For PC-lye dalabases: l may be uselul lo lurn lhs roerly on, or use lhe VerlyDalabase melhod,
when onlng a Reorl lhal uses lnked lables, lo new lables wlh dllerenl names, so lhal lhe lnkng and
ndex nlormalon gels udaled correclly.
fxampIc
This example sets the VerifyOnEveryPrint property of ReportOptions:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ReportOptions.VerifyOnEveryPrint := cTrue;
Crpe1.Output := toWindow;
Crpe1.Execute;
RcpurtOptiuns ZuumMudc prupcrty
DccIaratiun
property ZoomMode: TCrZoomPreview;
VCI Re|etetce S24
Typc
TCrZoomPreview = (pwNormal, pwPageWidth, pwWholePage, pwDefault);
Dcscriptiun
The ZoomMode property controls the zoom level of the Crystal Preview Window when it first appears on
screen.
fxampIc
This example sets the ZoomMode property of ReportOptions:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ReportOptions.ZoomMode := pwWholePage;
Crpe1.WindowState := wsMaximized;
Crpe1.Output := toWindow;
Crpe1.Execute;
RcpurtOptiuns Mcthuds
RcpurtOptiuns CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
The Clear method can be used to set the ReportOptions properties back to their default values:
CaseInsensitiveSQLData := cDefault;
ConvertDateTimeTyp := dtDefault;
ConvertNullFieldToDefault := cDefault;
CreateGroupTree := cDefault;
NoDataForHiddenObjects := cDefault;
pwNormal Equivalent to 100% magnification.
pwPageWidth The Report will be sized to fit the width of the Preview Window.
pwWholePage The Report will be sized to fit the width and height of the Preview Window.
pwDefault The ZoomMode property is ignored. The zoom level will be determined by the
level the Report was saved with, or the setting of the WindowZoom.Preview or
WindowZoom.Magnification properties.
VCI Re|etetce S2S
PerformGroupingOnServer := cDefault;
PrintEngineErrorMessages : = cDefault;
SaveDataWithReport := cDefault;
SaveSummariesWithReport := cDefault;
TranslateDOSMemos := cDefault;
TranslateDOSStrings := cDefault;
UseIndexForSpeed := cDefault;
VerifyOnEveryPrint := cDefault;
ZoomMode := pwDefault;
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 needed.
fxampIc
This line of code clears the ReportOptions properties:
Crpe1.ReportOptions.Clear;
RcpurtOptiuns CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeReportOptions): boolean;
Dcscriptiun
The CopyFrom method copies the ReportOptions property values from another TCrpeReportOptions object.
It is similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the ReportOptions property values to a temporary TCrpeReportOptions
object:
var
tempReportOptions : TCrpeReportOptions;
begin
tempReportOptions := TCrpeReportOptions.Create;
tempReportOptions.CopyFrom(Crpe1.ReportOptions);
{...later, when finished with the temp object...}
tempReportOptions.Free;
end;
VCI Re|etetce S26
RcpurtOptiuns Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the ReportOptions object, and does
not need to be called in code, unless you are using the CopyFrom method to store ReportOptions data to a
temporary object:
var
tempReportOptions : TCrpeReportOptions;
begin
tempReportOptions := TCrpeReportOptions.Create;
tempReportOptions.CopyFrom(Crpe1.ReportOptions);
end;
RcpurtOptiuns Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the ReportOptions information from the Report and stores it in the
ReportOptions object. If ReportOptions information was not found, the call returns False.
fxampIc
The following code illustrates the use of the Retrieve method. ReportOptions belong to the main Report,
therefore it is not necessary to retrieve them from Subreports also:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.ReportOptions.Retrieve;
VCI Re|etetce S27
RcpurtOptiuns Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the ReportOptions 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.
We strongly recommend 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.
fxampIc
In this example, the ReportOptions settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.ReportOptions.Send;
ScctiunFunt Prupcrtics
ScctiunFunt CharSct prupcrty
DccIaratiun
property CharSet: TCrFontCharSet;
Typc
TCrFontCharSet = (fcAnsi, fcDefault, fcSymbol, fcShiftJis, fcHangeul,
fcChineseBig5, fcOEM);
Dcscriptiun
CharSet determines the Character Set that is used for the Font in the specified Section. Use fcDefault for no
change.
VCI Re|etetce S28
fxampIc
The code below retrieves the SectionFont settings from the Report, then loops through looking for the Details
"a" section, and sets the Font Name, Size, and CharSet for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFont.Retrieve;
for cnt := 0 to (Crpe1.SectionFont.Count - 1) do
begin
{Look for Details area}
if Crpe1.SectionFont[cnt].Section = 'Da' then
begin
Crpe1.SectionFont[cnt].Name := 'Times New Roman';
Crpe1.SectionFont[cnt].Size := 10;
Crpe1.SectionFont[cnt].CharSet := fcDefault;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFunt FamiIy prupcrty
DccIaratiun
property Family: TCrFontFamily;
Typc
TCrFontFamily = (ffDefault, ffRoman, ffSwiss, ffModern, ffScript,
ffDecorative);
Dcscriptiun
The Family property specifies the Font Family that is used for the Font in the specified Section. Use ffDefault
for no change.
VCI Re|etetce S20
fxampIc
The code below retrieves the SectionFont settings from the Report, then loops through looking for the Details
"a" section, and sets the Font Name, Size, and Family for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFont.Retrieve;
for cnt := 0 to (Crpe1.SectionFont.Count - 1) do
begin
{Look for Details area}
if Crpe1.SectionFont[cnt].Section = 'Da' then
begin
Crpe1.SectionFont[cnt].Name := 'Times New Roman';
Crpe1.SectionFont[cnt].Size := 10;
Crpe1.SectionFont[cnt].Family := ffDefault;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFunt ltaIic prupcrty
DccIaratiun
property Italic: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The Italic property determines whether the Font should be italicized. Use cDefault for no change.
VCI Re|etetce S!6
fxampIc
The code below retrieves the SectionFont settings from the Report, then loops through looking for the Details
"a" section, and sets the Font Name, Size, and Italic properties for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFont.Retrieve;
for cnt := 0 to (Crpe1.SectionFont.Count - 1) do
begin
{Look for Details area}
if Crpe1.SectionFont[cnt].Section = 'Da' then
begin
Crpe1.SectionFont[cnt].Name := 'Times New Roman';
Crpe1.SectionFont[cnt].Size := 10;
Crpe1.SectionFont[cnt].Italic := cTrue;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFunt ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeSectionFont;
Dcscriptiun
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 various items stored in the SectionFont object, allowing the
object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript: SectionFont[2] is
the same as SectionFont.Item[2].
G Item returns a reference to itself, so the SectionFont properties can be used right after the subscript:
SectionFont[2].Name := 'Times New Roman';
VCI Re|etetce S!1
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.SectionFont.Retrieve;
{Set SectionFont object to the 3rd section}
Crpe1.SectionFont.Item[2];
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.SectionFont.Retrieve;
{Set SectionFont object to the 3rd section}
Crpe1.SectionFont[2];
ScctiunFunt ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current SectionFont item number, or
set the SectionFont 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 (SectionFont[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the SectionFont object is pointing
to the first SectionFont item:
if Crpe1.SectionFont.ItemIndex <> 0 then
Crpe1.SectionFont[0];
ScctiunFunt Namc prupcrty
DccIaratiun
property Name: TFontName;
VCI Re|etetce S!2
Dcscriptiun
Name specifies the Font Name to be used for the specified Section. The property uses Delphi's TFontName
type, which makes a list of installed fonts available on the Object Inspector (or if the property is double-clicked,
the Font Dialog will appear).
fxampIc
The code below retrieves the SectionFont settings from the Report, then loops through looking for the Details
"a" section, and sets the Font Name and Size for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFont.Retrieve;
for cnt := 0 to (Crpe1.SectionFont.Count - 1) do
begin
{Look for Details area}
if Crpe1.SectionFont[cnt].Section = 'Da' then
begin
Crpe1.SectionFont[cnt].Name := 'Times New Roman';
Crpe1.SectionFont[cnt].Size := 10;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFunt Pitch prupcrty
DccIaratiun
property Pitch: TFontPitch;
Typc
TFontPitch = (fpDefault, fpVariable, fpFixed);
Dcscriptiun
Pitch determines whether the Font character spacing will be Fixed or Variable.
G With Fixed Pitch, each character occupies the same width, as on a typewriter.
G With Variable Pitch, characters only occupy as much space as is required, so an "i" takes up less space
than a "w".
G Fixed Pitch is commonly used with numbers, so that the columns line up properly.
VCI Re|etetce S!!
fxampIc
The code below retrieves the SectionFont settings from the Report, then loops through looking for the Details
"a" section, and sets the Font Name, Size and Pitch for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFont.Retrieve;
for cnt := 0 to (Crpe1.SectionFont.Count - 1) do
begin
{Look for Details area}
if Crpe1.SectionFont[cnt].Section = 'Da' then
begin
Crpe1.SectionFont[cnt].Name := 'Times New Roman';
Crpe1.SectionFont[cnt].Size := 10;
Crpe1.SectionFont[cnt].Pitch := fpVariable;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFunt Scupc prupcrty
DccIaratiun
property Scope: TCrFontScope;
Typc
TCrFontScope = (Fields, Text, Both);
Dcscriptiun
The Scope property determines what type of Fields the Font changes will apply to: Database Fields, Text
Fields, or both.
VCI Re|etetce S!4
fxampIc
The code below retrieves the SectionFont settings from the Report, then loops through looking for the Details
"a" section, and sets the Font Name, Size, and Scope for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFont.Retrieve;
for cnt := 0 to (Crpe1.SectionFont.Count - 1) do
begin
{Look for Details area}
if Crpe1.SectionFont[cnt].Section = 'Da' then
begin
Crpe1.SectionFont[cnt].Name := 'Times New Roman';
Crpe1.SectionFont[cnt].Size := 10;
Crpe1.SectionFont[cnt].Scope := Both;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFunt Scctiun prupcrty
DccIaratiun
property Section: TCrSectionFontSection;
Typc
TCrSectionFontSection = string;
Dcscriptiun
The Section property contains the Section name of the item that the SectionFont object is currently pointed to.
It's primary use is as a look-up property to point the SectionFont object to the item with the Section specified.
The default array property, Item, however, provides an easier way to navigate through the object.
If the Retrieve method is used, the Section name of each SectionFont item is automatically filled when the
SectionFont information is retrieved.
VCI Re|etetce S!S
The Section name syntax is the same as the Short Section Names used in the Crystal Reports Designer as listed
in the following table. In addition, lower-case letters: a, b, c, etc. are used to specify sub-sections and numbers are
used to designate different Groups: GH1, GF2, etc. See About Section Names, Volume 1, Chapter 7, for more details
on the syntax.
fxampIc
The code below retrieves the SectionFont settings from the Report, then loops through looking for the Details
"a" section, and sets various options for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFont.Retrieve;
for cnt := 0 to (Crpe1.SectionFont.Count - 1) do
begin
{Look for Details area}
if Crpe1.SectionFont[cnt].Section = 'Da' then
begin
Crpe1.SectionFont[cnt].Name := 'Times New Roman';
Crpe1.SectionFont[cnt].Size := 10;
Crpe1.SectionFont[cnt].Scope := Both;
Crpe1.SectionFont[cnt].Italic := cTrue;
Crpe1.SectionFont[cnt].Weight := fwBold;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFunt ScctiunAsCudc prupcrty
DccIaratiun
property SectionAsCode: smallint;
RH Report Header
PH Page Header
GH Group Header
D Details
GF Group Footer
PF Page Footer
RF Report Footer
VCI Re|etetce S!6
Dcscriptiun
The SectionAsCode property can be used to read and write the Section property via Print Engine Section Code
numbers. Since the Print Engine Section Codes are numeric, it is easier to apply conditional formatting to
certain sections (in a For loop for example) based on mathematical calculations on the Section Code number
than it is by parsing out the regular Section Code string (GH1b, etc.).
See also: About Section Names, Volume 1, Chapter 7.
fxampIc
The SectionAsCode property can be used to apply formatting to specific sections based on mathematical
calculations or comparisons. The following code checks each section to see if it is a "b" section, such as RHb,
PHb, Db, etc., and if it is, the Font Size is changed to 10 point:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFont.Retrieve;
for cnt := 0 to (Crpe1.SectionFont.Count - 1) do
begin
if (Crpe1.SectionFont[cnt].SectionAsCode mod 1000 = 25) then
Crpe1.SectionFont[cnt].Size := 10;
end;
Crpe1.Execute;
The logic behind the math expression is based on the fact that each sub-section increments the Section Code
number by 25 (from 0 to 975 are the possible numbers). So, since 3000 is the general Section Code start number
for a Group Header, and is therefore the number to represent GroupHeader 1a, 3025 represents GroupHeader
1b, 3050 represents GroupHeader 1c, etc. Therefore, in order to find the "b" sections we must divide by 1000,
and if the remainder is 25, it is a "b" section. This also works for all the other sections that do not have Group
options, such as Details, ReportHeader, etc. since dividing by 25 will also return no remainder if the Section
Code number is evenly divisible by 1000.
ScctiunFunt Sizc prupcrty
DccIaratiun
property Size: smallint;
Dcscriptiun
The Size property determines how large or small the Font will be. The scale is in points.
VCI Re|etetce S!7
fxampIc
The code below retrieves the SectionFont settings from the Report, then loops through looking for the Details
"a" section, and sets the Font Name and Size for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFont.Retrieve;
for cnt := 0 to (Crpe1.SectionFont.Count - 1) do
begin
{Look for Details area}
if Crpe1.SectionFont[cnt].Section = 'Da' then
begin
Crpe1.SectionFont[cnt].Name := 'Times New Roman';
Crpe1.SectionFont[cnt].Size := 10;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFunt StrikcThruugh prupcrty
DccIaratiun
property StrikeThrough: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The StrikeThrough property determines whether the Font should have strike through lines in it. Use cDefault
for no change.
VCI Re|etetce S!8
fxampIc
The code below retrieves the SectionFont settings from the Report, then loops through looking for the Details
"a" section, and sets the Font Name, Size, and StrikeThrough properties for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFont.Retrieve;
for cnt := 0 to (Crpe1.SectionFont.Count - 1) do
begin
{Look for Details area}
if Crpe1.SectionFont[cnt].Section = 'Da' then
begin
Crpe1.SectionFont[cnt].Name := 'Times New Roman';
Crpe1.SectionFont[cnt].Size := 10;
Crpe1.SectionFont[cnt].StrikeThrough := cTrue;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFunt UndcrIincd prupcrty
DccIaratiun
property Underlined: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
The Underlined property determines whether the Font should be underlined. Use cDefault for no change.
fxampIc
The code below retrieves the SectionFont settings from the Report, then loops through looking for the Details
"a" section, and sets the Font Name, Size, and Underlined properties for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
VCI Re|etetce S!0
Crpe1.SectionFont.Retrieve;
for cnt := 0 to (Crpe1.SectionFont.Count - 1) do
begin
{Look for Details area}
if Crpe1.SectionFont[cnt].Section = 'Da' then
begin
Crpe1.SectionFont[cnt].Name := 'Times New Roman';
Crpe1.SectionFont[cnt].Size := 10;
Crpe1.SectionFont[cnt].Underlined := cTrue;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFunt Wcight prupcrty
DccIaratiun
property Weight: TCrFontWeight;
Typc
TCrFontWeight = (fwDefault, fwThin, fwExtraLight, fwLight, fwNormal,
fwMedium, fwSemiBold, fwBold, fwExtraBold, fwHeavy);
Dcscriptiun
The Weight property determines how heavy (thick) or light (thin) the Font will appear. Use fwDefault for no
change.
fxampIc
The code below retrieves the SectionFont settings from the Report, then loops through looking for the Details
"a" section, and sets the Font Name, Size, and Weight properties for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFont.Retrieve;
for cnt := 0 to (Crpe1.SectionFont.Count - 1) do
begin
{Look for Details area}
if Crpe1.SectionFont[cnt].Section = 'Da' then
VCI Re|etetce S46
begin
Crpe1.SectionFont[cnt].Name := 'Times New Roman';
Crpe1.SectionFont[cnt].Size := 10;
Crpe1.SectionFont[cnt].Weight := fwBold;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFunt Mcthuds
ScctiunFunt Add mcthud
DccIaratiun
procedure Add(SectionName: TCrSectionFontSection);
Typc
TCrSectionFontSection = string;
Dcscriptiun
The Add method adds an item to the SectionFont object and sets the internal index to that item. It requires a
Section name as a parameter, which should be a name corresponding to a Section in the Report. Sections are
named using the Short Section Name convention used in Crystal Reports (see About Section Names, Volume 1,
Chapter 7 for more information). If the Add method is used, the steps to using SectionFont are:
1 Add an item to the SectionFont object (you must specify the Section name).
2 Fill the item's properties (Name, Size, etc.) with values.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
Seclon names are correcl lor lhe currenl Reorl.
fxampIc
The Add method can be used to manually add an item to the SectionFont object, instead of using Retrieve:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Section Name - must be same as in Report}
Crpe1.SectionFont.Add('Da');
Crpe1.SectionFont.Name := 'Times New Roman';
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce S41
ScctiunFunt CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the SectionFont 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 is only applied to the SectionFont object of the current Report/Subreport specified in the Subreports
object. Therefore, to clear all the SectionFont of all the Subreports will require a looping procedure that goes
through each Subreport and applies the Clear.
fxampIc
This code clears the SectionFont properties for the main Report (assuming the default state of Subreports[0]):
Crpe1.SectionFont.Clear;
This code clears the SectionFont properties for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SectionFont.Clear;
end;
ScctiunFunt CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeSectionFont): boolean;
Dcscriptiun
The CopyFrom method copies the SectionFont property values from another TCrpeSectionFont object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
VCI Re|etetce S42
fxampIc
The following example copies all the SectionFont property values to a temporary TCrpeSectionFont object:
var
tempSectionFont : TCrpeSectionFont;
begin
tempSectionFont := TCrpeSectionFont.Create;
tempSectionFont.CopyFrom(Crpe1.SectionFont);
{...later, when finished with the temp object...}
tempSectionFont.Free;
end;
ScctiunFunt Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the SectionFont object. It is handy
for setting up loops to make similar changes to each item.
fxampIc
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.SectionFont.Retrieve;
for cnt := 0 to (Crpe1.SectionFont.Count - 1) do
Crpe1.SectionFont[cnt].Name := 'Times New Roman';
end;
ScctiunFunt Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the SectionFont object, and does not
need to be called in code.
VCI Re|etetce S4!
ScctiunFunt DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the SectionFont object. The "nIndex" parameter
represents the number of the item in the SectionFont object.
fxampIc
The Delete method can be used to manually remove an item from the SectionFont object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Section Name - must be same as in Report}
Crpe1.SectionFont.Add('Da');
Crpe1.SectionFont.Name := 'Times New Roman';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.SectionFont.Delete(0);
ScctiunFunt Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
ScctiunFunt Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
VCI Re|etetce S44
Dcscriptiun
The Retrieve method obtains the SectionFont information from the Report and stores it in the SectionFont
object. If no SectionFont information was found, the call returns False. Be aware that calling Retrieve will first
cause the SectionFont object to be cleared, so any current information stored in it will be removed.
NO7F: 7here s currenlly no way lo oblan Fonl nlormalon lrom lhe Prnl Fngne al runlme so Relreve
smly adds an lem lo lhe SeclonFonl objecl lor each Reorl Seclon l lnds, oblans lhe currenl Seclon
Code lor lhe Seclon roerly, and sels lhe olher roerles lo delaull values.
NO7F: Snce lhe SeclonFonl objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe
SeclonFonl lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl
lo oblan lhe SeclonFonl nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle
lhrough lhe Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale SeclonFonl
nlormalon lor each Subreorl (see Fxamle).
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFont.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SectionFont.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
ScctiunFunt ScctiunTypc mcthud
DccIaratiun
function SectionType: string;
VCI Re|etetce S4S
Dcscriptiun
The SectionType method returns the Section Code without the subsection specifier. In other words, if the
Section Code for an item is GH1ac, the SectionType method would return GH; if the SectionCode is Da, the
SectionType method would return D.
The primary use for this method is to apply changes to all the Sections in an area, regardless of the sub-section
specifier.
fxampIc
The following example uses the SectionType method to apply conditional formatting. In this case, we want to
change the Font style for the Group Header sections only:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFont.Retrieve;
for cnt := 0 to (Crpe1.SectionFont.Count - 1) do
begin
{if the SectionType is Group Header, apply the change}
if (Crpe1.SectionFont[cnt].SectionType = 'GH') then
Crpe1.SectionFont[cnt].Name := 'Times New Roman';
end;
end;
ScctiunFunt Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the SectionFont 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.
fxampIc
In this example, the SectionFont settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.SectionFont.Send;
VCI Re|etetce S46
ScctiunFurmat Prupcrtics
ScctiunFurmat BackgruundCuIur prupcrty
DccIaratiun
property BackgroundColor: TColor;
Dcscriptiun
BackgroundColor specifies the color that will fill the background of a specified section on the Report. The
value can be any of the Delphi color constants, the Color value returned from Delphi's Color Dialog, or the
following constants:
fxampIc
The code below retrieves the SectionFormat settings from the Report, then loops through looking for the
Details "a" section, and sets the BackgroundColor for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormat.Retrieve;
for cnt := 0 to (Crpe1.SectionFormat.Count - 1) do
begin
{Look for Details "a" section}
if Crpe1.SectionFormat[cnt].Section = 'Da' then
Crpe1.SectionFormat[cnt].BackgroundColor := clRed;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFurmat FrccFurmPIaccmcnt prupcrty
DccIaratiun
property FreeFormPlacement: TCrBoolean;
clUnchangedColor -2
clNoColor $FFFFFFFF
VCI Re|etetce S47
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
FreeFormPlacement determines if objects in a specified Section can be placed anywhere, or whether they snap
to the page grid.
fxampIc
The code below retrieves the SectionFormat settings from the Report, then loops through looking for the
Details "a" section, and sets FreeFormPlacement for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormat.Retrieve;
for cnt := 0 to (Crpe1.SectionFormat.Count - 1) do
begin
{Look for Details "a" section}
if Crpe1.SectionFormat[cnt].Section = 'Da' then
Crpe1.SectionFormat[cnt].FreeFormPlacement := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFurmat Hidc prupcrty
DccIaratiun
property Hide: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
Hide determines if the specified Area will show or not. A hidden section is still available for drill-down in the
Preview Window (provided that the drill-down options are turned on in the WindowButtonBar object). To
suppress an Area so that it is not available for drill-down, use the Suppress property.
VCI Re|etetce S48
fxampIc
The code below retrieves the AreaFormat settings from the Report, then loops through looking for the Details
area, and sets the Hide option for that area:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormat.Retrieve;
for cnt := 0 to (Crpe1.AreaFormat.Count - 1) do
begin
{Look for Details area}
if Crpe1.AreaFormat[cnt].Section = 'D' then
Crpe1.AreaFormat[cnt].Hide := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFurmat ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeSectionFormat;
Dcscriptiun
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 various items stored in the SectionFormat object, allowing the
object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript:
SectionFormat[2] is the same as SectionFormat.Item[2].
G Item returns a reference to itself, so the SectionFormat properties can be used right after the subscript:
SectionFormat[2].BackgroundColor := clRed;
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.SectionFormat.Retrieve;
{Set SectionFormat to the 3rd section}
Crpe1.SectionFormat.Item[2];
VCI Re|etetce S40
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.SectionFormat.Retrieve;
{Set SectionFormat to the 3rd section}
Crpe1.SectionFormat[2];
ScctiunFurmat ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current SectionFormat item number,
or set the SectionFormat 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 (SectionFormat[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the SectionFormat object is
pointing to the first SectionFormat item:
if Crpe1.SectionFormat.ItemIndex <> 0 then
Crpe1.SectionFormat[0];
ScctiunFurmat kccpTugcthcr prupcrty
DccIaratiun
property KeepTogether: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
VCI Re|etetce SS6
Dcscriptiun
KeepTogether determines whether a Section which is printing fields from the same Record will be split on a
Page Break or not. For example, if a Details section has fields placed on 4 horizontal lines, setting
KeepTogether to cTrue will ensure that those fields will not be split when a Page Break occurs, by moving
them all to the new page.
NO7F: 7he SeclonFormal Kee7ogelher roerly s nol lhe same as Cryslal Reorls KeeGrou7ogelher
olon, whch kees a Grou lrom slllng on a Page Break, and whch s avalable va lhe Kee7ogelher
roerly ol lhe GrouOlons objecl.
fxampIc
The code below retrieves the SectionFormat settings from the Report, then loops through looking for the
Details "a" section, and sets the KeepTogether option for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormat.Retrieve;
for cnt := 0 to (Crpe1.SectionFormat.Count - 1) do
begin
{Look for Details "a" section}
if Crpe1.SectionFormat[cnt].Section = 'Da' then
Crpe1.SectionFormat[cnt].KeepTogether := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFurmat NcwPagcAftcr prupcrty
DccIaratiun
property NewPageAfter: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
NewPageAfter determines if a Page Break will occur after the specified Section.
VCI Re|etetce SS1
fxampIc
The code below retrieves the SectionFormat settings from the Report, then loops through looking for the
Details "a" section, and sets the NewPageAfter option for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormat.Retrieve;
for cnt := 0 to (Crpe1.SectionFormat.Count - 1) do
begin
{Look for Details "a" section}
if Crpe1.SectionFormat[cnt].Section = 'Da' then
Crpe1.SectionFormat[cnt].NewPageAfter := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFurmat NcwPagcBcfurc prupcrty
DccIaratiun
property NewPageBefore: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
NewPageBefore determines if a Page Break will occur before the specified Section.
fxampIc
The code below retrieves the SectionFormat settings from the Report, then loops through looking for the
Details "a" section, and sets the NewPageBefore option for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormat.Retrieve;
VCI Re|etetce SS2
for cnt := 0 to (Crpe1.SectionFormat.Count - 1) do
begin
{Look for Details "a" section}
if Crpe1.SectionFormat[cnt].Section = 'Da' then
Crpe1.SectionFormat[cnt].NewPageBefore := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFurmat PrintAtButtumOfPagc prupcrty
DccIaratiun
property PrintAtBottomOfPage: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
PrintAtBottomOfPage determines if the specified Section will appear at the bottom of the page when the
Report is run.
fxampIc
The code below retrieves the SectionFormat settings from the Report, then loops through looking for the
Details "a" section, and sets the PrintAtBottomOfPage option for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormat.Retrieve;
for cnt := 0 to (Crpe1.SectionFormat.Count - 1) do
begin
{Look for Details "a" section}
if Crpe1.SectionFormat[cnt].Section = 'Da' then
Crpe1.SectionFormat[cnt].PrintAtBottomOfPage := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
VCI Re|etetce SS!
ScctiunFurmat RcsctPagcNAftcr prupcrty
DccIaratiun
property ResetPageNAfter: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
ResetPageNAfter determines if the Page Number will be reset back to 1 after the specified Section.
fxampIc
The code below retrieves the SectionFormat settings from the Report, then loops through looking for the
Details "a" section, and sets the ResetPageNAfter option for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormat.Retrieve;
for cnt := 0 to (Crpe1.SectionFormat.Count - 1) do
begin
{Look for Details "a" section}
if Crpe1.SectionFormat[cnt].Section = 'Da' then
Crpe1.SectionFormat[cnt].ResetPageNAfter := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFurmat Scctiun prupcrty
DccIaratiun
property Section: TCrSectionFormatSection;
Typc
TCrSectionFormatSection = string;
VCI Re|etetce SS4
Dcscriptiun
The Section property contains the Section name of the item that the SectionFormat object is currently pointed
to. Its primary use is as a look-up property to point the SectionFormat object to the item with the Section
specified. The default array property, Item, however, provides an easier way to navigate through the object.
If the Retrieve method is used, the Section name of each SectionFormat item is automatically filled when the
SectionFormat information is retrieved.
The Section name syntax is the same as the Short Section Names used in the Crystal Reports Designer as
outlined in the following table. In addition, lower-case letters: a, b, c, etc. are used to specify sub-sections and
numbers are used to designate different Groups: GH1, GF2, etc. See About Section Names, Volume 1, Chapter 7,
for more details on the syntax.
fxampIc
The code below retrieves the SectionFormat settings from the Report, then loops through looking for the
Details "a" section, and sets various options for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormat.Retrieve;
for cnt := 0 to (Crpe1.SectionFormat.Count - 1) do
begin
{Look for Details "a" section}
if Crpe1.SectionFormat[cnt].Section = 'Da' then
begin
Crpe1.SectionFormat[cnt].BackgroundColor := clRed;
Crpe1.SectionFormat[cnt].FreeFormPlacement := cTrue;
Crpe1.SectionFormat[cnt].KeepTogether := cTrue;
Crpe1.SectionFormat[cnt].NewPageAfter := cFalse;
Crpe1.SectionFormat[cnt].NewPageBefore := cFalse;
Crpe1.SectionFormat[cnt].PrintAtBottomOfPage := cDefault;
Crpe1.SectionFormat[cnt].ResetPageNAfter := cFalse;
Crpe1.SectionFormat[cnt].Suppress := cTrue;
Crpe1.SectionFormat[cnt].SuppressBlankSection := cTrue;
RH Report Header
PH Page Header
GH Group Header
D Details
GF Group Footer
PF Page Footer
RF Report Footer
VCI Re|etetce SSS
Crpe1.SectionFormat[cnt].UnderlaySection := cDefault;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFurmat Supprcss prupcrty
DccIaratiun
property Suppress: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
Suppress determines if a Section will appear or not when the Report is run. A Section which is suppressed can
not be drilled down into. To have a section hidden, but still allow drill-down, use the Hide property of the
AreaFormat object.
fxampIc
The code below retrieves the SectionFormat settings from the Report, then loops through looking for the
Details "a" section, and sets the Suppress option for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormat.Retrieve;
for cnt := 0 to (Crpe1.SectionFormat.Count - 1) do
begin
{Look for Details "a" section}
if Crpe1.SectionFormat[cnt].Section = 'Da' then
Crpe1.SectionFormat[cnt].Suppress := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
VCI Re|etetce SS6
ScctiunFurmat SupprcssBIankScctiun prupcrty
DccIaratiun
property SuppressBlankSection: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
Dcscriptiun
SuppressBlankSection determines whether the specified Section will be suppressed if it is blank. A Section
must be completely empty before it will be suppressed. Fields that have empty strings or nulls will be counted
as empty, but if they have even so little as a space for a value, they will not be counted as empty.
fxampIc
The code below retrieves the SectionFormat settings from the Report, then loops through looking for the
Details "a" section, and sets the SuppressBlankSection option for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormat.Retrieve;
for cnt := 0 to (Crpe1.SectionFormat.Count - 1) do
begin
{Look for Details "a" section}
if Crpe1.SectionFormat[cnt].Section = 'Da' then
Crpe1.SectionFormat[cnt].SuppressBlankSection := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFurmat UndcrIayScctiun prupcrty
DccIaratiun
property UnderlaySection: TCrBoolean;
Typc
TCrBoolean = (cFalse, cTrue, cDefault);
VCI Re|etetce SS7
Dcscriptiun
UnderlaySection determines if the specified Section will print underneath the following Section, like a
transparency.
fxampIc
The code below retrieves the SectionFormat settings from the Report, then loops through looking for the
Details "a" section, and sets the UnderlaySection option for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormat.Retrieve;
for cnt := 0 to (Crpe1.SectionFormat.Count - 1) do
begin
{Look for Details "a" section}
if Crpe1.SectionFormat[cnt].Section = 'Da' then
Crpe1.SectionFormat[cnt].UnderlaySection := cTrue;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFurmat ScctiunAsCudc prupcrty
DccIaratiun
property SectionAsCode: smallint
Dcscriptiun
The SectionAsCode property can be used to read and write the Section property via Print Engine Section Code
numbers. Since the Print Engine Section Codes are numeric, it is easier to apply conditional formatting to
certain sections (in a "For loop", for example) based on mathematical calculations on the Section Code number
than it is by parsing out the regular Section Code string (GH1b, etc.).
See also: About Section Names, Volume 1, Chapter 7.
VCI Re|etetce SS8
fxampIc
The SectionAsCode property can be used to apply formatting to specific sections based on mathematical
calculations or comparisons. The following code checks each section to see if it is a "b" section, such as RHb,
PHb, Db, etc., and if it is, the background color is changed to red:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormat.Retrieve;
for cnt := 0 to (Crpe1.SectionFormat.Count - 1) do
begin
if (Crpe1.SectionFormat[cnt].SectionAsCode mod 1000 = 25) then
Crpe1.SectionFormat[cnt].BackgroundColor := clRed;
end;
Crpe1.Execute;0
The logic behind the math expression is based on the fact that each sub-section increments the Section Code
number by 25 (from 0 to 975 are the possible numbers). So, since 3000 is the general Section Code start number
for a Group Header, and is therefore the number to represent GroupHeader 1a, 3025 represents GroupHeader
1b, 3050 represents GroupHeader 1c, etc. Therefore, in order to find the "b" sections we must divide by 1000,
and if the remainder is 25, it is a "b" section. This also works for all the other sections that do not have Group
options, such as Details, ReportHeader, etc. since dividing by 25 will also return no remainder if the Section
Code number is evenly divisible by 1000.
ScctiunFurmat Mcthuds
ScctiunFurmat Add mcthud
DccIaratiun
procedure Add(SectionName: TCrSectionFormatSection);
Typc
TCrSectionFormatSection = string;
Dcscriptiun
The Add method adds an item to the SectionFormat object and sets the internal index to that item. It requires
a Section name as a parameter, which should be a name corresponding to a Section in the Report. Sections are
named using the Short Section Name convention used in Crystal Reports (see About Section Names, Volume 1,
Chapter 7, for more information). If the Add method is used, the steps to using SectionFormat are:
1 Add an item to the SectionFormat object (you must specify the Section name).
VCI Re|etetce SS0
2 Fill the item's properties (NewPageAfter, SuppressBlankSection, etc.) with values.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
Seclon names are correcl lor lhe currenl Reorl.
fxampIc
The Add method can be used to manually add an item to the SectionFormat object, instead of using Retrieve:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Section Name - must be same as in Report}
Crpe1.SectionFormat.Add('Da');
Crpe1.SectionFormat.BackgroundColor := clRed;
Crpe1.Output := toWindow;
Crpe1.Execute;
ScctiunFurmat CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the SectionFormat 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 SectionFormat object of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the SectionFormat of all the Subreports will require a looping
procedure that goes through each Subreport and applies the Clear method.
fxampIc
This code clears the SectionFormat properties for the main Report (assuming the default state of
Subreports[0]):
Crpe1.SectionFormat.Clear;
This code clears the SectionFormat properties for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SectionFormat.Clear;
end;
VCI Re|etetce S66
ScctiunFurmat CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeSectionFormat): boolean;
Dcscriptiun
The CopyFrom method copies the SectionFormat property values from another TCrpeSectionFormat object. It
is similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the SectionFormat property values to a temporary TCrpeSectionFormat
object:
var
tempSectionFormat : TCrpeSectionFormat;
begin
tempSectionFormat := TCrpeSectionFormat.Create;
tempSectionFormat.CopyFrom(Crpe1.SectionFormat);
{...later, when finished with the temp object...}
tempSectionFormat.Free;
end;
ScctiunFurmat Cuunt prupcrty
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the SectionFormat object. It is handy
for setting up loops to make similar changes to each item.
fxampIc
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.SectionFormat.Retrieve;
VCI Re|etetce S61
for cnt := 0 to (Crpe1.SectionFormat.Count - 1) do
begin
{Look for Details "a" section}
if Crpe1.SectionFormat[cnt].Section = 'Da' then
begin
Crpe1.SectionFormat[cnt].BackgroundColor := clRed;
Crpe1.SectionFormat[cnt].FreeFormPlacement := cTrue;
Crpe1.SectionFormat[cnt].KeepTogether := cTrue;
Crpe1.SectionFormat[cnt].ResetPageNAfter := cFalse;
Crpe1.SectionFormat[cnt].Suppress := cTrue;
Crpe1.SectionFormat[cnt].SuppressBlankSection := cTrue;
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFurmat Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the SectionFormat object, and does
not need to be called in code.
ScctiunFurmat DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the SectionFormat object. The "nIndex" parameter
represents the number of the item in the SectionFormat object.
VCI Re|etetce S62
fxampIc
The Delete method can be used to manually remove an item from the SectionFormat object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Section Name - must be same as in Report}
Crpe1.SectionFormat.Add('Da');
Crpe1.SectionFormat.BackgroundColor := clRed;
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.SectionFormat.Delete(0);
ScctiunFurmat Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
ScctiunFurmat Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the SectionFormat information from the Report and stores it in the SectionFormat
object. If no SectionFormat information was found, the call returns False. Be aware that calling Retrieve will
first cause the SectionFormat object to be cleared, so any current information stored in it will be removed.
NO7F: Snce lhe SeclonFormal objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe
SeclonFormal lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you
wanl lo oblan lhe SeclonFormal nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo
sle lhrough lhe Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale SeclonFormal
nlormalon lor each Subreorl (see Fxamle).
VCI Re|etetce S6!
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormat.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SectionFormat.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
ScctiunFurmat ScctiunTypc mcthud
DccIaratiun
function SectionType: string;
Dcscriptiun
The SectionType method returns the Section Code without the subsection specifier. In other words, if the
Section Code for an item is GH1ac, the SectionType method would return GH; if the SectionCode is Da, the
SectionType method would return D.
The primary use for this method is to apply changes to all the Sections in an area, regardless of the sub-section
specifier. See the Example for an illustration.
fxampIc
The following example uses the SectionType method to apply conditional formatting to Sections. In this case,
the formatting is only to apply to Group Header sections:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormat.Retrieve;
VCI Re|etetce S64
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;
ScctiunFurmat Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
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.
fxampIc
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;
ScctiunFurmatFurmuIas Prupcrtics
ScctiunFurmatFurmuIas FurmuIa prupcrty
DccIaratiun
property Formula: TCrpeString;
Typc
TCrpeString = class(TStringList)
VCI Re|etetce S6S
Dcscriptiun
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.
fxampIc
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;
ScctiunFurmatFurmuIas ltcm prupcrty
DccIaratiun
property Item[nIndex: integer]: TCrpeSectionFormatFormulas;
VCI Re|etetce S66
Dcscriptiun
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;
fxampIc
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];
ScctiunFurmatFurmuIas ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
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.
VCI Re|etetce S67
fxampIc
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];
ScctiunFurmatFurmuIas Namc prupcrty
DccIaratiun
property Name: TCrSectionFormatFormula;
Typc
TCrSectionFormatFormula = (sfSuppress, sfPrintAtBottomOfPage,
sfNewPageBefore, sfNewPageAfter, sfResetPageNAfter, sfKeepTogether,
sfSuppressBlankSection, sfUnderlaySection, sfBackgroundColor);
Dcscriptiun
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.
G 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.
G The Retrieve method will obtain the applicable Formula names for each Section in the Report.
G The Names available in a given Section are accessible via the Names array property and the NameCount
method.
G 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.
fxpIanatiun
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];
VCI Re|etetce S68
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
G Section item: RH
Names Items
sfSuppress
sfHide
sfNewPageBefore
sfNewPageAfter
sfKeepTogether
sfResetPageNAfter
sfPrintAtBottomOfPage
sfSuppressBlankSection
sfUnderlaySection
sfBackgroundColor
G Section item: PH
Names Items
sfSuppress
sfHide
sfResetPageNAfter
sfSuppressBlankSection
sfUnderlaySection
sfBackgroundColor
G Section item: GH1
Names Items
sfSuppress
sfHide
etc.
VCI Re|etetce S60
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
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.
NO7F: Cryslal Reorls 6.0.x.1S1 reads lhe SeclonFormalFormula olons ncorreclly lrom older 6.0 verson
Reorls (or l may be lhal lhe older 6.0 Reorls dd nol qule slore lhe olons correclly!). 7hs s only
aarenl on lhe RH and RF Seclons ol a Subreorl. Inslead ol lhe lormula lmlalons (noled n lhe charl
above) aearng n lhe second Reorl Header (RHb) and second Reorl Fooler (RFb), lhey aear on lhe lasl
sub-seclon ol lhe Reorl Header, whch could be RHb l lhere are only 2 sub-seclons (whch s lhe delaull),
or l could be anylhng else (RHd, lor examle). Also, lhe RFb lmlalons do nol aear al all. 7hs behavor
does nol aear when desgnng a new Reorl n 6.0.x.1S1, only when loadng one desgned wlh an earler
verson. For lhs reason, when dealng wlh Subreorls and SeclonFormalFormulas, lhe IndexOlName melhod
s uselul lo make sure a lormula olon s avalable lor lhe Seclon belore allemlng lo assgn a Formula.
fxampIc
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
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
VCI Re|etetce S76
{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;
ScctiunFurmatFurmuIas Namclndcx prupcrty
DccIaratiun
property NameIndex: integer
Dcscriptiun
The NameIndex property is a Run-time only property which can be used to obtain the current Formula Name
item number, or set the Formula Name list to another item.
Comparison of Properties for Section Items and Name Items:
G The SectionFormatFormulas object contains an internal Index which determines which Section item it is
currently looking at. This index is changed via the Section, Item, and ItemIndex properties, and can be
read via the IndexOf method.
G Likewise, since each Section contains numerous Formula Name items, these are controlled via a
secondary internal Index which is changed via the Name, Names, and NameIndex properties, and can
be read via the IndexOfName method.
G That is,
Sections Names
Section Name
Item Names
ItemIndex NameIndex
IndexOf IndexOfName
Count NameCount
VCI Re|etetce S71
fxampIc
This example checks the NameIndex of the Formula names list and sets it to the first item if it is not currently
pointing to that item:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormatFormulas.Retrieve;
if Crpe1.SectionFormatFormulas[0].NameIndex <> 0 then
Crpe1.SectionFormatFormulas[0].NameIndex := 0;
ScctiunFurmatFurmuIas Namcs prupcrty
DccIaratiun
property Names[nIndex: integer]: TCrSectionFormatFormula
Typc
TCrSectionFormatFormula = (sfSuppress, sfPrintAtBottomOfPage,
sfNewPageBefore, sfNewPageAfter, sfResetPageNAfter, sfKeepTogether,
sfSuppressBlankSection, sfUnderlaySection, sfBackgroundColor);
Dcscriptiun
The Names property can be used to step through the Formula Name items of an SectionFormatFormulas item
by numerical subscript. It is useful in looping constructs, to gather all the Formula Names that apply to a
particular Section. In this case, it should be used along with the NameCount method, to avoid a "Subscript out
of bounds" error.
Comparison of Properties for Section Items and Name Items:
G The SectionFormatFormulas object contains an internal Index which determines which Section item it is
currently looking at. This index is changed via the Section, Item, and ItemIndex properties, and can be
read via the IndexOf method.
G Likewise, since each Section contains numerous Formula Name items, these are controlled via a
secondary internal Index which is changed via the Name, Names, and NameIndex properties, and can
be read via the IndexOfName method.
G That is,
Sections Names
Section Name
Item Names
ItemIndex NameIndex
IndexOf IndexOfName
Count NameCount
VCI Re|etetce S72
fxampIc
The Names property is used in the example below, to loop through the Formula items for the Page Header
section, sending the Formula names to a ListBox:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormatFormulas.Retrieve;
Crpe1.AreaFormatFormulas.Section := 'PH';
for cnt := 0 to (Crpe1.AreaFormatFormulas.NameCount - 1) do
begin
case Ord(Crpe1.AreaFormatFormulas.Names[cnt]) of
0: ListBox1.Items.Add('afHide');
1: ListBox1.Items.Add('afSuppress');
2: ListBox1.Items.Add('afPrintAtBottomOfPage');
3: ListBox1.Items.Add('afNewPageBefore');
4: ListBox1.Items.Add('afNewPageAfter');
5: ListBox1.Items.Add('afResetPageNAfter');
6: ListBox1.Items.Add('afKeepTogether');
end;
end;
end;
ScctiunFurmatFurmuIas Scctiun prupcrty
DccIaratiun
property Section: TCrSectionFormatFormulasSection;
Typc
TCrSectionFormatFormulasSection = string;
Dcscriptiun
The Section property specifies the Report Section name that the Formula will apply to. The property acts as a
look-up, to point the SectionFormatFormulas object to the item with the Section specified. The Retrieve
method can be used to fill the SectionFormatFormulas object with information from the Report, thus filling the
Section property with appropriate values.
The Section name syntax is the same as the Short Section Names used in the Crystal Reports Designer:
RH - Report Header
PH - Page Header
VCI Re|etetce S7!
GH - Group Header
D - Details
GF - Group Footer
PF - Page Footer
RF - Report Footer
Lower-case letters: a, b, c, etc. are used to specify sub-sections. Numbers are used to designate different
Groups: GH1, GF2, etc. See About Section Names, Volume 1, Chapter 7, for more details on the syntax.
NO7F: Whereas objecls such as AreaFormal and AreaFormalFormulas work on cerlan areas, lor examle, lhe
Delals area, SeclonFormal and SeclonFormalFormulas work on seclc ndvdual sub-seclons, such as
Delals "a", Delals "b", elc. 7he olons sel n lhese objecls allecl only lhe arlcular sub-seclon secled by
lhe Seclon roerly.
fxampIc
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;
ScctiunFurmatFurmuIas ScctiunAsCudc prupcrty
DccIaratiun
property SectionAsCode: smallint;
VCI Re|etetce S74
Dcscriptiun
The SectionAsCode property can be used to read and write the Section property via Print Engine Section Code
numbers. Since the Print Engine Section Codes are numeric, it is easier to apply conditional formatting to
certain sections (in a For loop for example) based on mathematical calculations on the Section Code number
than it is by parsing out the regular Section Code string (GH1b, etc.).
See also: About Section Names, Volume 1, Chapter 7.
fxampIc
The SectionAsCode property can be used to apply formula-based formatting to specific sections based on
mathematical calculations or comparisons. The following code checks each section to see if it is a "b" section,
such as RHb, PHb, Db, etc., and if it is, the background color is changed to red according to a formula:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormatFormulas.Retrieve;
for cnt := 0 to (Crpe1.SectionFormatFormulas.Count - 1) do
begin
if (Crpe1.SectionFormatFormulas[cnt].SectionAsCode mod
1000 = 25) then
begin
Crpe1.SectionFormatFormulas[cnt].Name := sfBackgroundColor;
Crpe1.SectionFormatFormulas[cnt].Formula.Text := '{company.STATE}
= "CA"';
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
The logic behind the math expression is based on the fact that each sub-section increments the Section Code
number by 25 (from 0 to 975 are the possible numbers). So, since 3000 is the general Section Code start number
for a Group Header, and is therefore the number to represent GroupHeader 1a, 3025 represents GroupHeader
1b, 3050 represents GroupHeader 1c, etc. Therefore, in order to find the "b" sections we must divide by 1000,
and if the remainder is 25, it is a "b" section. This formula also works for Sections that do not have Group
options, such as Details (Da = 4000, Db = 4025, etc.).
ScctiunFurmatFurmuIas Mcthuds
ScctiunFurmatFurmuIas Add mcthud
DccIaratiun
procedure Add(SectionName: TCrSectionFormatFormulasSection);
VCI Re|etetce S7S
Typc
TCrSectionFormatFormulasSection = string;
Dcscriptiun
The Add method adds an item to the SectionFormatFormulas object and sets the internal index to that item. It
requires a Section name as a parameter, which should be a name corresponding to a Section in the Report.
Sections are named using the Short Section Name convention used in Crystal Reports (see About Section Names,
Volume 1, Chapter 7, for more information). If the Add method is used, the steps to using
SectionFormatFormulas are:
1 Add an item to the SectionFormatFormulas object (you must specify the Section name).
2 Specify values for the properties (Name, Formula, etc.).
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
Seclon names are correcl lor lhe currenl Reorl.
ScctiunFurmatFurmuIas Chcck mcthud
DccIaratiun
function Check: boolean;
Dcscriptiun
The Check method can be used to check the syntax of a SectionFormatFormula while running the Report.
Check returns a boolean value:
Rcturns
G TRUE if the SectionFormat Formula is good.
G FALSE if the SectionFormat Formula has an error.
NO7F: Al lhs lme, lhe error wll nol be relurned unll lhe reorl s run. Pror lo runnng lhe reorl, lhs
melhod wll relurn 7RUF.
ScctiunFurmatFurmuIas CIcar mcthud
DccIaratiun
procedure Clear;
VCI Re|etetce S76
Dcscriptiun
This method can be used to clear the internal memory of the SectionFormatFormulas 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 SectionFormatFormulas object of the current Report/Subreport
specified in the Subreports object. Therefore, to clear all the SectionFormatFormulas of all the Subreports will
require a looping procedure that goes through each Subreport and applies the Clear method.
fxampIc
This code clears the SectionFormatFormulas properties for the main Report (assuming the default state of
Subreports[0]):
Crpe1.SectionFormatFormulas.Clear;
This code clears the SectionFormatFormulas for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SectionFormatFormulas.Clear;
end;
ScctiunFurmatFurmuIas CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeSectionFormatFormulas): boolean;
Dcscriptiun
The CopyFrom method copies the SectionFormatFormulas property values from another
TCrpeSectionFormatFormulas object. It is similar to Delphi's Assign method. It is useful for transferring or
temporary storage of values.
fxampIc
The following example copies all the SectionFormatFormulas property values to a temporary
TCrpeSectionFormatFormulas object:
var
tempSectionFormatFormulas : TCrpeSectionFormatFormulas ;
begin
tempSectionFormatFormulas := TCrpeSectionFormatFormulas.Create;
tempSectionFormatFormulas .CopyFrom(Crpe1.SectionFormatFormulas);
{...later, when finished with the temp object...}
tempSectionFormatFormulas .Free;
end;
VCI Re|etetce S77
ScctiunFurmatFurmuIas Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the SectionFormatFormulas object.
It is handy for setting up loops to make similar changes to each item.
fxampIc
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.SectionFormatFormulas.Retrieve;
for cnt := 0 to (Crpe1.SectionFormatFormulas.Count - 1) do
begin
Crpe1.SectionFormatFormulas[cnt].Name := sfKeepTogether;
Crpe1.SectionFormatFormulas[cnt].Formula.Text := 'True';
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFurmatFurmuIas Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create constructor creates the SectionFormatFormulas object. It is used internally in the VCL component
to create the SectionFormatFormulas object when the component is created, and should not be called outside
of the component.
VCI Re|etetce S78
ScctiunFurmatFurmuIas DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the SectionFormatFormulas object. The "nIndex"
parameter represents the number of the item in the SectionFormatFormulas object.
fxampIc
The Delete method can be used to manually remove an item from the SectionFormatFormulas object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Section Name - must be same as in Report}
Crpe1.SectionFormatFormulas.Add('PH');
Crpe1.SectionFormatFormulas.Name := afSuppress;
Crpe1.SectionFormatFormulas.Formula.Text := 'True';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.SectionFormatFormulas.Delete(0);
ScctiunFurmatFurmuIas Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method frees the SectionFormatFormulas object. It is used internally in the VCL component to
destroy the SectionFormatFormulas object when the component is destroyed, and should not be called outside
of the component.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
VCI Re|etetce S70
ScctiunFurmatFurmuIas lndcxOf mcthud
DccIaratiun
function IndexOf(SectionName: TCrSectionFormatFormulasSection): integer;
Typc
TCrSectionFormatFormulasSection = string;
Dcscriptiun
The IndexOf method takes a Section name and returns the index position of the Section item in the current
SectionFormatFormulas object.
After the Retrieve method has been called, the SectionFormatFormulas object contains one item for each
Section in the Report. This could be illustrated like so (the Section items in your Reports may not be the same):
SectionFormatFormulas - Section items
RHa
RHb
PH
GH1
GH2a
GH2b
D
GF2b
GF2a
GF1
PF
RFa
RFb
The IndexOf method can be used to determine if a given Section Name actually exists in the
SectionFormatFormulas object before trying to access it.
VCI Re|etetce S86
fxampIc
The following code illustrates the use of the IndexOf method to locate a specific Section:
var
nItem: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormatFormulas.Retrieve;
{Find Details "a" section}
nItem := Crpe1.SectionFormatFormulas.IndexOf('Da');
{If it exists...}
if nItem > -1 then
begin
with Crpe1.SectionFormatFormulas[nItem] do
begin
{Suppress section if STATE is California}
Name := sfSuppress;
Formula.Text := '{company.STATE} = "CA"';
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunFurmatFurmuIas lndcxOfNamc mcthud
DccIaratiun
function IndexOfName(FormulaName: TCrSectionFormatFormula): integer;
Typc
TCrSectionFormatFormula = (sfSuppress, sfPrintAtBottomOfPage,
sfNewPageBefore, sfNewPageAfter, sfResetPageNAfter, sfKeepTogether,
sfSuppressBlankSection, sfUnderlaySection, sfBackgroundColor);
Dcscriptiun
The IndexOfName method takes a SectionFormatFormula name and returns the index position of the Formula
item in the current Section item of the SectionFormatFormulas object. See the explanation of the Name
property for more details.
VCI Re|etetce S81
Comparison of Properties for Section Items and Name Items:
G The SectionFormatFormulas object contains an internal Index which determines which Section item it is
currently looking at. This index is changed via the Section, Item, and ItemIndex properties, and can be
read via the IndexOf method.
G Likewise, since each Section contains numerous Formula Name items, these are controlled via a
secondary internal Index which is changed via the Name, Names, and NameIndex properties, and can
be read via the IndexOfName method.
fxampIc
This example uses the IndexOfName method to update a ListBox of Formula Names for the Details Section:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormatFormulas.Retrieve;
{Set SectionFormatFormulas object to Details item}
Crpe1.SectionFormatFormulas.Section := 'D';
{Loop through and get formula names}
for cnt := 0 to (Crpe1.SectionFormatFormulas.NameCount - 1) do
begin
case Ord(Crpe1.SectionFormatFormulas.Names[cnt]) of
0: ListBox1.Items.Add('Suppress');
1: ListBox1.Items.Add('PrintAtBottomOfPage');
2: ListBox1.Items.Add('NewPageBefore');
3: ListBox1.Items.Add('NewPageAfter');
4: ListBox1.Items.Add('ResetPageNAfter');
5: ListBox1.Items.Add('KeepTogether');
6: ListBox1.Items.Add('SuppressBlankSection');
7: ListBox1.Items.Add('UnderlaySection');
8: ListBox1.Items.Add('BackgroundColor');
end;
end;
{Set Formulas Index to UnderlaySection}
Crpe1.SectionFormatFormulas.Name := sfUnderlaySection;
{Get Index number}
nItem := Crpe1.SectionFormatFormulas.IndexOfName(sfUnderlaySection);
{Update ListBox with Index}
ListBox1.ItemIndex := nItem;
Sections Names
Section Name
Item Names
ItemIndex NameIndex
IndexOf IndexOfName
Count NameCount
VCI Re|etetce S82
ScctiunFurmatFurmuIas NamcCuunt mcthud
DccIaratiun
function NameCount: integer;
Dcscriptiun
The NameCount property returns the number of Formula Names available for a specific Section. NameCount
can be used with the Names property in a looping construct, to step through the Formula Name items.
Comparison of Properties for Section Items and Name Items:
G The SectionFormatFormulas object contains an internal Index which determines which Section item it is
currently looking at. This index is changed via the Section, Item, and ItemIndex properties, and can be
read via the IndexOf method.
G Likewise, since each Section contains numerous Formula Name items, these are controlled via a
secondary internal Index which is changed via the Name, Names, and NameIndex properties, and can
be read via the IndexOfName method.
fxampIc
The Names property is used in the example below, to loop through the Formula items for the Page Header
section, sending the Formula names to a ListBox:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.AreaFormatFormulas.Retrieve;
Crpe1.AreaFormatFormulas.Section := 'PH';
for cnt := 0 to (Crpe1.AreaFormatFormulas.NameCount - 1) do
begin
case Ord(Crpe1.AreaFormatFormulas.Names[cnt]) of
0: ListBox1.Items.Add('afHide');
1: ListBox1.Items.Add('afSuppress');
2: ListBox1.Items.Add('afPrintAtBottomOfPage');
Sections Names
Section Name
Item Names
ItemIndex NameIndex
IndexOf IndexOfName
Count NameCount
VCI Re|etetce S8!
3: ListBox1.Items.Add('afNewPageBefore');
4: ListBox1.Items.Add('afNewPageAfter');
5: ListBox1.Items.Add('afResetPageNAfter');
6: ListBox1.Items.Add('afKeepTogether');
end;
end;
end;
ScctiunFurmatFurmuIas Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the SectionFormatFormulas from the Report and stores them in the
SectionFormatFormulas object. If SectionFormatFormulas information was not found, the call returns False.
Be aware that calling Retrieve will first cause the SectionFormatFormulas object to be cleared, so any current
information stored in it will be removed.
NO7F: Snce lhe SeclonFormalFormulas objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe
SeclonFormalFormulas lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo.
Il you wanl lo oblan lhe SeclonFormalFormulas nlormalon lor lhe man Reorl and all ol lhe Subreorls,
you wll have lo sle lhrough lhe Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore
searale SeclonFormalFormulas nlormalon lor each Subreorl (see Fxamle).
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormatFormulas.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
VCI Re|etetce S84
Crpe1.SectionFormatFormulas.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
ScctiunFurmatFurmuIas ScctiunTypc mcthud
DccIaratiun
property SectionType: string;
Dcscriptiun
The SectionType method returns the Section Code without the subsection specifier. In other words, if the
Section Code for an item is GH1a, the SectionType method would return GH; if the SectionCode is Da, the
SectionType method would return D.
The primary use for this method is to apply changes to all the Sections in an area, regardless of the sub-section
specifier. See the Example for an illustration.
fxampIc
The following example uses the SectionType method to apply conditional formatting. The formatting is to
apply to all Group Header sections, so the SectionType method can be used in an expression to apply the
changes:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionFormatFormulas.Retrieve;
for cnt := 0 to (Crpe1.SectionFormatFormulas.Count - 1) do
begin
{if the SectionType is Group Header, apply the change}
if (Crpe1.SectionFormatFormulas[cnt].SectionType = 'GH') then
begin
Crpe1.SectionFormatFormulas[cnt].Name := sfSuppress;
Crpe1.SectionFormatFormulas[cnt].Formula.Text := '{company.STATE}
= "CA"';
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
VCI Re|etetce S8S
ScctiunFurmatFurmuIas Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the SectionFormatFormulas 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.
fxampIc
In this example, the SectionFormatFormulas settings are sent from the Crystal component to the Crystal
Reports Print Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.SectionFormatFormulas.Send;
ScctiunHcight Prupcrtics
ScctiunHcight Hcight prupcrty
DccIaratiun
property Height: smallint;
Dcscriptiun
Height determines the height of the specified Section in twips.
There are 1440 twips to an inch.
There are 20 twips to a point.
There are 72 points to an inch.
Conversion Formulas:
Twips = Inches * 1440
Inches = Twips / 1440
VCI Re|etetce S86
Points = Twips / 20
Twips = Points * 20
Inches = Points / 72
Points = Inches * 72
fxampIc
The code below retrieves the SectionHeight settings from the Report, then loops through looking for the
Details "a" section, and sets the Height for that Section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionHeight.Retrieve;
for cnt := 0 to (Crpe1.SectionHeight.Count - 1) do
begin
{Look for Details area}
if Crpe1.SectionHeight[cnt].Section = 'Da' then
Crpe1.SectionHeight[cnt].Height := 400;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScctiunHcight ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeSectionHeight;
Dcscriptiun
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 various items stored in the SectionHeight object, allowing the
object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript:
SectionHeight[2] is the same as SectionHeight.Item[2].
G Item returns a reference to itself, so the SectionHeight properties can be used right after the subscript:
SectionHeight[2].Height:= 300;
VCI Re|etetce S87
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.SectionHeight.Retrieve;
{Set SectionHeight to the 3rd section}
Crpe1.SectionHeight.Item[2];
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.SectionHeight.Retrieve;
{Set SectionHeight to the 3rd section}
Crpe1.SectionHeight[2];
ScctiunHcight ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current SectionHeight item number,
or set the SectionHeight 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 (SectionHeight[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the SectionHeight object is
pointing to the first SectionHeight item:
if Crpe1.SectionHeight.ItemIndex <> 0 then
Crpe1.SectionHeight[0];
ScctiunHcight Scctiun prupcrty
DccIaratiun
property Section: TCrSectionHeightSection;
VCI Re|etetce S88
Typc
TCrSectionHeightSection = string;
Dcscriptiun
The Section property contains the Section name of the item that the SectionHeight object is currently pointed
to. It's primary use is as a look-up property to point the SectionHeight object to the item with the Section
specified. The default array property, Item, however, provides an easier way to navigate through the object.
If the Retrieve method is used, the Section name of each SectionHeight item is automatically filled when the
SectionHeight information is retrieved.
The Section name syntax is the same as the Short Section Names used in the Crystal Reports Designer:
RH - Report Header
PH - Page Header
GH - Group Header
D - Details
GF - Group Footer
PF - Page Footer
RF - Report Footer
Lower-case letters: a, b, c, etc. are used to specify sub-sections. Numbers are used to designate different
Groups: GH1, GF2, etc. See About Section Names, Volume 1, Chapter 7, for more details on the syntax.
fxampIc
The code below retrieves the SectionHeight settings from the Report, then loops through looking for the
Details "a" section, and sets the Height for that section:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionHeight.Retrieve;
for cnt := 0 to (Crpe1.SectionHeight.Count - 1) do
begin
{Look for Details area}
if Crpe1.SectionHeight[cnt].Section = 'Da' then
Crpe1.SectionHeight[cnt].Height := 400;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
VCI Re|etetce S80
ScctiunHcight ScctiunAsCudc prupcrty
DccIaratiun
property SectionAsCode: smallint;
Dcscriptiun
The SectionAsCode property can be used to read and write the Section property via Print Engine Section Code
numbers. Since the Print Engine Section Codes are numeric, it is easier to apply conditional formatting to
certain sections (in a For loop for example) based on mathematical calculations on the Section Code number
than it is by parsing out the regular Section Code string (GH1b, etc.).
See also: About Section Names, Volume 1, Chapter 7.
fxampIc
The SectionAsCode property can be used to apply formatting to specific sections based on mathematical
calculations or comparisons. The following code checks each section to see if it is a "b" section, such as RHb,
PHb, Db, etc., and if it is, the SectionHeight is changed to 500 twips:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionHeight.Retrieve;
for cnt := 0 to (Crpe1.SectionHeight.Count - 1) do
begin
if (Crpe1.SectionHeight[cnt].SectionAsCode mod 1000 = 25) then
Crpe1.SectionHeight[cnt].Height := 500;
end;
Crpe1.Execute;
The logic behind the math expression is based on the fact that each sub-section increments the Section Code
number by 25 (from 0 to 975 are the possible numbers). So, since 3000 is the general Section Code start number
for a Group Header, and is therefore the number to represent GroupHeader 1a, 3025 represents GroupHeader
1b, 3050 represents GroupHeader 1c, etc. Therefore, in order to find the "b" sections we must divide by 1000,
and if the remainder is 25, it is a "b" section. This also works for all the other sections that do not have Group
options, such as Details, ReportHeader, etc. since dividing by 25 will also return no remainder if the Section
Code number is evenly divisible by 1000.
ScctiunHcight Mcthuds
ScctiunHcight Add mcthud
DccIaratiun
procedure Add(SectionName: TCrSectionHeightSection);
VCI Re|etetce S06
Typc
TCrSectionHeightSection = string;
Dcscriptiun
The Add method adds an item to the SectionHeight object and sets the internal index to that item. It requires
a Section name as a parameter, which should be a name corresponding to a Section in the Report. Sections are
named using the Short Section Name convention used in Crystal Reports (see About Section Names, Volume 1,
Chapter 7, for more information). If the Add method is used, the steps to using SectionHeight are:
1 Add an item to the SectionHeight object (you must specify the Section name).
2 Fill the Height property with a value.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
Seclon names are correcl lor lhe currenl Reorl.
fxampIc
The Add method can be used to manually add an item to the SectionHeight object, instead of using Retrieve:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Section Name - must be same as in Report}
Crpe1.SectionHeight.Add('PH');
Crpe1.SectionHeight.Height := 500;
Crpe1.Output := toWindow;
Crpe1.Execute;
ScctiunHcight CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the SectionHeight 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 SectionHeight object of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the SectionHeight of all the Subreports will require a looping
procedure that goes through each Subreport and applies the Clear method.
VCI Re|etetce S01
fxampIc
This code clears the SectionHeight properties for the main Report (assuming the default state of
Subreports[0]):
Crpe1.SectionHeight.Clear;
This code clears the SectionHeight properties for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SectionHeight.Clear;
end;
ScctiunHcight CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeSectionHeight): boolean;
Dcscriptiun
The CopyFrom method copies the SectionHeight property values from another TCrpeSectionHeight object. It
is similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the SectionHeight property values to a temporary TCrpeSectionHeight
object:
var
tempSectionHeight : TCrpeSectionHeight;
begin
tempSectionHeight := TCrpeSectionHeight.Create;
tempSectionHeight.CopyFrom(Crpe1.SectionHeight);
{...later, when finished with the temp object...}
tempSectionHeight.Free;
end;
ScctiunHcight Cuunt mcthud
DccIaratiun
function Count: integer;
VCI Re|etetce S02
Dcscriptiun
The Count method can be used to obtain the number of items currently in the SectionHeight object. It is handy
for setting up loops to make similar changes to each item.
fxampIc
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.SectionHeight.Retrieve;
for cnt := 0 to (Crpe1.SectionHeight.Count - 1) do
Crpe1.SectionHeight[cnt].Height := 500;
end;
ScctiunHcight Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the SectionHeight object, and does
not need to be called in code.
ScctiunHcight DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the SectionHeight object. The "nIndex" parameter
represents the number of the item in the SectionHeight object.
VCI Re|etetce S0!
fxampIc
The Delete method can be used to manually remove an item from the SectionHeight object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Section Name - must be same as in Report}
Crpe1.SectionHeight.Add('PH');
Crpe1.SectionHeight.Height := 500;
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.SectionHeight.Delete(0);
ScctiunHcight Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
ScctiunHcight Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the SectionHeight information from the Report and stores it in the SectionHeight
object. If no SectionHeight information was found, the call returns False. Be aware that calling Retrieve will
first cause the SectionHeight object to be cleared, so any current information stored in it will be removed.
NO7F: Snce lhe SeclonHeghl objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe
SeclonHeghl lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you
wanl lo oblan lhe SeclonHeghl nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo
sle lhrough lhe Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale SeclonHeghl
nlormalon lor each Subreorl (see Fxamle).
VCI Re|etetce S04
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SectionHeight.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SectionHeight.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
ScctiunHcight ScctiunTypc mcthud
DccIaratiun
function SectionType: string;
Dcscriptiun
The SectionType method returns the Section Code without the subsection specifier. In other words, if the
Section Code for an item is GH1ac, the SectionType method would return GH; if the SectionCode is Da, the
SectionType method would return D.
The primary use for this method is to apply changes to all the Sections in an area, regardless of the sub-section
specifier.
fxampIc
The following example uses the SectionType method to apply conditional formatting. In this case, we only
want to change the SectionHeight for the Group Header sections, so the SectionType method can be used in
an expression to apply the changes:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
VCI Re|etetce S0S
Crpe1.SectionHeight.Retrieve;
for cnt := 0 to (Crpe1.SectionHeight.Count - 1) do
begin
{if the SectionType is Group Header, apply the change}
if (Crpe1.SectionHeight[cnt].SectionType = 'GH') then
Crpe1.SectionHeight[cnt].Height := 500;
end;
end;
ScctiunHcight Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the SectionHeight 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.
fxampIc
In this example, the SectionHeight settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.SectionHeight.Send;
ScIcctiun Prupcrtics
ScIcctiun FurmuIa prupcrty
DccIaratiun
property Formula: TCrpeString;
Typc
TCrpeString = class(TStringList)
VCI Re|etetce S06
Dcscriptiun
The Formula property specifies the actual Selection Formula text. Any values in the selection formula that
must be seen as strings should be put in double quotes, for example:
Crpe1.Selection.Formula.Text := '{company.STATE} = "CA"';
When the Replace property is set to False, the Selection Formula that is passed in to the Report is appended
with a Boolean "AND" to any characters in the Selection Formula currently in the Report. This includes
comment lines (any text on a line with two forward slashes in front of it) and existing Selection Formulas.
Therefore, care must be taken to make sure the Selection Formula in the Report is valid. When in doubt, use
the Retrieve method and build the whole statement in Delphi, then replace the current Selection, by setting
Replace to True.
See also Using Variables with Selection Formula, Page 102.
fxampIc
The following example retrieves the current Selection Formula from the Report and adds an OR condition:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the Selection}
Crpe1.Selection.Retrieve;
{Add an OR condition}
Crpe1.Selection.Formula.Add(' OR {company.STATE} = "WA"');
{Replace the Selection in the Report with the new one}
Crpe1.Selection.Replace := True;
{Check the Selection before running Report}
if Crpe1.Selection.Check then
begin
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScIcctiun RcpIacc prupcrty
DccIaratiun
property Replace: boolean;
Dcscriptiun
The Replace property determines if the Selection Formula sent from the VCL will replace the one that is
already in the Report (if there is one), or if it will be ANDed on to the end.
By default, Replace is set to True.
VCI Re|etetce S07
For example,
If there is a Selection Formula in the Report that reads:
{company.STATE} = "WA"
And there is a Selection Formula in the VCL that reads:
{company.SALES} = 100000
If Replace is True, the Selection Formula in the Report (when it is run) will read:
{company.SALES} = 100000
If Replace is False, the Selection Formula in the Report (when it is run) will read:
{company.STATE} = "WA" AND {company.SALES} = 100000
fxampIc
The following example retrieves the current Selection Formula from the Report and adds an OR condition. It
then sends the Formula back in, replacing the one that is currently there:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the Selection}
Crpe1.Selection.Retrieve;
{Add an OR condition}
Crpe1.Selection.Formula.Add(' OR {company.STATE} = "WA"');
{Replace the Selection in the Report with the new one}
Crpe1.Selection.Replace := True;
{Check the Selection before running Report}
if Crpe1.Selection.Check then
begin
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScIcctiun Mcthuds
ScIcctiun Chcck mcthud
DccIaratiun
function Check: boolean;
Dcscriptiun
The Check method can be used to check the syntax of a Selection Formula before running the Report. Check
returns a boolean value.
VCI Re|etetce S08
Rcturns
G TRUE if the Selection Formula is good.
G FALSE if the Selection Formula has an error.
fxampIc
The following example retrieves the current Selection Formula from the Report and adds an OR condition. It
then sends the Formula back in, checking it for proper syntax:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the Selection}
Crpe1.Selection.Retrieve;
{Add an OR condition}
Crpe1.Selection.Formula.Add(' OR {company.STATE} = "WA"');
{Replace the Selection in the Report with the new one}
Crpe1.Selection.Replace := True;
{Check the Selection before running Report}
if Crpe1.Selection.Check then
begin
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
ScIcctiun CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the Selection object. It clears the Formula property and
sets the Replace property to True. 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 Selection object of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the Selection of all the Subreports will require a looping procedure
that goes through each Subreport and applies the Clear method.
fxampIc
This code clears the Selection for the main Report (assuming the default state of Subreports[0]):
Crpe1.Selection.Clear;
VCI Re|etetce S00
This code clears the Selection for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.Selection.Clear;
end;
ScIcctiun CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeSelectionFormula): boolean;
Dcscriptiun
The CopyFrom method copies the Selection property values from another TCrpeSelectionFormula object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the Selection property values to a temporary TCrpeSelectionFormula object:
var
tempSelection : TCrpeSelectionFormula;
begin
tempSelection := TCrpeSelectionFormula.Create;
tempSelection.CopyFrom(Crpe1.Selection);
{...later, when finished with the temp object...}
tempSelection.Free;
end;
ScIcctiun Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the Selection object, and does not need
to be called in code.
VCI Re|etetce 666
ScIcctiun Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
ScIcctiun Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the Selection Formula from the Report and stores it in the Formula property of
the Selection object. If successful, the call returns True. Be aware that calling Retrieve will first cause the
Selection object to be cleared, so any current information stored in it will be removed.
NO7F: Snce lhe Seleclon objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe Seleclon lor
lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl lo oblan lhe
Seleclon nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle lhrough lhe
Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale Seleclon nlormalon lor each
Subreorl (see Fxamle).
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Selection.Retrieve;
VCI Re|etetce 661
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.Selection.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
ScIcctiun Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the Selection 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.
fxampIc
In this example, the Selection settings are sent from the Crystal component to the Crystal Reports Print Engine
DLL. This is normally handled automatically in the Execute method:
Crpe1.Selection.Send;
VCI Re|etetce 662
Scssiunlnfu Prupcrtics
Scssiunlnfu DBPasswurd prupcrty
DccIaratiun
property DBPassword: string;
Dcscriptiun
The DBPassword property specifies the Database Password for an MS Access table that has Database-Level
security.
fxampIc
The code example below shows how to retrieve the SessionInfo, and then loop through the items to set the
UserID and UserPassword before running the Report:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SessionInfo.Retrieve;
for cnt := 0 to (Crpe1.SessionInfo.Count - 1) do
Crpe1.SessionInfo[cnt].DBPassword := '007';
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
The next example does the same as the above, but uses the Propagate property to eliminate the need for a code
loop to pass set the information for each table:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SessionInfo.Retrieve;
Crpe1.SessionInfo[0].DBPassword := '007';
Crpe1.SessionInfo.Propagate := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
Scssiunlnfu HandIc prupcrty
DccIaratiun
property Handle: LongInt;
VCI Re|etetce 66!
Dcscriptiun
The Handle property specifies the handle to the MS Access Session, and can be used instead of passing
information to the UserID and UserPassword properties. If the Handle value is 0, the Crystal Report Engine
uses the UserID and UserPassword settings. In all other cases it uses the Handle value.
Scssiunlnfu ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeSessionInfo;
Dcscriptiun
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 various items stored in the SessionInfo object, allowing the
object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript:
SessionInfo[2] is the same as SessionInfo.Item[2].
G Item returns a reference to itself, so the SessionInfo properties can be used right after the subscript:
SessionInfo[2].DBPassword:= 'myPassword';
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.SessionInfo.Retrieve;
{Set SessionInfo object to the 3rd item}
Crpe1.SessionInfo.Item[2];
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.SessionInfo.Retrieve;
{Set SessionInfo object to the 3rd item}
Crpe1.SessionInfo[2];
Scssiunlnfu ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
VCI Re|etetce 664
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current SessionInfo item number, or
set the SessionInfo 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 (SessionInfo[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the SessionInfo object is pointing
to the first SessionInfo item:
if Crpe1.SessionInfo.ItemIndex <> 0 then
Crpe1.SessionInfo[0];
Scssiunlnfu Prupagatc prupcrty
DccIaratiun
property Propagate: boolean;
Dcscriptiun
The Propagate property takes the SessionInfo values applied to the first SessionInfo item (which usually points
to the first Table in a Report), and applies them to all the other SessionInfo items (or Tables) in the Report.
G Propagate only applies to the current Report.
G When setting Propagate for a Subreport, the other Tables in the Subreport will get their SessionInfo
settings from the first Table of that Subreport.
fxampIc
The code example below shows how to retrieve the SessionInfo, set the first item's UserID and UserPassword,
then set the Propagate property to make these values apply to all other items for that Report (but not for
Subreports, which must be set separately):
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SessionInfo.Retrieve;
Crpe1.SessionInfo[0].UserID := 'Bond';
Crpe1.SessionInfo[0].UserPassword := '007';
Crpe1.SessionInfo.Propagate := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 66S
Scssiunlnfu TabIc prupcrty
DccIaratiun
property Table: TCrSessionInfoTable;
Dcscriptiun
The Table property specifies the Table number of a SessionInfo item. It's primary use is as a look-up property
to point the SessionInfo object to the item with the Table number specified. The default array property, Item,
however, provides an easier way to navigate through the object.
If the Retrieve method is used, the SessionInfo information is retrieved from the Report, and the Table number
of each SessionInfo item is automatically filled with values from the Report. In this case, the Table number and
the Item number are usually the same, i.e. Table := 0 will point to the same item as SessionInfo[0].
fxampIc
The code example below shows how to retrieve the SessionInfo, and then loop through the items to set the
UserID and UserPassword before running the Report:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SessionInfo.Retrieve;
{Set SessionInfo to item with Table number 0}
Crpe1.SessionInfo.Table := 0;
Crpe1.SessionInfo.UserID := 'Bond';
Crpe1.SessionInfo.UserPassword := '007';
Crpe1.SessionInfo.Propagate := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
Scssiunlnfu UscrlD prupcrty
DccIaratiun
property UserID: string;
Dcscriptiun
The UserID property specifies the User ID for an MS Access table that has User-Level security.
VCI Re|etetce 666
fxampIc
The code example below shows how to retrieve the SessionInfo, and then loop through the items to set the
UserID and UserPassword before running the Report:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SessionInfo.Retrieve;
for cnt := 0 to (Crpe1.SessionInfo.Count - 1) do
begin
Crpe1.SessionInfo[cnt].UserID := 'Bond';
Crpe1.SessionInfo[cnt].UserPassword := '007';
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
Scssiunlnfu UscrPasswurd prupcrty
DccIaratiun
property UserPassword: string;
Dcscriptiun
The UserPassword property specifies the password for an MS Access table that has User-Level security.
fxampIc
The code example below shows how to retrieve the SessionInfo, and then loop through the items to set the
UserID and UserPassword before running the Report:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SessionInfo.Retrieve;
for cnt := 0 to (Crpe1.SessionInfo.Count - 1) do
begin
Crpe1.SessionInfo[cnt].UserID := 'Bond';
Crpe1.SessionInfo[cnt].UserPassword := '007';
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
VCI Re|etetce 667
Scssiunlnfu Mcthuds
Scssiunlnfu Add mcthud
DccIaratiun
procedure Add(TableNumber: TCrSessionInfoTable);
Typc
TCrSessionInfoTable = integer;
Dcscriptiun
The Add method adds an item to the SessionInfo object and sets the internal index to that item. It requires a
Table number as a parameter, which should be a number corresponding to a Table in the Report. Tables are
numbered starting from zero. If the Add method is used, the steps to using SessionInfo are:
1 Add an item to the SessionInfo object (you must specify the Table number).
2 Fill the item's properties (UserID, UserPassword, etc.) with values.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
7able numbers are correcl lor lhe currenl Reorl.
fxampIc
The Add method can be used to manually add an item to the SessionInfo object, instead of using Retrieve:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Table Number - must be same as in Report}
Crpe1.SessionInfo.Add(0);
Crpe1.SessionInfo.UserID := 'Bond';
Crpe1.SessionInfo.UserPassword := '007';
Crpe1.Output := toWindow;
Crpe1.Execute;
Scssiunlnfu CIcar mcthud
DccIaratiun
procedure Clear;
VCI Re|etetce 668
Dcscriptiun
This method can be used to clear the internal memory of the SessionInfo 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 SessionInfo object of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the SessionInfo of all the Subreports will require a looping procedure
that goes through each Subreport and applies the Clear method.
fxampIc
This code clears the SessionInfo properties for the main Report (assuming the default state of Subreports[0]):
Crpe1.SessionInfo.Clear;
This code clears the SessionInfo properties for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SessionInfo.Clear;
end;
Scssiunlnfu CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeSessionInfo): boolean;
Dcscriptiun
The CopyFrom method copies the SessionInfo property values from another TCrpeSessionInfo object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the SessionInfo property values to a temporary TCrpeSessionInfo object:
var
tempSessionInfo : TCrpeSessionInfo;
begin
tempSessionInfo := TCrpeSessionInfo.Create;
tempSessionInfo.CopyFrom(Crpe1.SessionInfo);
{...later, when finished with the temp object...}
tempSessionInfo.Free;
end;
VCI Re|etetce 660
Scssiunlnfu Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the SessionInfo object. It is handy
for setting up loops to make similar changes to each item.
fxampIc
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.SessionInfo.Retrieve;
for cnt := 0 to (Crpe1.SessionInfo.Count - 1) do
begin
Crpe1.SessionInfo[cnt].UserID := 'Bond';
Crpe1.SessionInfo[cnt].UserPassword := '007';
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
Scssiunlnfu Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the SessionInfo object, and does not
need to be called in code.
VCI Re|etetce 616
Scssiunlnfu DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the SessionInfo object. The "nIndex" parameter
represents the number of the item in the SessionInfo object.
fxampIc
The Delete method can be used to manually remove an item from the SessionInfo object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Table Number - must be same as in Report}
Crpe1.SessionInfo.Add(0);
Crpe1.SessionInfo.UserID := 'Bond';
Crpe1.SessionInfo.UserPassword := '007';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.SessionInfo.Delete(0);
Scssiunlnfu Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
Scssiunlnfu Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
VCI Re|etetce 611
Dcscriptiun
The Retrieve method obtains the SessionInfo information from the Report and stores it in the SessionInfo
object. If no SessionInfo information was found, the call returns False. Be aware that calling Retrieve will first
cause the SessionInfo object to be cleared, so any current information stored in it will be removed.
NO7F: Snce lhe SessonInlo objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe SessonInlo lor
lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl lo oblan lhe
SessonInlo nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle lhrough lhe Subreorls
objecl and call Relreve lor each lem. 7he VCI wll slore searale SessonInlo nlormalon lor each Subreorl.
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SessionInfo.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SessionInfo.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
Scssiunlnfu Scnd mcthud
DccIaratiun
function Send: bololean;
Dcscriptiun
The Send method sends the SessionInfo 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.
VCI Re|etetce 612
fxampIc
In this example, the SessionInfo settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.SessionInfo.Send;
SurtFicIds Prupcrtics
SurtFicIds DcIctcSF prupcrty
DccIaratiun
property DeleteSF: boolean;
Dcscriptiun
The DeleteSF property can be used to remove a SortField from a Report. The SortField is not actually removed
from the Report until the Execute method is called. After Execute is called, the SortField is also removed from
the VCL.
NO7F: DeleleSF s nol lhe same as Delele. Delele removes a SorlFeld lem lrom lhe SorlFelds objecl, nol
lrom lhe Reorl.
fxampIc
This example will remove the second SortField from a Report when that Report is run:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SortFields.Retrieve;
Crpe1.SortFields[1].DeleteSF := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
SurtFicIds Dircctiun prupcrty
DccIaratiun
property Direction: TCrSortDirection;
Typc
TCrSortDirection = (sdDescending, sdAscending, sdDefault);
VCI Re|etetce 61!
Dcscriptiun
The Direction property determines the Sort Order, which can either be sdDescending (9..0, Z..A), sdAscending
(0..9, A..Z), or sdDefault (no change).
fxampIc
This example changes the Sort Order of the first SortField to ascending:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SortFields.Retrieve;
Crpe1.SortFields[0].Direction := sdAscending;
Crpe1.Output := toWindow;
Crpe1.Execute;
SurtFicIds FicId prupcrty
DccIaratiun
property Field: string;
Dcscriptiun
The Field property specifies the field that will control sorting. Sort fields can be database fields or formula
fields.
G Enclose field names in braces: {company.STATE}.
G If a formula field is specified, use the @ sign before the formula name: {@FormulaName}.
fxampIc
This example changes the second SortField to be sorted on a formula field called FormulaOne:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SortFields.Retrieve;
Crpe1.SortFields[1].Field := '{@FormulaOne}';
Crpe1.Output := toWindow;
Crpe1.Execute;
SurtFicIds ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeSortFields;
VCI Re|etetce 614
Dcscriptiun
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.
G 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].
G Item returns a reference to itself, so the SortFields properties can be used right after the subscript:
SortFields[2].Field := '{company.STATE}';
fxampIc
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];
SurtFicIds ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
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.
VCI Re|etetce 61S
fxampIc
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];
SurtFicIds Numbcr prupcrty
DccIaratiun
property Number: TCrSortFieldsNumber;
Dcscriptiun
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.
fxampIc
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;
SurtFicIds Mcthuds
SurtFicIds Add mcthud
DccIaratiun
procedure Add(SortFieldNumber: TCrSortFieldsNumber);
VCI Re|etetce 616
Typc
TCrSortFieldsNumber = integer;
Dcscriptiun
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:
1 Add an item to the SortFields object (you must specify the SortField number).
2 Fill the item's properties (Direction, Field, etc.) with values.
3 When 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.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
SorlFeld numbers are correcl lor lhe currenl Reorl. However, lor addng new SorlFelds lhal are nol
currenlly n lhe Reorl, lhe Add melhod musl be used. When usng Add n lhs way, lhe SorlFeld number
secled musl be one grealer lhan lhe hghesl SorlFeld number currenlly n lhe Reorl (or one hgher lhan
lhe SorlFeld number n lhe VCI l more lhan one SorlFeld s beng added).
fxampIc
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
VCI Re|etetce 617
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;
SurtFicIds CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
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.
VCI Re|etetce 618
fxampIc
This code clears the SortFields properties for the main Report (assuming the default state of Subreports[0]):
Crpe1.SortFields.Clear;
This code clears the SortFields properties for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SortFields.Clear;
end;
SurtFicIds CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeSortFields): boolean;
Dcscriptiun
The CopyFrom method copies the SortFields property values from another TCrpeSortFields object. It is similar
to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the SortFields property values to a temporary TCrpeSortFields object:
var
tempSortFields : TCrpeSortFields;
begin
tempSortFields := TCrpeSortFields.Create;
tempSortFields.CopyFrom(Crpe1.SortFields);
{...later, when finished with the temp object...}
tempSortFields.Free;
end;
SurtFicIds Cuunt mcthud
DccIaratiun
function Count: integer;
VCI Re|etetce 610
Dcscriptiun
The Count method can be used to obtain the number of items currently in the SortFields object. It is handy for
setting up loops to make similar changes to each item.
fxampIc
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.SortFields.Retrieve;
for cnt := 0 to (Crpe1.SortFields.Count - 1) do
Crpe1.SortFields[cnt].Direction := sdDescending;
end;
SurtFicIds Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the SortFields object, and does not
need to be called in code.
SurtFicIds DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the SortFields object. The "nIndex" parameter
represents the number of the item in the SortFields object, which may not be the same as the SortFields
Number value.
NO7F: Delele wll nol remove lhe SorlFeld lrom lhe Reorl, l wll jusl remove l lrom lhe Cryslal VCI. Sel
lhe DeleleSF roerly lo remove a SorlFeld lrom lhe Reorl.
VCI Re|etetce 626
fxampIc
The Delete method can be used to manually remove an item from the SortFields object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify SortField Number}
Crpe1.SortFields.Add(0);
Crpe1.SortFields.Field := '{company.STATE}';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.SortFields.Delete(0);
SurtFicIds Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
SurtFicIds Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the SortFields from the Report and stores them in the SortFields object. If no
SortFields were found, the call returns False. Be aware that calling Retrieve will first cause the SortFields object
to be cleared, so any current information stored in it will be removed.
NO7F: Snce lhe SorlFelds objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe SorlFelds
lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl lo oblan
lhe SorlFelds nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle lhrough lhe
Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale SorlFelds nlormalon lor each
Subreorl (see Fxamle).
VCI Re|etetce 621
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SortFields.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SortFields.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
SurtFicIds Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the SortFields 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.
fxampIc
In this example, the SortFields settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.SortFields.Send;
VCI Re|etetce 622
SQl Prupcrtics
SQl fxprcssiuns prupcrty
DccIaratiun
property Expressions : TCrpeSQLExpressions;
Typc
TCrpeSQLExpressions = class(TPersistent)
Dcscriptiun
Only available with SCR 7 and higher. The Expressions object contains all the properties that apply to SQL
Expressions in a Report.
G The Name property specifies the Name of the Expression.
G The Expression property holds the Expression text.
G The default array property Item, and the ItemIndex property, can be used to navigate through the
various Expressions that may be stored in the Expressions object.
G Expressions may be retrieved from the Report via the Retrieve method.
G The Add / Delete methods can be used instead of Retrieve/Clear to manually add and remove items in
the Expressions object.
G The Check method provides an easy way of checking the syntax of the Expression text before running
the Report.
SQL Expressions are similar to Crystal Reports Formulas, except that they use SQL syntax, and are processed
on the Server (whenever possible).
fxampIc
The following code retrieves the Expressions from a Report, and sets the first one:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Expressions.Retrieve;
{Assign a new expression to the Expression property}
Crpe1.SQL.Expressions[0].Expression.Text := '{fn RTRIM(company.`name`)}';
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 62!
SQl fxprcssiuns fxprcssiun prupcrty
DccIaratiun
property Expression: TCrpeString;
Typc
TCrpeString = class(TStringList)
Dcscriptiun
The Expression property contains the actual text of the Expression. To assign a new value to the Expression
property, any of the following methods can be used (or any other method that is valid for a StringList):
1. Crpe1.SQL.Expressions.Expression.Assign('{fn UCASE(table.`lastname`)}');
2. Crpe1.SQL.Expressions.Expression.Text := '{fn UCASE(table.`lastname`)}';
3. Crpe1.SQL.Expressions.Expression.Clear;
Crpe1.SQL.Expressions.Expression[0] := '{fn UCASE(table.`lastname`)}';
4. Crpe1.SQL.Expressions.Expression.SetText(PChar('{fn UCASE(table.`lastname`)}'));
G The new Expression string must conform to SQL syntax requirements.
fxampIc
The following code shows how the Expression property is used to store a new expression:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Expressions.Retrieve;
Crpe1.SQL.Expressions[0].Expression.Assign('{fn
UCASE(employee.`lastname`)}');
Crpe1.Output := toWindow;
Crpe1.Execute;
SQl fxprcssiuns ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeSQLExpressions;
VCI Re|etetce 624
Dcscriptiun
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 various items stored in the Expressions object, allowing the
object to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript:
Expressions[2] is the same as Expressions.Item[2].
G Item returns a reference to itself, so the Expressions properties can be used right after the subscript:
Expressions[2].Name := 'Expression1';
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Expressions.Retrieve;
{Set Expressions to the 3rd Expression}
Crpe1.SQL.Expressions.Item[2];
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Expressions.Retrieve;
{Set Expressions to the 3rd Expression}
Crpe1.SQL.Expressions[2];
SQl fxprcssiuns ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current Expressions item number, or
set the Expressions 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 (Expressions[2], for example), or whenever the key property (if applicable)
is assigned a new lookup value (key properties are things like Expressions.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.
VCI Re|etetce 62S
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the Expressions object is
pointing to the first Expression:
if Crpe1.SQL.Expressions.ItemIndex <> 0 then
Crpe1.SQL.Expressions[0];
SQl fxprcssiuns Namc prupcrty
DccIaratiun
property Name: TCrExpressionName;
Typc
TCrExpressionName = string;
Dcscriptiun
The Name property specifies the Name of the Expression. It is a key property, and therefore serves as a lookup;
that is, assigning it a value will cause the Expressions object to point to the item that has a Expression Name
with the same value. Before using the Name property to navigate through the Expressions, the Retrieve
method should be called, or the manual Add method.
G The % sign is not used when designating an Expression name in this property.
G This property cannot be used to create new Expressions. Only Expressions that already exist in the
Report can be specified.
fxampIc
The following code uses the Expression Name property to point the Expressions object to the specified
expression. It then assigns a new expression text to the Expression property:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Expressions.Retrieve;
{Set the Expressions object to the "Expression One" item}
Crpe1.SQL.Expressions.Name := 'Expression One';
{Assign a new expression to the Expression property}
Crpe1.SQL.Expressions.Expression.Text := '{fn RTRIM(company.`name`)}';
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 626
SQl fxprcssiuns Add mcthud
DccIaratiun
procedure Add(ExpressionName: TCrExpressionName);
Typc
TCrExpressionName = string;
Dcscriptiun
The Add method manually adds an item to the Expressions object and sets the internal index to that item. It
requires an Expression name as a parameter, which should be a name corresponding to an Expression already
created in the Report.
The steps to using the Add method with Expressions are:
1 Add an item to the Expressions object (you must specify the Expression Name).
2 Fill the item's Expression property with a value.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
Fxresson names are correcl lor lhe currenl Reorl.
fxampIc
The Add method can be used to manually add an item to the Expressions object, instead of using Retrieve:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Expression Name - must be same as in Report}
Crpe1.SQL.Expressions.Add('Expression1');
Crpe1.SQL.Expressions.Expression.Text := '{fn UCASE(employee.`lastname`)}';
Crpe1.Output := toWindow;
Crpe1.Execute;
SQl fxprcssiuns Chcck mcthud
DccIaratiun
function Check: boolean;
VCI Re|etetce 627
Dcscriptiun
The Check method can be used to check the syntax of an Expression before running the Report. Check returns
a boolean value:
True :Expression is good.
False :Expression has an error.
fxampIc
The following code loops through all the Expressions, checking each one:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Expressions.Retrieve;
for cnt := 0 to (Crpe1.SQL.Expressions.Count - 1) do
begin
if not Crpe1.SQL.Expressions[cnt].Check then
ShowMessage('Error in Expression #' + IntToStr(cnt));
end;
end;
SQl fxprcssiuns CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the Expressions 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 Expressions object of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the Expressions of all the Subreports will require a looping procedure
that goes through each Subreport and applies the Clear method.
fxampIc
This code clears the Expressions for the main Report (assuming the default state of Subreports[0]):
Crpe1.SQL.Expressions.Clear;
VCI Re|etetce 628
This code clears the Expressions for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SQL.Expressions.Clear;
end;
SQl fxprcssiuns CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeSQLExpressions): boolean;
Dcscriptiun
The CopyFrom method copies the Expressions property values from another TCrpeSQLExpressions object. It
is similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the Expressions property values to a temporary TCrpeSQLExpressions
object:
var
tempExpressions : TCrpeSQLExpressions;
begin
tempExpressions := TCrpeSQLExpressions.Create;
tempExpressions.CopyFrom(Crpe1.SQL.Expressions);
{...later, when finished with the temp object...}
tempExpressions.Free;
end;
SQl fxprcssiuns Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the Expressions object. It is handy
for setting up loops to make similar changes to each item.
VCI Re|etetce 620
fxampIc
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.SQL.Expressions.Retrieve;
for cnt := 0 to (Crpe1.SQL.Expressions.Count - 1) do
begin
if not Crpe1.SQL.Expressions[cnt].Check then
ShowMessage('Error in Expression: ' + IntToStr(cnt));
end;
end;
SQl fxprcssiuns Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the Expressions object, and does not need
to be called in code, unless you are using the CopyFrom method to store Expressions data to a temporary object:
var
tempExpressions : TCrpeSQLExpressions;
begin
tempExpressions := TCrpeSQLExpressions.Create;
tempExpressions.CopyFrom(Crpe1.SQL.Expressions);
end;
SQl fxprcssiuns DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the Expressions object. The "nIndex" parameter
represents the order of the item in the Expressions object.
VCI Re|etetce 6!6
fxampIc
The Delete method can be used to manually remove an item from the Expressions object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Expression Name - must be same as in Report}
Crpe1.SQL.Expressions.Add('Expression1');
Crpe1.SQL.Expressions.Expression.Text := '{fn UCASE(employee.`lastname`)}';
Crpe1.Output := toWindow;
Crpe1.Execute;
{Specify the item number}
Crpe1.SQL.Expressions.Delete(0);
SQl fxprcssiuns Dcstruy mcthud
DccIaratiun
destructor Destroy;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
SQl fxprcssiuns lndcxOf mcthud
DccIaratiun
function IndexOf(ExpressionName: TCrExpressionName): integer;
Typc
TCrExpressionName = string;
Dcscriptiun
The IndexOf method takes an Expression name and returns the index position of the Expression item in the
current Expressions object.
VCI Re|etetce 6!1
After the Retrieve method has been called, the Expressions object contains one item for each Expression in the
Report. The IndexOf method can be used to determine if a given Expression Name actually exists in the
Expressions object before trying to access it.
fxampIc
The following code illustrates the use of the IndexOf method to locate a specific Expression item by it's name:
var
nItem: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Expressions.Retrieve;
{Find a specific Expression}
nItem := Crpe1.SQL.Expressions.IndexOf('Expression1');
{If it exists, change the Expression}
if nItem > -1 then
Crpe1.SQL.Expressions[nItem].Expression.Text := '{fn
UCASE(employee.`lastname`)}';
Crpe1.Output := toWindow;
Crpe1.Execute;
end;
SQl fxprcssiuns Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the SQL Expressions information from the Report and stores it in the Expressions
object. If no Expressions information was found, the call returns False. Be aware that calling Retrieve will first
cause the Expressions object to be cleared, so any current information stored in it will be removed.
NO7F: Snce lhe Fxressons objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe Fxressons
lor lhe Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl lo oblan
lhe Fxressons nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle lhrough lhe
Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale Fxressons nlormalon lor each
Subreorl (see Fxamle).
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Expressions.Retrieve;
VCI Re|etetce 6!2
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SQL.Expressions.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
SQl fxprcssiuns Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the Expressions 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.
fxampIc
In this example, the Expressions settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.SQL.Expressions.Send;
SQl Params prupcrty
DccIaratiun
property Params: TCrpeStoredProcParams;
VCI Re|etetce 6!!
Typc
TCrpeStoredProcParams = class(TPersistent)
Dcscriptiun
NO7F: For SCR 7, Params are now handled lhrough lhe ParamFelds objecl.
The Params object is a member of the SQL object, and contains all the properties that relate to Stored Procedure
Parameters.
G The Name property specifies the name of the Parameter.
G The Value property specifies the actual value to be passed into the Stored Procedure Parameter. To set a
parameter value for the Stored Procedure to NULL, pass the string constant 'CRWNull' to the Value
property.
G The ParamType property is a read-only property that contains the data type of the Parameter.
G The Number property, or the default array property, Item, or the ItemIndex property can be used to
navigate through the various Parameters stored in the Params object.
G The Retrieve method can be used to get the Params from a Report.
G The Count method will indicate how many Parameters are in the Params object.
All Parameter values are stored as string values. To pass a numeric value to the Value property directly, pass
the value in quotes like this: '100'. The Crystal Reports Print Engine will treat this as the value 100. To pass
other types, either convert them to a string representation, or use one of the properties that can read and write
to the Value property using native Delphi types:
AsInteger
AsFloat
AsBoolean
AsDate
NO7F: When assng Boolean aramelers, beller resulls wll be acheved by usng 1 or 0 nslead ol 7rue or
False. 7he AsBoolean roerly already does lhs, so l s only necessary lo kee n mnd l you are wrlng
dreclly lo lhe Value roerly.
fxampIc
In the code following, the Stored Procedure Parameters are first retrieved, then the first and second Params
are passed new values:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Params.Retrieve;
Crpe1.SQL.Params[0].Value := '100';
Crpe1.SQL.Params[1].Value := '200';
Crpe1.Execute;
VCI Re|etetce 6!4
SQl Params AsBuuIcan prupcrty
DccIaratiun
property AsBoolean: boolean;
Dcscriptiun
The AsBoolean property can be used to read and write to the Value property using native Delphi boolean
values instead of the string values normally required by Value.
fxampIc
This example uses the AsBoolean property to pass in a native Delphi boolean value as the first parameter value
to the Stored Procedure the Report is based on:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Params.Retrieve;
Crpe1.SQL.Params[0].AsBoolean := True;
Crpe1.Execute;
SQl Params AsDatc prupcrty
DccIaratiun
property AsDate: TDateTime;
Dcscriptiun
The AsDate property can be used to read and write to the Value property using native Delphi DateTime values
instead of the string values normally required by Value.
G When reading this property, only the Date part of the Value string will be included in the result
returned.
G When writing this property, only the Date part of the TDateTime passed to it will be formatted in the
Value string.
NO7F: Mosl Slored Procedure Paramelers lhal nvolve dales are read by lhe Prnl Fngne as a lormalled dale/
lme slrng: 1999-01-01 00:00:00.000. When sendng lhe Param values back lo lhe Fngne, l lhe lme arl s
nol ncluded, even lhough l may nol be used by lhe Slored Procedure, an error wll resull. When n doubl,
nsecl lhe lormal ol lhe Value roerly aller callng lhe Relreve melhod, and lhe execled lormal wll be
dslayed. Il l ncludes lhe lme, use lhe AsDale7me roerly nslead ol AsDale.
VCI Re|etetce 6!S
fxampIc
This example uses the AsDate property to pass in a native Delphi datetime value as the first parameter value
to the Stored Procedure the Report is based on:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Params.Retrieve;
Crpe1.SQL.Params[0].AsDate := Now;
Crpe1.Execute;
SQl Params AsDatcTimc prupcrty
DccIaratiun
property AsDateTime: TDateTime;
Dcscriptiun
The AsDateTime property can be used to read and write to the Value property using native Delphi datetime
values instead of the string values normally required by Value.
G When reading this property, both the Date and Time portions of the Value string will be included in the
result returned.
G When writing this property, both the Date and Time portions of the TDateTime passed in will be
formatted in the Value string.
fxampIc
This example uses the AsDateTime property to pass in a native Delphi datetime value as the first parameter
value to the Stored Procedure the Report is based on:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Params.Retrieve;
Crpe1.SQL.Params[0].AsDateTime := Now;
Crpe1.Execute;
SQl Params AsFIuat prupcrty
DccIaratiun
property AsFloat: double;
VCI Re|etetce 6!6
Dcscriptiun
The AsFloat property can be used to read and write to the Value property using native Delphi floating point
values instead of the string values normally required by Value.
fxampIc
This example uses the AsFloat property to pass in a native Delphi floating point value as the first parameter
value to the Stored Procedure the Report is based on:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Params.Retrieve;
Crpe1.SQL.Params[0].AsFloat := 1.22;
Crpe1.Execute;
SQl Params Aslntcgcr prupcrty
DccIaratiun
property AsInteger: integer;
Dcscriptiun
The AsInteger property can be used to read and write to the Value property using native Delphi integer values
instead of the string values normally required by Value.
fxampIc
This example uses the AsInteger property to pass in a native Delphi integer value as the first parameter value
to the Stored Procedure the Report is based on:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Params.Retrieve;
Crpe1.SQL.Params[0].AsInteger := 1;
Crpe1.Execute;
SQl Params ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeStoredProcParams;
VCI Re|etetce 6!7
Dcscriptiun
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 Params object, allowing the object
to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript: Params[2] is the
same as Params.Item[2].
G Item returns a reference to itself, so the Params properties can be used right after the subscript:
Params[2].Value := '100';
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Params.Retrieve;
{Set Params object to the 3rd parameter}
Crpe1.SQL.Params.Item[2];
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Params.Retrieve;
{Set Params object to the 3rd parameter}
Crpe1.SQL.Params[2];
SQl Params ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current Params item number, or set the
Params 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 (Params[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.
VCI Re|etetce 6!8
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the Params object is pointing to
the first Params item:
if Crpe1.SQL.Params.ItemIndex <> 0 then
Crpe1.SQL.Params[0];
SQl Params Namc prupcrty
DccIaratiun
property Name: TCrStoredProcParamName;
Typc
TCrStoredProcParamName = string[128];
Dcscriptiun
The Name property is the key, or lookup property for the Params object. As such, it cannot be directly
overwritten with a new value. Instead, setting a new value to the Name property will cause it to navigate the
Params object to the matching item, or generate an error if the name does not exist. Before using the Name
property to navigate through the Params, the Retrieve method should be called, or the manual Add method.
fxampIc
This example illustrates the use of the Name property to navigate through the Params object:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Params.Retrieve;
{Set Params object to item 'FirstParam' name}
Crpe1.SQL.Params.Name := 'FirstParam';
{Set Params item Value}
Crpe1.SQL.Params.Value := 'CA';
Crpe1.Output := toWindow;
Crpe1.Execute;
Note that since there is an internal index in the Params object (and most of the other Crystal VCL sub-class
objects), it is not necessary to specify a subscript (i.e. Params[0].Value) every time a property is set. Once the
sub-class object is pointing to a certain item, the other properties apply to that item, whether the subscript is
specified or not.
VCI Re|etetce 6!0
SQl Params ParamTypc prupcrty
DccIaratiun
property ParamType: TCrStoredProcParamType;
Typc
TCrStoredProcParamType = (spLongVarChar, spBinary, spVarBinary,
spLongVarBinary, spBigInt, spTinyInt, spBit, spChar, spNumeric, spDecimal,
spInteger, spSmallInt, spFloat, spReal, spDouble, spDate, spTime, spTimeStamp,
spVarChar);
Dcscriptiun
ParamType is a read-only property that will only have a meaningful value if the Retrieve method is used to
obtain Params items from the Report. It indicates what data type the Value property is expecting.
NO7F: Il s nol ossble lo change lhe lye ol a Params lem al runlme. 7hs musl be done wlhn lhe Cryslal
Reorls desgner.
fxampIc
The ParamType property can be used to check the type of Value the Params item expects:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Params.Retrieve;
for cnt := 0 to (Crpe1.SQL.Params.Count - 1) do
begin
case Crpe1.SQL.Params[cnt].ParamType of
spLongVarChar : Crpe1.SQL.Params[cnt].Value := 'CA';
spBinary : Crpe1.SQL.Params[cnt].Value := '0'; {?}
spVarBinary : Crpe1.SQL.Params[cnt].Value := '10'; {?}
spLongVarBinary : Crpe1.SQL.Params[cnt].Value := '10'; {?}
spBigInt : Crpe1.SQL.Params[cnt].AsInteger := 1;
spTinyInt : Crpe1.SQL.Params[cnt].AsInteger := 1;
spBit : Crpe1.SQL.Params[cnt].AsNumber := 1; {?}
spChar : Crpe1.SQL.Params[cnt].Value := 'CA';
spNumeric : Crpe1.SQL.Params[cnt].AsInteger := 1;
spDecimal : Crpe1.SQL.Params[cnt].AsFloat := 1.23;
spInteger : Crpe1.SQL.Params[cnt].AsInteger := 1;
spSmallInt : Crpe1.SQL.Params[cnt].AsInteger := 1;
spFloat : Crpe1.SQL.Params[cnt].AsFloat := 1.23;
spReal : Crpe1.SQL.Params[cnt].AsFloat := 1.23;
VCI Re|etetce 646
spDouble : Crpe1.SQL.Params[cnt].AsFloat := 1.23;
spDate : Crpe1.SQL.Params[cnt].AsDate := Now;
spTime : Crpe1.SQL.Params[cnt].Value := '12:00:00.000';
spTimeStamp : Crpe1.SQL.Params[cnt].AsDate := Now;
spVarChar : Crpe1.SQL.Params[cnt].Value := 'CA';
end;
end;
Crpe1.Output := toWindow;
Crpe1.Execute;
SQl Params VaIuc prupcrty
DccIaratiun
property Value: string;
Dcscriptiun
The Value property contains the actual value of the Stored Procedure Parameter. If the Retrieve method was
called, the Value property will show the current value of the parameter(s) as stored in the Report.
All parameter values are stored as string values. If you wish to pass other types, they will either need to be
converted to a string representation, or you will need to use one of the four other properties that can be used
to read and write to the Text property using native Delphi types: AsInteger, AsFloat, AsBoolean, AsDate.
To pass a number to the Value property directly, pass the value in quotes like this: '100'. The Crystal Reports
Print Engine will treat this as the value 100. To pass it via the AsInteger property do this: Params.AsInteger :=
100.
If you want to set the parameter value for the Stored Procedure to NULL, pass the string constant 'CRWNull'
to the Value property.
fxampIc
The Value property is used to pass new values to a Stored Procedure Parameter:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Params.Retrieve;
for cnt := 0 to (Crpe1.SQL.Params.Count - 1) do
Crpe1.SQL.Params[cnt].Value := 'CA';
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 641
SQl Params Add mcthud
DccIaratiun
procedure Add(ParamNumber: TCrParamNumber);
Typc
TCrParamNumber = integer;
Dcscriptiun
The Add method adds an item to the Params object and sets the internal index to that item. It requires a Stored
Procedure Parameter number as a parameter, which should be a number corresponding to a Stored Procedure
Parameter in the Report. Stored Procedure Parameters are numbered starting from zero. If the Add method is
used, the steps to using Params are:
1 Add an item to the Params object (you must specify the Parameter number).
2 Fill the Value property.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
Parameler numbers are correcl lor lhe currenl Reorl.
fxampIc
The Add method can be used to manually add an item to the Params object, instead of using Retrieve:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Parameter Name - must be same as in Report}
Crpe1.SQL.Params.Add('Parameter1');
Crpe1.SQL.Params.Value := 'CA';
Crpe1.Output := toWindow;
Crpe1.Execute;
SQl Params CIcar mcthud
DccIaratiun
procedure Clear;
VCI Re|etetce 642
Dcscriptiun
This method can be used to clear the internal memory of the Params 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 Params object of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the Params of all the Subreports will require a looping procedure that
goes through each Subreport and applies the Clear method.
fxampIc
This code clears the Params properties for the main Report (assuming the default state of Subreports[0]):
Crpe1.SQL.Params.Clear;
This code clears the Params properties for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SQL.Params.Clear;
end;
SQl Params CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeStoredProcParams): boolean;
Dcscriptiun
The CopyFrom method copies the Params property values from another TCrpeStoredProcParams object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the Params property values to a temporary TCrpeStoredProcParams object:
var
tempParams : TCrpeStoredProcParams;
begin
tempParams := TCrpeStoredProcParams.Create;
tempParams.CopyFrom(Crpe1.SQL.Params);
{...later, when finished with the temp object...}
tempParams.Free;
end;
VCI Re|etetce 64!
SQl Params Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the Params object. It is handy for
setting up loops to make similar changes to each item.
fxampIc
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.SQL.Params.Retrieve;
for cnt := 0 to (Crpe1.SQL.Params.Count - 1) do
Crpe1.SQL.Params[cnt].Value := 'CA';
end;
SQl Params Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the Params object, and does not need
to be called in code.
SQl Params DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
VCI Re|etetce 644
Dcscriptiun
The Delete method can be used to remove an item from the Params object. The "nIndex" parameter represents
the number of the item in the Params object.
NO7F: Delele wll nol remove lhe Slored Procedure Paramelers lrom lhe Reorl, l wll jusl remove l lrom
lhe Cryslal VCI.
fxampIc
The Delete method can be used to manually remove an item from the Params object:
Crpe1.ReportName := 'C:\Company.rpt';
{Specify Parameter Name - must be same as in Report}
Crpe1.SQL.Params.Add('Parameter1');
Crpe1.SQL.Params.Value := 'CA';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.SQL.Params.Delete(0);
SQl Params Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
SQl Params Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the Stored Procedure Parameter information from the Report and adds one item
to the Params object for each Stored Procedure Parameter in the Report. If Stored Procedure Parameters were
not found, the call returns False. Be aware that calling Retrieve will first cause the Params object to be cleared,
so any current information stored in it will be removed.
VCI Re|etetce 64S
NO7F: Snce lhe Params objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe Params lor lhe
Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl lo oblan lhe
Params nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle lhrough lhe
Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale Params nlormalon lor each
Subreorl (see Fxamle).
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Params.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SQL.Params.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
SQl Params Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the Params 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.
VCI Re|etetce 646
fxampIc
In this example, the Params settings are sent from the Crystal component to the Crystal Reports Print Engine
DLL. This is normally handled automatically in the Execute method:
Crpe1.SQL.Params.Send;
SQl Qucry prupcrty
DccIaratiun
property Query: TCrpeString;
Typc
TCrpeString = class(TStringList)
Dcscriptiun
The Query property is used to retrieve and send the SQL Query statement used by a specified Report. This
will only be available if the Report is based off SQL databases, or ODBC Data Sources. Query does not apply
to PC-type databases (dBase, FoxPro, Access, Paradox, etc.) using native drivers.
The SELECT part of the Query cannot be changed, since it is determined by the fields that are placed in the
Report. Although the property requires that the entire SQL Query statement be entered, the SELECT section
must not be different from the original Query. If an ORDER BY clause will be included, it must be preceded
with CHR(13) and CHR(10) (carriage return/line feed).
NO7F: Cryslal Reorls wll alleml lo lranslale any Seleclon lormula and SorlFelds sorl order nlo lhe
WHFRF and ORDFR BY arls ol lhe SQI Query when lhe Reorl s run. For lhs reason, l may be easer lo
ass values nlo lhese roerles nslead ol modlyng lhe SQI Query dreclly. Conversely, modlyng lhe SQI
Query wll cause lhe Seleclon lormula n a Reorl lo be removed when lhe Reorl s run.
fxampIc
The following example uses the Query property to pass a new SQL statement to the Report:
Crpe1.ReportName := 'C:\Company.rpt';
{Set the LogOn}
Crpe1.Connect.Retrieve;
Crpe1.Password := 'Aesop';
{Set the SQL Query}
Crpe1.SQL.Query[0] := 'SELECT DEPT."DEPTNO", DEPT."DNAME", DEPT."LOC"';
Crpe1.SQL.Query[1] := 'FROM "SCOTT"."DEPT" DEPT';
Crpe1.SQL.Query[2] := 'WHERE DEPT."DEPTNO" = 10';
Crpe1.SQL.Query[3] := 'ORDER BY DEPT."DNAME" ASC';
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 647
SQl Mcthuds
SQl CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the Query property of the SQL object. It is the same as:
Crpe1.SQL.Query.Clear;
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 SQL Query of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the SQL Query of all the Subreports will require a looping procedure
that goes through each Subreport and applies the Clear method.
fxampIc
This code clears the SQL Query for the main Report (assuming the default state of Subreports[0]):
Crpe1.SQL.Clear;
This code clears the SQL Query for all the Subreports:
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SQL.Clear;
end;
SQl CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeSQL): boolean;
VCI Re|etetce 648
Dcscriptiun
The CopyFrom method copies the SQL property values from another TCrpeSQL object. It is similar to Delphi's
Assign method. It is useful for transferring or temporary storage of values.
NO7F: Al lhs lme, lhe CoyFrom lor SQI only coes lhe Query. Il you wanl lo coy Params, or Fxressons,
you wll have lo coy lhem searalely.
fxampIc
The following example copies all the SQL property values to a temporary TCrpeSQL object:
var
tempSQL : TCrpeSQL;
begin
tempSQL := TCrpeSQL.Create;
tempSQL.CopyFrom(Crpe1.SQL);
{...later, when finished with the temp object...}
tempSQL.Free;
end;
SQl Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the SQL object, and does not need to
be called in code.
SQl Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
VCI Re|etetce 640
SQl Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the SQL Query information from the Report and stores it in the SQL.Query
property of the component. If an SQL Query was not found, or a connection could not be made to the SQL Server
(which is required to retrieve the Query), the call returns False. Be aware that calling Retrieve will first cause the
SQL .Query property in the VCL to be cleared, so any current information stored in it will be removed.
NO7F: Snce lhe SQI objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe SQIQuery lor lhe
Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl lo oblan lhe
SQIQuery nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle lhrough lhe
Subreorls objecl and call Relreve lor each lem. 7he VCI wll slore searale SQI.Query nlormalon lor each
Subreorl (see Fxamle).
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SQL.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.SQL.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
VCI Re|etetce 6S6
SQl Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the SQL 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.
fxampIc
In this example, the SQL settings are sent from the Crystal component to the Crystal Reports Print Engine DLL.
This is normally handled automatically in the Execute method:
Crpe1.SQL.Send;
Subrcpurts Prupcrtics
Subrcpurts ltcm prupcrty
DccIaratiun
property Item[nIndex: integer]: TCrpeSubreports;
Dcscriptiun
The Item property is a default array property. It's primary use is to navigate through the Subreport object,
allowing it to be treated as an array.
G Item is the default property, so it does not need to be specified, therefore this: Subreports.Item[2], is the
same as this: Subreports[2]. Both will point the properties of the Subreports object to the second
Subreport.
G Item returns a reference to itself, so the Subreports properties can be used right after the subscript:
ShowMessage(Subreports[2].Section);
VCI Re|etetce 6S1
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Subreports.Retrieve;
{Set Subreports object to the 2nd subreport}
Crpe1.Subreports.Item[2];
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Subreports.Retrieve;
{Set Subreports object to the 2nd subreport}
Crpe1.Subreports[2];
Subrcpurts ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
The ItemIndex property can be used to set the current Subreport, or to read which item the Subreport object
is currently set to.
fxampIc
This code sets the current Subreport to the first Subreport:
Crpe1.SubReports.ItemIndex := 1;
And this code shows which Subreport number is currently being accessed by the Subreports object:
ShowMessage(IntToStr(Crpe1.Subreports.ItemIndex));
The following code illustrates the use of the ItemIndex property to make sure the Subreports object is pointing
to the main Report:
if Crpe1.Subreports.ItemIndex <> 0 then
Crpe1.Subreports[0];
Subrcpurts Namc prupcrty
DccIaratiun
property Name: TCrSubreportName;
VCI Re|etetce 6S2
Typc
TCrSubreportName = string;
Dcscriptiun
The Name property is the key property for the Subreports sub-class. It contains the Name of the Report/
Subreport. For the main Report, this property contains an empty string. It is a look-up property and therefore
primarily serves to provide a way to navigate through the Subreports items by specifying a Subreport Name.
However, in most cases it will be easier to navigate using the default Item or the ItemIndex properties.
When the Name property is assigned a new value, those properties and sub-classes on the Crystal VCL that
can apply to Subreports (such as Selection, GroupSelection, SectionFormat, SQLQuery, etc.), will be updated
to look at the particular Subreport specified.
G If the Retrieve method is used, the Name property is automatically filled for each Subreports item that is
retrieved.
G The Add and Delete methods provide a manual method of adding/removing items from the Subreports
object in place of Retrieve/Clear.
fxampIc
The following code fills a list box with all the Subreport Names (we start the count with 1 to avoid the Main
Report):
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
ListBox1.Items.Add(Crpe1.Subreports[cnt].Name);
The following code shows how to use the Name property to cause the Subreports object to point to the main
Report, after accessing a Subreport:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
Crpe1.Subreports[1];
Crpe1.Tables.Retrieve;
Crpe1.Tables[0].Name := 'sales.dbf';
{This line points the VCL back to the main Report}
Crpe1.Subreports.Name := '';
Note that in the above example, the same effect can be achieved by this:
{This line points the VCL back to the main Report}
Crpe1.Subreports[0];
VCI Re|etetce 6S!
Subrcpurts Nlinks prupcrty
DccIaratiun
property NLinks: integer;
Dcscriptiun
The NLinks property is a read-only property that reveals the number of Subreport Links that are active for the
current Subreport.
A Subreport that is linked to the main Report will accept a value from the main Report and select the Records
for that Subreport based on the value passed in from the main Report. Linked Subreports are normally used
in the Details or Group Header/Footer areas of a Report, to add or arrange specific details for a particular
record or group in the main Report. In this way, it is possible to format the details in the Subreport
independent of the formatting of the main Report.
fxampIc
The following code checks the NLinks property of a Subreport:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
ShowMessage('Subreport 1 has :' +
IntToStr(Crpe1.Subreports[1].NLinks) + ' Links');
Subrcpurts OnDcmand prupcrty
DccIaratiun
property OnDemand: boolean;
Dcscriptiun
The OnDemand property is a read-only property that reveals whether the current Subreport is set to be "On
Demand" or not. For further details about "On Demand" Subreports, consult the Seagate Crystal Reports Help File.
fxampIc
The following code checks the OnDemand property of a Subreport:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
if Crpe1.Subreports[1].OnDemand then
ShowMessage('Subreport 1 is OnDemand');
VCI Re|etetce 6S4
Subrcpurts Scctiun prupcrty
DccIaratiun
property Section: string;
Dcscriptiun
The Section property contains the Section name that the current Subreport is located in. For the main Report,
this property will be a blank string. It's primary use is to help locate Subreports in a Report, since there is no
easy way in the Crystal Reports designer to determine where all the Subreports are located.
If the Retrieve method is used, the Section property is automatically filled when the Subreports are retrieved.
The Section property is not used in the internal processing of the VCL so assigning it an new value will not
affect the execution of the Report (i.e., it is not possible to move a Subreport to a different section by assigning
a new value to the Section property).
The Section name syntax is the same as the Short Section Names used in the Crystal Reports Designer. See
About Section Names, Volume 1, Chapter 7, for more details on the syntax.
fxampIc
The following code fills a list box with all the Subreport Section codes:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
ListBox1.Items.Add(Crpe1.Subreports[cnt].Section);
Subrcpurts Subfxccutc prupcrty
DccIaratiun
property SubExecute: boolean;
Dcscriptiun
The SubExecute property determines whether Subreports can be run as individual reports or not. By default
this property is set to False.
If the SubExecute property is set to True, then when Crpe1.Execute is called, the current Report will be run.
The current Report is the Report that the Subreports object is currently pointing to (whatever was last specified
via the Item, ItemIndex, or Name properties). If this happens to be a Subreport, then the Subreport will run as
if it were a stand-alone Report.
If the SubExecute property is set to False, then when Crpe1.Execute is called, the main Report will always be
run (along with any associated Subreports), regardless of which Report the Subreports object is currently
pointing to.
VCI Re|etetce 6SS
Rcmarks
Bear in mind that if you set this property to True, and you want to run the main Report, you will need to make
sure that the Subreports object is pointing to the main Report before calling Crpe1.Execute, that is:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
Crpe1.SubReports[1]; {pointing to Subreport 1}
Crpe1.SubExecute := True;
Crpe1.SubReports[0]; {point to Main Report before Executing}
Crpe1.Execute; {Run the Main Report}
fxampIc
The following example will run the first Subreport as a separate Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
Crpe1.Subreports[1];
Crpe1.Subreports.SubExecute := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
The following example will run the main Report in spite of the fact that the Crystal Reports Component is
currently pointing to a Subreport:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
Crpe1.Subreports[1];
Crpe1.Subreports.SubExecute := False;
Crpe1.Execute;
Subrcpurts Mcthuds
Subrcpurts Add mcthud
DccIaratiun
procedure Add(SubName: TCrSubreportName);
Typc
TCrSubreportName = string;
VCI Re|etetce 6S6
Dcscriptiun
The Add and Delete methods provide a manual method of maintaining the Subreport items in the Subreports
object. We recommend that you use the Retrieve method instead as it is much easier and less error-prone. The
Add method adds an item to the Subreports object and sets the Subreports object index to that item. It requires
a valid Subreport name as a parameter.
NO7F: 7hs melhod wll nol add a Subreorl lo a Reorl; l only works on lhe VCIs nlernal dala arrays.
fxampIc
This example adds a new Subreport called MySubName to the Subreports object, and then runs the Subreport:
Crpe1.ReportName := 'C:\Report1.rpt';
{Specify Subreport Name - must be same as in Report}
Crpe1.Subreports.Add('SubRpt1');
Crpe1.Subreports.SubExecute := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
Subrcpurts CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
The Clear procedure removes any current Subreport information from the VCL. It does not clear the main
Report information. To Clear the main Report as well, use the CloseJob method of the TCrpe object:
Crpe1.CloseJob;
or change the ReportName property to a different value (which causes CloseJob to be called):
Crpe1.ReportName := 'C:\aNewReport.rpt';
To Clear the main Report and Subreport information, and all of the Window/Printer/Export properties as
well, use the Clear method of the TCrpe component:
Crpe1.Clear;
NO7F: Il s nol normally necessary lo call lhe Subreorls Clear melhod, snce lhs wll be called aulomalcally
when lhe ReorlName s changed.
VCI Re|etetce 6S7
fxampIc
This code sets the Subreport Selection Formula, runs the main Report, and then clears all the Subreport
information stored in the VCL component:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
Crpe1.Subreports[1];
Crpe1.Selection.Formula.Text := '{company.STATE} = "CA"';
Crpe1.Subreports[0];
Crpe1.Output := toWindow;
Crpe1.Execute;
{Clear the Subreport information from the VCL}
Crpe1.Subreports.Clear;
To clear properties for a specific Subreport only, use the Clear methods for those particular properties. This
example clears the Tables object for the second Subreport:
Crpe1.Subreports[2];
Crpe1.Tables.Clear;
Subrcpurts CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeSubreports): boolean;
Dcscriptiun
The CopyFrom method copies the Subreports sub-class property values to another TCrpeSubreports object. It
is similar to Delphi's Assign method. It is useful for temporary storage of values.
NO7F: 7hs melhod wll nol coy all ol lhe olher sub-classes ol nlormalon relalng lo a arlcular Subreorl,
such as Seleclon, 7ables, SorlFelds, elc. 7hese musl be done searalely, or va lhe CoyFrom melhod lor lhe
base 7Cre class.
fxampIc
The following example copies all the Subreports property values to a temporary TCrpeSubreports object:
var
tempSubreports : TCrpeSubreports;
begin
tempSubreports := TCrpeSubreports.Create;
tempSubreports.CopyFrom(Crpe1.Subreports);
{...later, when finished with the temp object...}
tempSubreports.Free;
end;
VCI Re|etetce 6S8
Subrcpurts Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
Count returns the number of Subreports. It includes the Main Report, and so a Count value of 1 means that there
is only one main Report and no Subreports. Likewise, Subreports[0] refers to the main Report. When dealing
with Subreports, be sure to call the Retrieve method before using Count. This will ensure a meaningful value.
fxampIc
The following code fills a list box with all the Subreport Names. The count is started with 1 since 0 refers to the
main Report:
Crpe1.Subreports.Retrieve;
for cnt := 1 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt1];
ListBox1.Items.Add(Crpe1.Subreports.Name);
end;
Subrcpurts Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create constructor creates the Subreports object. It is used internally in the VCL component to create the
Subreports object and should not be called outside of the component.
Subrcpurts DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
VCI Re|etetce 6S0
Dcscriptiun
The Add and Delete methods provide a manual method of maintaining the Subreport items in the Subreports
object of the VCL. We recommend that you use the Retrieve method instead as it is much easier and less error-
prone. The Delete method removes an item from the Subreports object. If that item was the currently selected
one, it sets the Subreports index to the previous item. It requires a valid Subreport item number as a parameter.
This method will not remove a Subreport from a Report; it only works on the VCL's internal data arrays.
fxampIc
This example adds a new Subreport called 'SubRpt1' to the Subreports object, runs the Subreport, and then
finally deletes the Subreport item from the Subreports object:
Crpe1.ReportName := 'C:\Report1.rpt';
{Specify Subreport Name - must be same as in Report}
Crpe1.Subreports.Add('SubRpt1');
Crpe1.Subreports.SubExecute := True;
Crpe1.Output := toWindow;
Crpe1.Execute;
{Delete the Subreport item from the VCL}
Crpe1.Subreports.Delete(1);
Subrcpurts Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method frees the Subreports object. It is used internally in the VCL component to destroy the
Subreports object and should not be called outside of the component.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
Subrcpurts lndcxOf mcthud
DccIaratiun
function IndexOf(SubName: TCrSubreportName): integer;
VCI Re|etetce 666
Typc
TCrSubreportName = string[128];
Dcscriptiun
The IndexOf method takes a Subreport name and returns the index position of the Subreport item in the
current Subreports object.
After the Retrieve method has been called, the Subreports object contains one item for each Subreport in the
Report. The IndexOf method can be used to determine if a given Subreport Name actually exists in the
Subreports object before trying to access it.
fxampIc
The following code illustrates the use of the IndexOf method to locate a specific Subreport item by it's name:
var
nItem: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Find a specific Subreport}
nItem := Crpe1.Subreports.IndexOf('SubreportOne');
{If it exists, retrieve the Formulas for that Subreport}
if nItem > -1 then
begin
with Crpe1.Subreports[nItem] do
Formulas.Retrieve;
end;
end;
Subrcpurts Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
Retrieve obtains Subreport information from a Report. It returns True if the call was successful, and False if it did
not find any Subreports. Retrieve will get the Name, and Section of each Subreport, and allocate memory to store
further Subreport details. It does not retrieve everything about a Subreport, such as Selection Formula, Section
Information, Table information, etc. These must all be retrieved individually using their associated objects.
VCI Re|etetce 661
If you intend to work with Subreports, then this method is the first one that should be called. After calling it, a loop
can be set up which will go through all the Reports and retrieve the desired data from each one (see Example).
NO7F: Relreve wll clear oul any currenl Subreorl nlormalon, so l should nol be called more lhan once
durng lhe rocess ol runnng a Reorl.
fxampIc
The following code illustrates the use of the Retrieve method for obtaining Subreport items, and then looping
through the Subreports to retrieve other information:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.Tables.Retrieve;
Crpe1.Selection.Retrieve;
Crpe1.SortFields.Retrieve;
Crpe1.GraphType.Retrieve;
end;
end;
Summarylnfu Prupcrtics
Summarylnfu AppNamc prupcrty
DccIaratiun
property AppName: TCrSummaryString;
Typc
TCrSummaryString = string[128];
Dcscriptiun
AppName is a Read-only, Run-time only property which indicates which application created the Report. This
property will only have a value if the Retrieve method is called beforehand.
VCI Re|etetce 662
fxampIc
This code sample retrieves the SummaryInfo from a Report and displays the AppName value:
Crpe1.ReportName := 'Company.rpt';
Crpe1.SummaryInfo.Retrieve;
ShowMessage(Crpe1.SummaryInfo.AppName);
Summarylnfu Authur prupcrty
DccIaratiun
property Author: TCrSummaryString;
Typc
TCrSummaryString = string[128];
Dcscriptiun
The Author property specifies the author of the current Report.
fxampIc
This code sample retrieves the SummaryInfo from a Report and displays the Author value:
Crpe1.ReportName := 'Company.rpt';
Crpe1.SummaryInfo.Retrieve;
ShowMessage(Crpe1.SummaryInfo.Author);
Summarylnfu Cummcnts prupcrty
DccIaratiun
property Comments: TCrpeString;
Typc
TCrpeString = class(TStringList)
Dcscriptiun
The Comments property specifies any comments for the current Report. The Comment strings should not be
longer than 512 characters, or an error will be generated (this is a Print Engine limitation at the moment).
VCI Re|etetce 66!
fxampIc
This code sample retrieves the SummaryInfo from a Report and displays the Comments value in a Memo:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.SummaryInfo.Retrieve;
Memo1.Lines.Assign(Crpe1.SummaryInfo.Comments);
Summarylnfu kcywurds prupcrty
DccIaratiun
property Keywords: TCrSummaryString;
Typc
TCrSummaryString = string[128];
Dcscriptiun
The Keywords property specifies the keywords included for the current report.
fxampIc
This code sample retrieves the SummaryInfo from a Report and displays the Keywords value:
Crpe1.ReportName := 'Company.rpt';
Crpe1.SummaryInfo.Retrieve;
ShowMessage(Crpe1.SummaryInfo.Keywords);
Summarylnfu Subjcct prupcrty
DccIaratiun
property Subject: TCrSummaryString;
Typc
TCrSummaryString = string[128];
Dcscriptiun
The Subject property specifies the subject of the current report.
VCI Re|etetce 664
fxampIc
This code sample retrieves the SummaryInfo from a Report and displays the Subject value:
Crpe1.ReportName := 'Company.rpt';
Crpe1.SummaryInfo.Retrieve;
ShowMessage(Crpe1.SummaryInfo.Subject);
Summarylnfu TcmpIatc prupcrty
DccIaratiun
property Template: TCrSummaryString;
Typc
TCrSummaryString = string[128];
Dcscriptiun
The Template property specifies the ReportTemplate for the current report.
fxampIc
This code sample retrieves the SummaryInfo from a Report and displays the Template value:
Crpe1.ReportName := 'Company.rpt';
Crpe1.SummaryInfo.Retrieve;
ShowMessage(Crpe1.SummaryInfo.Template);
Summarylnfu TitIc prupcrty
DccIaratiun
property Title: TCrSummaryString;
Typc
TCrSummaryString = string[128];
Dcscriptiun
The Title property specifies the Report Title of the current Report, and holds the same information as the
ReportTitle property, or the Report Title field in Crystal Reports Designer.
VCI Re|etetce 66S
fxampIc
This code sample retrieves the SummaryInfo from a Report and displays the Title value:
Crpe1.ReportName := 'Company.rpt';
Crpe1.SummaryInfo.Retrieve;
ShowMessage(Crpe1.SummaryInfo.Title);
Summarylnfu Mcthuds
Summarylnfu CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to set the SummaryInfo properties to their default values:
AppName := '';
Title := '';
Subject := '';
Author := '';
Keywords := '';
Comments.Clear;
Template := '';
It is called automatically if the Clear method is called for the main component, but may be called in code as
needed.
fxampIc
This line of code clears the SummaryInfo properties:
Crpe1.SummaryInfo.Clear;
Summarylnfu CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeSummaryInfo): boolean;
VCI Re|etetce 666
Dcscriptiun
The CopyFrom method copies the SummaryInfo property values from another TCrpeSummaryInfo object. It
is similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the SummaryInfo property values to a temporary TCrpeSummaryInfo
object:
var
tempSummaryInfo : TCrpeSummaryInfo;
begin
tempSummaryInfo := TCrpeSummaryInfo.Create;
tempSummaryInfo.CopyFrom(Crpe1.SummaryInfo);
{...later, when finished with the temp object...}
tempSummaryInfo.Free;
end;
Summarylnfu Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component and does not need to be called in code.
Summarylnfu Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
VCI Re|etetce 667
Summarylnfu Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the SummaryInfo information from the Report. SummaryInfo only applies to the
main Report, not to Subreports, and is only available with Crystal Reports 6 or higher. Returns True if the call
succeeded.
NO7F: Allemlng lo Relreve SummaryInlo lrom a Reorl where lhe Commenls are larger lhan S12
characlers can cause an error n lhe Prnl Fngne. 7hs s a known roblem (al lhe lme ol lhs wrlng), and
should be addressed n a lulure release (> 6.0).
fxampIc
This code sample retrieves the SummaryInfo from a Report:
Crpe1.ReportName := 'Company.rpt';
Crpe1.SummaryInfo.Retrieve;
Summarylnfu Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the SummaryInfo 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.
fxampIc
In this example, the SummaryInfo settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.SummaryInfo.Send;
VCI Re|etetce 668
TabIcs Prupcrtics
TabIcs DcscriptivcNamc prupcrty
DccIaratiun
property DescriptiveName: string;
Dcscriptiun
DescriptiveName is a read-only, run-time property which contains a description of the database driver being
used by Crystal Reports to connect to the Table, for example:
G xBase
G IDAPI Database DLL
G Oracle7 SQL
G ODBC - Interbase
This property goes along with TableType and DLLName to provide a complete description of the database
driver. These properties will only have values after the Retrieve method is called.
fxampIc
The following example illustrates the use of the DescriptiveName property:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the Tables}
Crpe1.Tables.Retrieve;
{Loop through Tables obtaining descriptive information}
for cnt := 0 to (Crpe1.Tables.Count - 1) do
begin
ListBox1.Items.Add(Crpe1.Tables[cnt].TableType);
ListBox2.Items.Add(Crpe1.Tables[cnt].DLLName);
ListBox3.Items.Add(Crpe1.Tables[cnt].DescriptiveName);
end;
TabIcs DllNamc prupcrty
DccIaratiun
property DLLName: string;
VCI Re|etetce 660
Dcscriptiun
DLLName is a read-only, run-time property which contains the name of the database driver being used by
Crystal Reports to connect to the Table, for example:
pdbxbse.dll
pdbbde.dll
pdsora7.dll
pdsodbc.dll
Note that the 16-bit naming convention is used, even though the DLL's may be 32-bit (P2BXBSE.DLL, etc.).
This property goes along with TableType and DescriptiveName to provide a complete description of the
database driver. These properties will only have values after the Retrieve method is called.
fxampIc
The following example illustrates the use of the DLLName property:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the Tables}
Crpe1.Tables.Retrieve;
{Loop through Tables obtaining descriptive information}
for cnt := 0 to (Crpe1.Tables.Count - 1) do
begin
ListBox1.Items.Add(Crpe1.Tables[cnt].TableType);
ListBox2.Items.Add(Crpe1.Tables[cnt].DLLName);
ListBox3.Items.Add(Crpe1.Tables[cnt].DescriptiveName);
end;
TabIcs ltcm prupcrty
DccIaratiun
property Item[const nIndex: integer]: TCrpeTables;
Dcscriptiun
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 various items stored in the Tables object, allowing the object
to be treated like an array.
G Item is a default property, so it does not need to be specified when using the subscript: Tables[2] is the
same as Tables.Item[2].
G Item returns a reference to itself, so the Tables properties can be used right after the subscript:
Tables[2].Name := 'MyTable.dbf';
VCI Re|etetce 676
fxampIc
Since Item is a default array property, the following two blocks of code do the same thing:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Tables.Retrieve;
{Set Tables object to the 3rd item}
Crpe1.Tables.Item[2];
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Tables.Retrieve;
{Set Tables object to the 3rd item}
Crpe1.Tables[2];
TabIcs ltcmlndcx prupcrty
DccIaratiun
property ItemIndex: integer;
Dcscriptiun
ItemIndex is a Run-time only property which can be used to obtain the current Tables item number, or set the
Tables 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 (Tables[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.
fxampIc
The following code illustrates the use of the ItemIndex property to make sure the Tables object is pointing to
the first Table:
if Crpe1.Tables.ItemIndex <> 0 then
Crpe1.Tables[0];
TabIcs Namc prupcrty
DccIaratiun
property Name: string;
VCI Re|etetce 671
Dcscriptiun
The Name property is the table name of the current Table, without the path. Note that the length of the Path
plus the Name should not exceed 256 characters (Print Engine limit).
fxampIc
The following example shows how to change the name of a Table:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Tables.Retrieve;
for cnt := 0 to (Crpe1.Tables.Count - 1) do
Crpe1.Tables[cnt].Name := 'MyNewName.dbf';
end;
TabIcs Numbcr prupcrty
DccIaratiun
property Number: TCrTableNumber;
Typc
TCrTableNumber = integer;
Dcscriptiun
The Number property contains the number of the Table in the Report. It uses a zero-based numbering scheme,
so the first Table in a Report is number 0. The Number property is the key lookup property for the Tables object
and therefore cannot be changed by direct assignment. For example:
Crpe1.Tables.Number := 2;
will cause the Tables object to look up and move to the second table in the Report. It will not overwrite the
current Table with a new Table number.
fxampIc
This example demonstrates the use of the Number property to point to a specific Table:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Tables.Retrieve;
{Go to Table number 2}
Crpe1.Tables.Number := 2;
{Change the Path for that Table}
Crpe1.Tables.Path := 'C:\NewPath\';
Crpe1.Execute;
VCI Re|etetce 672
TabIcs Passwurd prupcrty
DccIaratiun
property Password: string;
Dcscriptiun
The Password property applies to Paradox password-protected tables. For MS Access password-protected
Tables, use the SessionInfo object instead of the Password property of the Tables object.
fxampIc
The code below shows how to use the Password property of the Tables object:
Crpe1.ReportName := 'C:\ParadoxTable.rpt';
Crpe1.Tables.Retrieve;
Crpe1.Tables[0].Password := 'SwornToSecrecy';
Crpe1.Execute;
TabIcs Path prupcrty
DccIaratiun
property Path: string;
Dcscriptiun
The Path property is the path of the current Table. If the current table is:
'c:\mydir\table1.dbf'
the Path would be:
'c:\mydir\'
A BDE Alias can also be passed to this property to assign the Table a new path:
Crpe1.Tables.Path := ':MyAlias:';
The Propagate property causes the Path of the first Table to be used for all the Tables in the main Report and
all Subreports as well. If Propagate is set to True on a Tables object that belongs to a Subreport, then only the
Tables of that Subreport will use the same path as the first Table of the main Report.
Note that Retrieve or Add have to be called first to fill the Tables object with Table items.
The length of the Path plus the Name should not exceed 256 characters (Print Engine limit).
VCI Re|etetce 67!
fxampIc
The following code changes the Path of the second Table:
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Tables.Retrieve;
Crpe1.Tables[1].Path := 'c:\MyNewDir\';
Crpe1.Execute;
The following code changes the Path of the first Table to a BDE Alias called 'MyAlias':
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Tables.Retrieve;
Crpe1.Tables[0].Path := ':MyAlias:';
Crpe1.Execute;
The following code changes the Path of the first Table and causes the change to be used for all the Tables in
the main Report and any Subreports:
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Tables.Retrieve;
Crpe1.Tables[0].Path := 'C:\MyNewDir\';
Crpe1.Tables.Propagate := True;
Crpe1.Execute;
The following code loops through all Tables in the first Subreport and changes the paths:
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Subreports.Retrieve;
Crpe1.Subreports[1];
Crpe1.Tables.Retrieve;
for cnt := 0 to (Crpe1.Tables.Count - 1) do
Crpe1.Tables[cnt].Path := 'c:\MyNewDir\';
TabIcs Prupagatc prupcrty
DccIaratiun
property Propagate: boolean;
Dcscriptiun
In the previous versions of the Crystal VCL, there was a property called "DatafilesLocation" which allowed the
programmer to pass in a directory path that would be used for all the Tables in the Report, including any
Subreports. This functionality has been included in the Tables object by the inclusion of the Propagate property.
VCI Re|etetce 674
If this property is set to True, then the path of the first Table in the main Report will be used for the paths of
all other Tables. If the Propagate property of the Tables object is set to True for a Subreport, then that Subreport
will use the path from the first Table of the main Report for all of the paths of it's Tables. This will not affect
the Table paths of the other Subreports. Setting the Propagate flag in the main Report, however, will affect the
Table paths in all the Subreports (see the Example).
fxampIc
If the Propagate property is set to True for the main Report, then the path of the first Table in the main Report
will be used for the paths of all other Tables in the main Report, and any Subreports also:
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Tables.Retrieve;
{Set Path of first Table}
Crpe1.Tables[0].Path := 'c:\MyNewPath\';
Crpe1.Tables.Propagate := True;
If the Propagate property of a Subreport Tables object is set to True, then the Tables for that Subreport will use
the path from the first Table of the main Report for all of their paths:
Crpe1.ReportName := 'C:\Report1.rpt';
Crpe1.Tables.Retrieve;
{Sets VCL to Subreport 1}
Crpe1.Subreports[1];
{Sets Propagate flag for Subreport 1 Tables}
Crpe1.Tables.Propagate := True;
In the above example, setting the Propagate flag for a Subreport, will cause that Subreport to get it's Table Path
information from the first Table in the main Report. It will not affect the Table Paths of the other Subreports.
Setting the Propagate flag in the main Report, however, will affect the Tables in all the Subreports.
TabIcs TabIcTypc prupcrty
DccIaratiun
property TableType: TCrTableType;
Typc
TCrTableType = (ttUnknown, ttStandard, ttSQL);
VCI Re|etetce 67S
Dcscriptiun
TableType is a read-only, run-time property which contains the type of the database driver being used by
Crystal Reports to connect to the Table. TableType will be one of the following:
G ttSQL - The Table is an SQL-type table, or a Table being accessed via ODBC.
G ttStandard - The Table is a PC-Type database (dBase, FoxPro, Access, Paradox, etc.) using native
database connections (that is, not via ODBC).
G ttUnknown - The TableType could not be identified.
This property goes along with DLLName and DescriptiveName to provide a complete description of the
database driver. These properties will only have values after the Retrieve method is called.
fxampIc
The following example illustrates the use of the TableType property:
Crpe1.ReportName := 'C:\Company.rpt';
{Retrieve the Tables}
Crpe1.Tables.Retrieve;
{Loop through Tables obtaining descriptive information}
for cnt := 0 to (Crpe1.Tables.Count - 1) do
begin
ListBox1.Items.Add(Crpe1.Tables[cnt].TableType);
ListBox2.Items.Add(Crpe1.Tables[cnt].DLLName);
ListBox3.Items.Add(Crpe1.Tables[cnt].DescriptiveName);
end;
TabIcs Mcthuds
TabIcs Add mcthud
DccIaratiun
procedure Add(TableNumber: TCrTableNumber);
Typc
TCrTableNumber = integer;
VCI Re|etetce 676
Dcscriptiun
The Add method adds an item to the Tables object and sets the internal index to that item. It requires a Table
number as a parameter, which should be a number corresponding to a Table in the Report. Tables are
numbered starting from zero. If the Add method is used, the steps to using Tables are:
1 Add an item to the Tables object (you must specify the Table number).
2 Fill the item's properties (Name, Path, etc.) with values.
3 When Execute is called, the properties will be sent to the Print Engine.
NO7F: Il s easer lo use lhe Relreve melhod nslead ol Add, snce l ensures lhal lhe number ol lems, and lhe
7able numbers are correcl lor lhe currenl Reorl.
fxampIc
The following code uses the Add method to set the values for the first table in a Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Tables.Add(0);
Crpe1.Tables[0].Name := 'Address.dbf';
Crpe1.Tables[0].Path := 'C:\Temp\Tables\';
Crpe1.Output := toWindow;
Crpe1.Execute;
TabIcs CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to clear the internal memory of the Tables 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 Tables object of the current Report/Subreport specified in the
Subreports object. Therefore, to clear all the Tables of all the Subreports will require a looping procedure that
goes through each Subreport and applies the Clear method:
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.Tables.Clear;
end;
VCI Re|etetce 677
fxampIc
This code clears the Tables properties for the main Report (assuming the default state of Subreports[0]):
Crpe1.Tables.Clear;
This code clears the Tables properties for the second Subreport:
Crpe1.Subreports[2];
Crpe1.Tables.Clear;
TabIcs CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeTables): boolean;
Dcscriptiun
The CopyFrom method copies the Tables property values from another TCrpeTables object. It is similar to
Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the Tables property values to a temporary TCrpeTables object:
var
tempTables : TCrpeTables;
begin
tempTables := TCrpeTables.Create;
tempTables.CopyFrom(Crpe1.Tables);
{...later, when finished with the temp object...}
tempTables.Free;
end;
TabIcs Cuunt mcthud
DccIaratiun
function Count: integer;
Dcscriptiun
The Count method can be used to obtain the number of items currently in the Tables object. It is useful for
setting up loops to make similar changes to each item.
VCI Re|etetce 678
fxampIc
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.Tables.Retrieve;
for cnt := 0 to (Crpe1.Tables.Count - 1) do
Crpe1.Tables[cnt].Name := 'NewTable.dbf';
end;
TabIcs Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the Tables object, and does not need
to be called in code.
TabIc DcIctc mcthud
DccIaratiun
procedure Delete(nIndex: integer);
Dcscriptiun
The Delete method can be used to remove an item from the Tables object. The "nIndex" parameter represents
the number of the item in the Tables object, which may not be the same as the actual Table Number.
NO7F: Delele wll nol remove lhe 7able lrom lhe Reorl, l wll jusl remove l lrom lhe Cryslal VCI.
VCI Re|etetce 670
fxampIc
The following code uses the Add method to set the values for the first table in a Report, and then, after running
the Report, deletes the Table item from the VCL. This is not normally necessary, though, as Tables would
automatically be cleared when the ReportName changes:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Tables.Add(0);
Crpe1.Tables[0].Name := 'Address.dbf';
Crpe1.Tables[0].Path := 'C:\Temp\Tables\';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.Tables.Delete(0);
TabIcs Dcstruy mcthud
DccIaratiun
destructor Destroy; override;
Dcscriptiun
The Destroy method is used internally in the Crystal component and does not need to be called in code.
NO7F: 7he 7Cre comonenl s resonsble lor crealng and lreeng all ol lhe sub-classes lhal belong lo l. 7he
only lme you would wanl lo be concerned wlh dong lhs s l you are crealng a lemorary objecl lo slore
dala lrom lhe 7Cre usng lhe CoyFrom melhod lhal s avalable lrom lhe sub-class or lhe CoyFrom melhod
lhal s avalable lrom lhe man 7Cre class.
TabIcs Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the Tables information from the Report and adds one item to the Tables object
for each Table in the Report. If Tables information was not found, the call returns False. Be aware that calling
Retrieve will first cause the Tables object to be cleared, so any current information stored in it will be removed.
NO7F: Snce lhe 7ables objecl also ales lo Subreorls, lhe Relreve melhod wll oblan lhe 7ables lor lhe
Reorl (or Subreorl) lhal lhe Subreorls objecl ndex s currenlly onlng lo. Il you wanl lo oblan lhe 7ables
nlormalon lor lhe man Reorl and all ol lhe Subreorls, you wll have lo sle lhrough lhe Subreorls objecl and
call Relreve lor each lem. 7he VCI wll slore searale 7ables nlormalon lor each Subreorl (see Fxamle).
VCI Re|etetce 686
fxampIc
The following code illustrates the use of the Retrieve method for the main Report:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Tables.Retrieve;
The following code illustrates the use of the Retrieve method for the main Report and any Subreports:
var
cnt: integer;
begin
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Subreports.Retrieve;
{Loop through Reports and Retrieve}
for cnt := 0 to (Crpe1.Subreports.Count - 1) do
begin
Crpe1.Subreports[cnt];
Crpe1.Tables.Retrieve;
end;
{Set Crpe component back to main Report}
Crpe1.Subreports[0];
end;
TabIcs Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the Tables 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.
fxampIc
In this example, the Tables settings are sent from the Crystal component to the Crystal Reports Print Engine
DLL. This is normally handled automatically in the Execute method:
Crpe1.Tables.Send;
VCI Re|etetce 681
Vcrsiun Prupcrtics
Vcrsiun Dll prupcrty
DccIaratiun
property DLL: string;
Dcscriptiun
The DLL property is a read-only property that contains the DLL version number of the CRPE32.DLL which is
currently open.
The DLL property can be used whenever you build functionality into a Report that may not be available in
earlier versions of the Crystal Report Engine and you need to verify the version number first. This property
can also be a handy safeguard for users who have more than one version of the Crystal Report Engine with
the older version earlier in the path than the new version.
NO7F: 7here s some nlernal roleclon bull nlo lhe VCI whch wll revenl oeralon l a CRPF32.DII
earler lhan S.x.x.108 allemls lo load.
The SummaryInfo object, the WindowEvents, the WindowCursor object, and most of the WindowButtonBar
options (except for Visible), will only work with Crystal Reports 6.0, and the ParamFields object requires the
last maintenance release of 5.0: 5.0.x.108.
fxampIc
The following example checks to see if the version of the CRPE32.DLL is greater than 5. If it is, the
WindowButtonBar buttons can be made visible/invisible.
if StrToInt(Crpe1.Version.DLL[1]) > 5 then
Crpe1.WindowButtonBar.AllowDrillDown := True;
Vcrsiun fnginc prupcrty
DccIaratiun
property Engine: string;
Dcscriptiun
The Engine property is a read-only property that contains the Engine version number of the CRPE32.DLL
which is currently open.
VCI Re|etetce 682
The Engine property can be used whenever you build functionality into a Report that may not be available in
earlier versions of the Crystal Report Engine and you need to verify the version number first. This property
can also be a handy safeguard for users who have more than one version of the Crystal Report Engine with
the older version earlier in the path than the new version.
NO7F: 7here s some nlernal roleclon bull nlo lhe VCI whch wll revenl oeralon l a CRPF32.DII
earler lhan S.x.x.108 allemls lo load.
The SummaryInfo object, the WindowEvents, the WindowCursor object, and most of the WindowButtonBar
options (except for Visible), will only work with Crystal Reports 6.0, and the ParamFields object requires the
last maintenance release of 5.0: 5.0.x.108.
fxampIc
The following example checks to see if the version of the CRPE32.DLL is greater than 5. If it is, the
WindowButtonBar buttons can be made visible/invisible.
if StrToInt(Crpe1.Version.Engine[1]) > 5 then
Crpe1.WindowButtonBar.AllowDrillDown := True;
Vcrsiun Majur prupcrty
DccIaratiun
property Major: integer;
Dcscriptiun
The Major property is a read-only property that contains the major File Version number of the CRPE32.DLL
which is currently open. This is the first number sequence of the File Version string, ie. for 6, 0, 1, 135, the Major
version number would be 6.
fxampIc
The following example checks to see if the version of the CRPE32.DLL is greater than 5. If it is, the
WindowButtonBar buttons can be made visible/invisible.
if Crpe1.Version.Major > 5 then
Crpe1.WindowButtonBar.AllowDrillDown := True;
Vcrsiun Minur prupcrty
DccIaratiun
property Minor: integer;
VCI Re|etetce 68!
Dcscriptiun
The Minor property is a read-only property that contains the minor File Version number of the CRPE32.DLL
which is currently open. This is the last number sequence of the File Version string, that is, for 6, 0, 1, 135, the
Minor version number would be 135.
Vcrsiun Winduws prupcrty
DccIaratiun
property Windows: string;
Dcscriptiun
This property provides a formatted string that contains the version of Windows currently being used. It is
provided for general use, where certain features of an application may require different code if used on
Windows95 or WindowsNT.
The string is formatted with the Windows version first, ie. "95", then a slash character: "/", then the Windows
release number, that is, "4.0".
fxampIc
The following example uses the utility function GetToken to parse the Version.Windows string:
var
str1, str2 : string;
begin
str1 := Crpe1.Version.Windows;
str2 := Crpe1.GetToken(str1, '/');
ShowMessage('The Windows platform is: ' + str2 + chr(10) +
'and the Windows version number is: ' + str1);
end;
Vcrsiun Mcthuds
Vcrsiun CIcar mcthud
DccIaratiun
procedure Clear;
VCI Re|etetce 684
Dcscriptiun
The Clear method will reset the three Version properties to their default (empty strings). This should not
normally need to be used, since the Version properties are updated every time the Crystal Reports Print
Engine is opened, which is handled internally in the component.
fxampIc
The following example shows the code syntax of the Clear method:
Crpe1.Version.Clear;
Crpe1.Version.Retrieve;
ShowMessage(Crpe1.Version.DLL);
Vcrsiun CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeVersion): boolean;
Dcscriptiun
The CopyFrom method copies the Version property values from another TCrpeVersion object. It is similar to
Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the Version property values to a temporary TCrpeVersion object:
var
tempVersion : TCrpeVersion;
begin
tempVersion := TCrpeVersion.Create;
tempVersion.CopyFrom(Crpe1.Version);
{...later, when finished with the temp object...}
tempVersion.Free;
end;
Vcrsiun Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component and does not need to be called in code.
VCI Re|etetce 68S
Vcrsiun Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method obtains the Version information from the Report, and stores it in the Version object. This
does not normally need to be called in code, since it is called automatically whenever the Crystal Reports Print
Engine is opened. The component will open the Print Engine whenever required, although it can also be
opened manually via the OpenEngine method.
fxampIc
The following example shows the code syntax of the Retrieve function:
Crpe1.Version.Retrieve;
ShowMessage(Crpe1.Version.DLL);
WinduwButtunBar Prupcrtics
WinduwButtunBar AIIuwDriIIDuwn prupcrty
DccIaratiun
property AllowDrillDown: boolean;
Dcscriptiun
AllowDrillDown determines if drill-down capability will be enabled on the Preview Window or not. This only
applies to Crystal 6.0 or higher.
fxampIc
This code example sets the WindowButtonBar properties so that Drill-Down is possible, and the Cancel button
is hidden:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowButtonBar do
VCI Re|etetce 686
begin
Visible := True;
AllowDrillDown := True;
CancelBtn := False;
end;
Crpe1.Execute;
WinduwButtunBar CanccIBtn prupcrty
DccIaratiun
property CancelBtn: Boolean;
Dcscriptiun
CancelBtn determines if the Cancel Button will appear on the Preview Window or not. This only applies to
Crystal 6.0 or higher.
fxampIc
This code example sets the WindowButtonBar properties so that Drill-Down is possible, and the Cancel button
is hidden:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowButtonBar do
begin
Visible := True;
AllowDrillDown := True;
CancelBtn := False;
end;
Crpe1.Execute;
WinduwButtunBar CIuscBtn prupcrty
DccIaratiun
property CloseBtn: Boolean;
Dcscriptiun
CloseBtn determines if the Close Button will appear on the Preview Window or not. This only applies to
Crystal 6.0 or higher.
VCI Re|etetce 687
fxampIc
This code example sets the WindowButtonBar properties so that Drill-Down is possible, and the Close button
is hidden:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowButtonBar do
begin
Visible := True;
AllowDrillDown := True;
CloseBtn := False;
end;
Crpe1.Execute;
WinduwButtunBar fxpurtBtn prupcrty
DccIaratiun
property ExportBtn: Boolean;
Dcscriptiun
ExportBtn determines if the Export Button will appear on the Preview Window or not. This only applies to
Crystal 6.0 or higher.
fxampIc
This code example sets the WindowButtonBar properties so that Drill-Down is possible, and the Export button
is hidden:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowButtonBar do
begin
Visible := True;
AllowDrillDown := True;
ExportBtn := False;
end;
Crpe1.Execute;
VCI Re|etetce 688
WinduwButtunBar GruupTrcc prupcrty
DccIaratiun
property GroupTree: Boolean;
Dcscriptiun
GroupTree determines if the Group Tree will appear on the Preview Window or not. This only applies to
Crystal 6.0 or higher. If the Report has been saved with the Group Tree option turned off, it must first be
activated using the ReportOptions.CreateGroupTree property (ReportOptions are only available in SCR 7).
fxampIc
This code example sets the WindowButtonBar properties so that Drill-Down is possible, and the Group Tree
is visible:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowButtonBar do
begin
Visible := True;
AllowDrillDown := True;
GroupTree := True;
end;
Crpe1.Execute;
WinduwButtunBar NavigatiunCtIs prupcrty
DccIaratiun
property NavigationCtls: Boolean;
Dcscriptiun
NavigationCtls determines if the Navigation Controls will appear on the Preview Window or not. This only
applies to Crystal 6.0 or higher. Navigation Controls are the paging buttons. The action of these buttons can
also be simulated with the Pages object.
VCI Re|etetce 680
fxampIc
This code example sets the WindowButtonBar properties so that Drill-Down is possible, and the Navigation
Controls are hidden:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowButtonBar do
begin
Visible := True;
AllowDrillDown := True;
NavigationCtls := False;
end;
Crpe1.Execute;
WinduwButtunBar PrintBtn prupcrty
DccIaratiun
property PrintBtn: boolean;
Dcscriptiun
PrintBtn determines if the Print Button will appear on the Preview Window or not. This only applies to Crystal
6.0 or higher.
fxampIc
This code example sets the WindowButtonBar properties so that Drill-Down is possible, and the Print Button
is hidden:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowButtonBar do
begin
Visible := True;
AllowDrillDown := True;
PrintBtn := False;
end;
Crpe1.Execute;
VCI Re|etetce 606
WinduwButtunBar PrintSctupBtn prupcrty
DccIaratiun
property PrintSetupBtn: boolean;
Dcscriptiun
PrintSetupBtn determines if the Printer Setup Button will appear on the Preview Window or not. This only
applies to Crystal 6.0 or higher.
fxampIc
This code example sets the WindowButtonBar properties so that Drill-Down is possible, and the PrintSetup
button is hidden:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowButtonBar do
begin
Visible := True;
AllowDrillDown := True;
PrintSetupBtn := False;
end;
Crpe1.Execute;
WinduwButtunBar PrugrcssCtIs prupcrty
DccIaratiun
property ProgressCtls: Boolean;
Dcscriptiun
ProgressCtls determines if the Progress Controls will appear on the Preview Window or not. This only applies
to Crystal 6.0 or higher. Progress Controls are the numbers that appear when counting the records that have
been read, selected, and printed. These numbers are also available via the Records object.
VCI Re|etetce 601
fxampIc
This code example sets the WindowButtonBar properties so that Drill-Down is possible, and the Progress
Controls are hidden:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowButtonBar do
begin
Visible := True;
AllowDrillDown := True;
ProgressCtls := False;
end;
Crpe1.Execute;
WinduwButtunBar RcfrcshBtn prupcrty
DccIaratiun
property RefreshBtn: Boolean;
Dcscriptiun
RefreshBtn determines if the Refresh Button will appear on the Preview Window or not. This only applies to
Crystal 6.0 or higher.
fxampIc
This code example sets the WindowButtonBar properties so that Drill-Down is possible, and the Refresh
button is hidden:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowButtonBar do
begin
Visible := True;
AllowDrillDown := True;
RefreshBtn := False;
end;
Crpe1.Execute;
VCI Re|etetce 602
WinduwButtunBar ScarchBtn prupcrty
DccIaratiun
property SearchBtn: Boolean;
Dcscriptiun
SearchBtn determines if the Search Button will appear on the Preview Window or not. This only applies to
Crystal 6.0 or higher.
fxampIc
This code example sets the WindowButtonBar properties so that Drill-Down is possible, and the Search button
are hidden:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowButtonBar do
begin
Visible := True;
AllowDrillDown := True;
SearchBtn := False;
end;
Crpe1.Execute;
WinduwButtunBar VisibIc prupcrty
DccIaratiun
property Visible: boolean;
Dcscriptiun
The Visible property determines if the Preview Window Button Bar will be visible or not. If you are making
your own custom button bar, you may want to hide the Crystal button bar. This can be done by setting Visible
to False.
fxampIc
This code example turns off the Crystal Preview Window button bar:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
Crpe1.WindowButtonBar.Visible := False;
Crpe1.Execute;
VCI Re|etetce 60!
WinduwButtunBar ZuumCtI prupcrty
DccIaratiun
property ZoomCtl: Boolean;
Dcscriptiun
The ZoomCtl property determines if the window control used to set the Zoom Level will be visible on the
Preview Window or not. This only applies to Crystal 6.0 or higher.
fxampIc
This code example sets the WindowButtonBar properties so that Drill-Down is possible, and the Zoom Control
is hidden:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowButtonBar do
begin
Visible := True;
AllowDrillDown := True;
ZoomCtl := False;
end;
Crpe1.Execute;
WinduwButtunBar Mcthuds
WinduwButtunBar CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
The Clear method sets all the properties associated with the WindowButtonBar object back to their default
values:
Visible := True;
AllowDrillDown := False;
CancelBtn := False;
CloseBtn := False;
VCI Re|etetce 604
ExportBtn := True;
GroupTree := False;
NavigationCtls := True;
PrintBtn := True;
PrintSetupBtn := False;
ProgressCtls := True;
RefreshBtn := False;
SearchBtn := False;
ZoomCtl := True;
These settings are exactly the same as the Crystal Reports 5.0 preview window, which did not have the extra
Preview Window buttons that were added in Crystal Reports 6.0, nor did it have the ability to show/hide the
various buttons.
It is called automatically if the Clear method is called for the main component, but may be called in code as
needed.
fxampIc
This line of code clears the WindowButtonBar properties:
Crpe1.WindowButtonBar.Clear;
WinduwButtunBar CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeWindowButtonBar): boolean;
Dcscriptiun
The CopyFrom method copies the WindowButtonBar property values from another TCrpeWindowButtonBar
object. It is similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the WindowButtonBar property values to a temporary
TCrpeWindowButtonBar object:
var
tempWindowButtonBar : TCrpeWindowButtonBar;
begin
tempWindowButtonBar := TCrpeWindowButtonBar.Create;
tempWindowButtonBar.CopyFrom(Crpe1.WindowButtonBar);
{...later, when finished with the temp object...}
tempWindowButtonBar.Free;
end;
VCI Re|etetce 60S
WinduwButtunBar Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the WindowButtonBar object, and
does not need to be called in code.
WinduwButtunBar Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
Dcscriptiun
The Retrieve method can be used to obtain the current WindowButtonBar settings from an open Crystal
Preview Window. If there is no open window, the Retrieve method returns False.
fxampIc
The following code sample runs a Report to Preview Window, then retrieves the WindowButtonBar settings:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.WindowButtonBar.Retrieve;
WinduwButtunBar Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the WindowButtonBar 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.
VCI Re|etetce 606
We strongly recommend 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.
fxampIc
In this example, the WindowButtonBar settings are sent from the Crystal component to the Crystal Reports
Print Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.WindowButtonBar.Send;
WinduwCursur Prupcrtics
WinduwCursur DctaiIArca prupcrty
DccIaratiun
property DetailArea: TCrWindowCursor;
Typc
TCrWindowCursor = (wcDefault, wcArrow, wcCross, wcIBeam, wcUpArrow, wcSizeAll, wcSizeNWSE,
wcSizeNESW, wcSizeWE, wcSizeNS, wcNo, wcWait, wcAppStart, wcHelp, wcMagnify);
Dcscriptiun
The DetailArea property controls what Mouse Cursor shape will appear when the Mouse is passing over a
Detail section on the runtime Preview Window.
fxampIc
The example below sets the Mouse Cursor to a Magnifying Glass when it passes over a Detail Area on the
Preview Window:
Crpe1.ReportName := 'C:\Company.rpt;
Crpe1.WindowCursor.DetailArea := wcMagnify;
Crpe1.Output := toWindow;
Crpe1.Execute;
VCI Re|etetce 607
WinduwCursur DctaiIArcaFicId prupcrty
DccIaratiun
property DetailAreaField: TCrWindowCursor;
Typc
TCrWindowCursor = (wcDefault, wcArrow, wcCross, wcIBeam, wcUpArrow, wcSizeAll, wcSizeNWSE,
wcSizeNESW, wcSizeWE, wcSizeNS, wcNo, wcWait, wcAppStart, wcHelp, wcMagnify);
Dcscriptiun
The DetailAreaField property controls what Mouse Cursor shape will appear when the Mouse is passing over
a Field in a Detail section on the runtime Preview Window.
fxampIc
The example below sets the Mouse Cursor to a Magnifying Glass when it passes over a Detail Area Field on
the Preview Window:
Crpe1.ReportName := 'C:\Company.rpt;
Crpe1.WindowCursor.DetailAreaField := wcMagnify;
Crpe1.Output := toWindow;
Crpe1.Execute;
WinduwCursur Graph prupcrty
DccIaratiun
property Graph: TCrWindowCursor;
Typc
TCrWindowCursor = (wcDefault, wcArrow, wcCross, wcIBeam, wcUpArrow, wcSizeAll,
wcSizeNWSE, wcSizeNESW, wcSizeWE, wcSizeNS, wcNo, wcWait, wcAppStart, wcHelp,
wcMagnify);
Dcscriptiun
The Graph property controls what Mouse Cursor shape will appear when the Mouse is passing over a Graph
on the runtime Preview Window.
VCI Re|etetce 608
fxampIc
The example below sets the Mouse Cursor to a Magnifying Glass when it passes over a Detail Area Field on
the Preview Window:
Crpe1.ReportName := 'C:\Company.rpt;
Crpe1.WindowCursor.DetailAreaField := wcMagnify;
Crpe1.Output := toWindow;
Crpe1.Execute;
WinduwCursur GruupArca prupcrty
DccIaratiun
property GroupArea: TCrWindowCursor;
Typc
TCrWindowCursor = (wcDefault, wcArrow, wcCross, wcIBeam, wcUpArrow, wcSizeAll,
wcSizeNWSE, wcSizeNESW, wcSizeWE, wcSizeNS, wcNo, wcWait, wcAppStart, wcHelp,
wcMagnify);
Dcscriptiun
The GroupArea property controls what Mouse Cursor shape will appear when the Mouse is passing over a
Group section on the runtime Preview Window.
fxampIc
The example below sets the Mouse Cursor to a Magnifying Glass when it passes over a Group Area on the
Preview Window:
Crpe1.ReportName := 'C:\Company.rpt;
Crpe1.WindowCursor.GroupArea := wcMagnify;
Crpe1.Output := toWindow;
Crpe1.Execute;
WinduwCursur GruupArcaFicId prupcrty
DccIaratiun
property GroupAreaField: TCrWindowCursor;
VCI Re|etetce 600
Typc
TCrWindowCursor = (wcDefault, wcArrow, wcCross, wcIBeam, wcUpArrow, wcSizeAll,
wcSizeNWSE, wcSizeNESW, wcSizeWE, wcSizeNS, wcNo, wcWait, wcAppStart, wcHelp,
wcMagnify);
Dcscriptiun
The GroupAreaField property controls what Mouse Cursor shape will appear when the Mouse is passing over
a Field in a Group section on the runtime Preview Window.
fxampIc
The example below sets the Mouse Cursor to a Magnifying Glass when it passes over a Group Area Field on
the Preview Window:
rpe1.ReportName := 'C:\Company.rpt;
Crpe1.WindowCursor.GroupAreaField := wcMagnify;
Crpe1.Output := toWindow;
Crpe1.Execute;
WinduwCursur Mcthuds
WinduwCursur CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to set all of the WindowCursor properties back to default:
GroupArea := wcDefault;
GroupAreaField := wcDefault;
DetailArea := wcDefault;
DetailAreaField := wcDefault;
Graph := wcDefault;
fxampIc
This code clears the WindowCursor properties:
Crpe1.WindowCursor.Clear;
VCI Re|etetce 766
WinduwCursur CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeWindowCursor): boolean;
Dcscriptiun
The CopyFrom method copies the WindowCursor property values from another TCrpeWindowCursor object.
It is similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the WindowCursor property values to a temporary TCrpeWindowCursor
object:
var
tempWindowCursor : TCrpeWindowCursor;
begin
tempWindowCursor := TCrpeWindowCursor.Create;
tempWindowCursor.CopyFrom(Crpe1.WindowCursor);
{...later, when finished with the temp object...}
tempWindowCursor.Free;
end;
WinduwCursur Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create constructor creates the WindowCursor object. It is used internally in the VCL component to create
the WindowCursor object and should not be called outside of the component.
WinduwCursur Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
VCI Re|etetce 761
Dcscriptiun
The Retrieve method obtains the WindowCursor information from the Report and stores it in the
WindowCursor object. If WindowCursor information was not found, the call returns False.
fxampIc
This code sample retrieves the WindowCursor settings from a Report. Unless the Report has already been run
with specific WindowCursor settings (or if it has Saved Data), the retrieved values will be default:
Crpe1.ReportName := 'Company.rpt';
Crpe1.WindowCursor.Retrieve;
WinduwCursur Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the WindowCursor 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.
fxampIc
In this example, the WindowCursor settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.WindowCursor.Send;
WinduwSizc Prupcrtics
WinduwSizc Hcight prupcrty
DccIaratiun
property Height: smallint;
VCI Re|etetce 762
Dcscriptiun
The Height property specifies the height of the Preview Window, in pixels. Use -1 for default.
fxampIc
The following example displays a Report in a Preview Window. The window will appear in the upper left
corner of the screen and will be 300 pixels high, and 500 pixels wide:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowSize do
begin
Left := 0;
Top := 0;
Height := 300;
Width := 500;
end;
Crpe1.Execute;
WinduwSizc lcft prupcrty
DccIaratiun
property Left: smallint;
Dcscriptiun
The Left property specifies the x coordinate of the upper left corner of the Preview Window, in pixels. Use -1
for default.
fxampIc
The following example displays a Report in a Preview Window. The window will appear in the upper left
corner of the screen and will be 300 pixels high, and 500 pixels wide:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowSize do
begin
Left := 0;
Top := 0;
Height := 300;
Width := 500;
end;
Crpe1.Execute;
VCI Re|etetce 76!
WinduwSizc Tup prupcrty
DccIaratiun
property Top: smallint;
Dcscriptiun
The Top property specifies the y coordinate of the upper left corner of the Preview Window, in pixels. Use -1
for default.
fxampIc
The following example displays a Report in a Preview Window. The window will appear in the upper left
corner of the screen and will be 300 pixels high, and 500 pixels wide:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowSize do
begin
Left := 0;
Top := 0;
Height := 300;
Width := 500;
end;
Crpe1.Execute;
WinduwSizc Width prupcrty
DccIaratiun
property Width: smallint;
Dcscriptiun
The Width property specifies the width of the Preview Window, in pixels. Use -1 for default.
VCI Re|etetce 764
fxampIc
The following example displays a Report in a Preview Window. The window will appear in the upper left
corner of the screen and will be 300 pixels high, and 500 pixels wide:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
with Crpe1.WindowSize do
begin
Left := 0;
Top := 0;
Height := 300;
Width := 500;
end;
Crpe1.Execute;
WinduwSizc Mcthuds
WinduwSizc CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
The Clear method clears the WindowSize properties, setting them all to their default values:
Top := -1;
Left := -1;
Width := -1;
Height := -1;
It is called automatically if the Clear method is called for the main component, but may be called in code as
needed.
fxampIc
This line of code clears the WindowSize properties:
Crpe1.WindowSize.Clear;
VCI Re|etetce 76S
WinduwSizc CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeWindowSize): boolean;
Dcscriptiun
The CopyFrom method copies the WindowSize property values from another TCrpeWindowSize object. It is
similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the WindowSize property values to a temporary TCrpeWindowSize object:
var
tempWindowSize : TCrpeWindowSize;
begin
tempWindowSize := TCrpeWindowSize.Create;
tempWindowSize.CopyFrom(Crpe1.WindowSize);
{...later, when finished with the temp object...}
tempWindowSize.Free;
end;
WinduwSizc Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component and does not need to be called in code.
WinduwSizc Rctricvc mcthud
DccIaratiun
function Retrieve: boolean;
VCI Re|etetce 766
Dcscriptiun
Retrieve can be used to obtain the size of the currently open Crystal Preview Window. If there is a Preview
Window open when the Retrieve method is called, the WindowSize properties will be updated with the
Preview Window size and position.
fxampIc
The following code sample runs a Report to Preview Window, then retrieves the size and position of the
Window:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.WindowSize.Retrieve;
WinduwSizc Scnd mcthud
DccIaratiun
function Send : boolean;
Dcscriptiun
Send can be used to actively change the size and position of the currently open Crystal Preview Window. The
size and position of the Preview Window will be changed to reflect the values of the Top, Left, Width and
Height properties.
fxampIc
The following code sample runs a Report to Preview Window, then changes the size and position of the
Window:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.Execute;
Crpe1.WindowSize.Retrieve;
Crpe1.WindowSize.Top := 5;
Crpe1.WindowSize.Left := 5;
Crpe1.WindowSize.Send;
VCI Re|etetce 767
WinduwStyIc Prupcrtics
WinduwStyIc BurdcrStyIc prupcrty
DccIaratiun
property BorderStyle: TCrFormBorderStyle;
Typc
TCrFormBorderStyle = bsNone..bsDialog;
{bsNone, bsSingle, bsSizeable, bsDialog}
Dcscriptiun
The BorderStyle property is of Type: TCrFormBorderStyle, which is a smaller sub-set of Delphi's
TFormBorderStyle. It includes bsNone, bsSingle, bsSizeable, and bsDialog. Out of these, probably the two
most useful are bsSizeable and bsNone, since the first style is best used for running the Preview Window as a
stand-alone window, and the second is best used when running the Crystal Window as a child of another
Delphi Form. The default BorderStyle is bsSizeable.
WinduwStyIc DisabIcd prupcrty
DccIaratiun
property Disabled: boolean;
Dcscriptiun
The Disabled property can be used to disable and enable the Preview Window. When the Window is Disabled,
it will still be visible, but will not react to keystrokes or mouse clicks. To hide and show the Preview Window,
use the ShowWindow and HideWindow methods of TCrpe.
Disabled can be set either before or after the TCrpe.Execute method is called. If it is set after Execute, it will act
on the open Preview Window.
VCI Re|etetce 768
fxampIc
The following example illustrates the use of the Disabled property to deactivate the Preview Window until the
Report has finished processing:
Crpe1.ReportName := 'C:\Company.rpt';
Crpe1.Output := toWindow;
Crpe1.WindowStyle.Disabled := True;
Crpe1.Execute;
while Crpe1.Status <> 3 do
Application.ProcessMessages;
Crpe1.WindowStyle.Disabled := False;
WinduwStyIc MaxButtun prupcrty
DccIaratiun
property MaxButton: Boolean;
Dcscriptiun
MaxButton controls whether the maximize button appears on the Preview Window or not. If BorderStyle is set
to bsNone or bsDialog, this property is ignored because the maximize button is not available for these styles.
fxampIc
This code sample shows how to set the WindowStyle options:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
{Set the WindowStyle options}
with Crpe1.WindowStyle do
begin
BorderStyle := Sizeable;
SystemMenu := True;
MaxButton := True;
MinButton := True;
Title := 'MyReport';
end;
Crpe1.Execute;
WinduwStyIc MinButtun prupcrty
DccIaratiun
property MinButton: Boolean;
VCI Re|etetce 760
Dcscriptiun
MinButton controls whether the minimize button appears on the Preview Window or not. If BorderStyle is set
to bsNone or bsDialog, this property is ignored because the minimize button is not available for these styles.
fxampIc
This code sample shows how to set the WindowStyle options:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
{Set the WindowStyle options}
with Crpe1.WindowStyle do
begin
BorderStyle := Sizeable;
SystemMenu := True;
MaxButton := True;
MinButton := True;
Title := 'MyReport';
end;
Crpe1.Execute;
WinduwStyIc SystcmMcnu prupcrty
DccIaratiun
property SystemMenu: Boolean;
Dcscriptiun
SystemMenu applies to the Windows system menu that appears when the top left corner of a window is
clicked, or Alt-SpaceBar is pressed. This property determines if the system menu is available on the Preview
Window or not. This property is ignored if the BorderStyle is set to bsNone.
fxampIc
This code sample shows how to set the WindowStyle options:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
{Set the WindowStyle options}
with Crpe1.WindowStyle do
begin
BorderStyle := Sizeable;
SystemMenu := True;
MaxButton := True;
MinButton := True;
Title := 'MyReport';
end;
Crpe1.Execute;
VCI Re|etetce 716
WinduwStyIc TitIc prupcrty
DccIaratiun
property Title: string;
Dcscriptiun
The Title property contains the string that will appear in the Preview Window Title Bar, which is normally
called the window Caption. If the BorderStyle is set to bsNone, this property will be ignored because windows
with no border should not have a caption.
Title is an "active" property. If it is changed while a Preview Window is open, the Window will be updated
immediately.
fxampIc
This code sample shows how to set the WindowStyle options:
Crpe1.ReportName := 'MyReport.rpt';
Crpe1.Output := toWindow;
{Set the WindowStyle options}
with Crpe1.WindowStyle do
begin
BorderStyle := Sizeable;
SystemMenu := True;
MaxButton := True;
MinButton := True;
Title := 'MyReport';
end;
Crpe1.Execute;
WinduwStyIc Mcthuds
WinduwStyIc CIcar mcthud
DccIaratiun
procedure Clear;
VCI Re|etetce 711
Dcscriptiun
This method clears the WindowStyle properties by setting them to default:
BorderStyle := bsSizeable;
ControlBox := True;
MaxButton := True;
inButton := True;
Title := '';
It is called automatically if the Clear method is called for the main component, but may be called in code as
needed.
fxampIc
This line of code clears the WindowStyle properties:
Crpe1.WindowStyle.Clear;
WinduwStyIc CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeWindowStyle): boolean;
Dcscriptiun
The CopyFrom method copies the WindowStyle property values from another TCrpeWindowStyle object. It
is similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the WindowStyle property values to a temporary TCrpeWindowStyle object:
var
tempWindowStyle : TCrpeWindowStyle;
begin
tempWindowStyle := TCrpeWindowStyle.Create;
tempWindowStyle.CopyFrom(Crpe1.WindowStyle);
{...later, when finished with the temp object...}
tempWindowStyle.Free;
end;
VCI Re|etetce 712
WinduwStyIc Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component to create the WindowStyle object, and does not
need to be called in code.
WinduwZuum Prupcrtics
WinduwZuum Magnificatiun prupcrty
DccIaratiun
property Magnification: TCrZoomMagnification;
Typc
TCrZoomMagnification = -1..400;
Dcscriptiun
The Magnification property controls the zoom level of a Report Preview Window. The acceptable values are:
0,1,2 : Same as the Preview enumerated values (pwNormal, pwPageWidth, pwWholePage)
25 to 400 : Magnification by percentage
-1, 3 to 24 : Default Magnification used (no change)
NO7F: 7he ZoomMagnlcalon range goes down lo -1 because -1 s used as a slandard numerc delaull value
lhroughoul Delh and lhroughoul lhe Cryslal comonenl. However, n lhs case, any value below 2S (excel
0,1, or 2) wll be counled as delaull, e. lhe roerly wll be gnored.
fxampIc
This example sets the zoom magnification level of the Preview Window to 50 percent:
Crpe1.WindowZoom.Magnification := 50;
VCI Re|etetce 71!
WinduwZuum Prcvicw prupcrty
DccIaratiun
property Preview: TCrZoomPreview;
Typc
TCrZoomPreview = (pwNormal, pwPageWidth, pwWholePage, pwDefault);
Dcscriptiun
The Preview property sets the zoom level of a Report Preview Window to a pre-defined level:
pwNormal = Equivalent to 100% magnification.
pwPageWidth = The Report will be sized to fit the width of the Preview Window.
pwWholePage = The Report will be sized to fit the width and height of the Preview Window.
pwDefault = The Preview property is ignored. The zoom level will be determined by the level
the Report was saved with, or the setting of the Magnification property.
The property may be set in code, either before or after the Execute method. If it is used after Execute, it will
immediately act on the currently open Preview Window.
fxampIc
This example sets the Preview Window zoom level so that the Report will be sized to the width and height of
the window:
Crpe1.WindowZoom.Preview := pwWholePage;
WinduwZuum Mcthuds
WinduwZuum CIcar mcthud
DccIaratiun
procedure Clear;
Dcscriptiun
This method can be used to set the WindowZoom properties to their default values:
Preview := pwDefault;
Magnification := -1;
It is called automatically if the Clear method is called for the main component, but may be called in code as needed.
VCI Re|etetce 714
WinduwZuum CupyFrum mcthud
DccIaratiun
function CopyFrom(Source: TCrpeWindowZoom): boolean;
Dcscriptiun
The CopyFrom method copies the WindowZoom property values from another TCrpeWindowZoom object.
It is similar to Delphi's Assign method. It is useful for transferring or temporary storage of values.
fxampIc
The following example copies all the WindowZoom property values to a temporary TCrpeWindowZoom
object:
var
tempWindowZoom : TCrpeWindowZoom;
begin
tempWindowZoom := TCrpeWindowZoom.Create;
tempWindowZoom.CopyFrom(Crpe1.WindowZoom);
{...later, when finished with the temp object...}
tempWindowZoom.Free;
end;
WinduwZuum Crcatc mcthud
DccIaratiun
constructor Create;
Dcscriptiun
The Create method is used internally in the Crystal component and does not need to be called in code.
WinduwZuum NcxtlcvcI mcthud
DccIaratiun
procedure NextLevel;
VCI Re|etetce 71S
Dcscriptiun
The NextLevel method advances the Preview level by one step.
G If it is currently at pwNormal, it will go to pwPageWidth.
G If it is at pwPageWidth it will go to pwWholePage.
G If it is at pwWholePage it will go to pwNormal.
This property can be useful when designing a custom button bar, or custom Form that is to control the Preview
Window.
fxampIc
This code will advance the WindowZoom Preview level by one step:
Crpe1.WindowZoom.NextLevel;
WinduwZuum Scnd mcthud
DccIaratiun
function Send: boolean;
Dcscriptiun
The Send method sends the WindowZoom 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.
fxampIc
In this example, the WindowZoom settings are sent from the Crystal component to the Crystal Reports Print
Engine DLL. This is normally handled automatically in the Execute method:
Crpe1.WindowZoom.Send;
ltdex1
l N D L X
C
Constunts
DetuCopes...................... 206
Lmpty Strng ...................... 206
Lxport ................................ 206
Murgns ............................. 206
PrntCptons ...................... 206
Secton .............................. 206
f
Lrror Codes - Crystu keports Prnt
Lngne................................. 2l0
Lrror Codes - VCL
Ceneru ............................. 207
Cruphs .............................. 208
CroupCondton/
CroupCptons.................. 208
CroupSortleds................. 208
LogCnlnlo......................... 208
Purumeter leds ................ 208
Prnter ............................... 208
Sectons............................. 209
Sessonlnlo ........................ 209
Sortleds........................... 209
SL Purums....................... 209
Subreports ......................... 209
Summurylnlo..................... 209
1ubes................................ 2l0
\ndow............................ 2l0
Lvents
CnLrror ............................. l66
CnLxecuteegn................ l68
CnLxecuteDoneSend ........ l69
CnLxecuteLnd................... l69
CnledMuppng ............... l70
CnCetVerson ................... l72
Cn}obCpened................... l73
CnPrntLnded.................... l74
CnPrnterSend................... l75
Cn\ndowCose............... l75
M
Methods
ooeun1oStr ..................... l32
Cunce}ob.......................... l33
Ceur ................................. l33
CoseLngne....................... l36
Cose}ob............................ l37
Cose\ndow.................... l37
Copylrom ......................... l38
Creute................................ l35
Dute1me1oStr .................. l38
Dute1oStr .......................... l39
Destroy.............................. l39
LxDuteStr ...........................l40
LxDute1meStr ...................l4l
Lxecute ..............................l42
Lxport\ndow...................l40
Lx1meStr...........................l44
loutng1oStr......................l44
locused .............................l45
CetPuthlromAus ..............l45
Cet1oken...........................l46
CetVersonlnlo...................l47
Hde\ndow.....................l47
lsStrLmpty ..........................l48
LogCnPrvutelnlo...............l48
CpenLngne.......................l5l
Cpen}ob ............................l5l
Prnt\ndow .....................l52
keport\ndowHunde .......l53
ketreveDetuCopes..........l53
ketreveledMuppng ........l54
ketrevekeport1te.............l54
ketreve\ndowStute.........l54
SectonCode1oStr ..............l55
SendDetuCopes ..............l56
SendDuogPurent ..............l56
SendDscurdSuvedDutu......l57
SendledMuppng .............l57
SendCutput .......................l58
SendProgressDuog ...........l58
Sendkeport1te .................l59
Setlocus ............................l59
Show\ndow....................l60
Str1oooeun .....................l60
Str1oDute...........................l6l
Str1oDute1me...................l6l
Str1oloutng......................l62
Str1oSectonCode ..............l62
Str1o1Crooeun................l63
Str1o1me ..........................l63
1Crooeun1oStr................l64
1me1oStr ..........................l64
1runcStr .............................l65
VerlyDutubuse ..................l65
P
Propertes
About.....................................6
Areulormut ............................7
Areulormut Methods............l0
Areulormut Propertes............9
Areulormutlormuus............l0
Areulormutlormuus
Methods .............................l2
Areulormutlormuus
Propertes ...........................l2
CunCoseLngne .................. l3
Connect............................... l3
Connect Methods ................ l5
Connect Propertes .............. l5
ConnectMethod................... l5
DesgnContros.................... l7
DetuCopes........................ l9
DuogPurent ....................... 20
DscurdSuvedDutu............... 2l
Lxport.................................. 2l
Lxport Lmu Methods.......... 24
Lxport Lmu Propertes........ 24
Lxport Methods ................... 25
Lxport Propertes ................. 24
ledMuppng ...................... 26
lormuus ............................. 27
lormuus Methods............... 29
lormuus Propertes ............. 29
CruphDutu .......................... 30
CruphDutu Methods ............ 32
CruphDutu Propertes .......... 3l
CruphCptons ..................... 32
CruphCptons Methods ....... 34
CruphCptons Propertes ..... 33
Cruph1ext ........................... 34
Cruph1ext Methods............. 36
Cruph1ext Propertes........... 36
Cruph1ype .......................... 36
Cruph1ype Methods............ 38
Cruph1ype Propertes.......... 38
CroupCondton .................. 39
CroupCondton Methods.... 40
CroupCondton
Propertes........................... 40
CroupCptons ..................... 4l
CroupCptons Methods....... 43
CroupCptons Propertes..... 42
CroupSeecton ................... 43
CroupSeecton Methods ..... 45
CroupSeecton Propertes ... 45
CroupSortleds................... 46
CroupSortleds Methods .... 47
CroupSortleds
Propertes........................... 47
HusSuvedDutu..................... 47
ls}oblnshed ....................... 48
}obNumber.......................... 49
LustLrrorNumber ................. 49
LustLrrorStrng ..................... 50
LoudLngneCnLse............... 5l
LogCnlnlo Methods............. 53
LogCnlnlo Propertes........... 53
LogCnServer ....................... 54
LogCnServer Propertes ....... 56
ltdex2
LonCnServer Methods......... 56
Murgns ............................... 56
Murgns Methods................. 57
Murgns Propertes............... 57
Cutput................................. 58
Puges................................... 59
Puges Methods .................... 60
Puges Propertes .................. 60
Purumleds......................... 6l
Purumleds lnlo Methods ... 65
Purumleds lnlo
Propertes........................... 65
Purumleds Methods .......... 66
Purumleds Propertes ........ 64
Purumleds kunges
Methods............................. 66
Purumleds kunges
Propertes........................... 65
PrntDute............................. 67
PrntDute Methods............... 67
PrntDute Propertes............. 67
PrntLnded........................... 68
Prnter ................................. 68
Prnter Methods ................... 8l
Prnter Propertes ................. 8l
Prnter, DevMode
Structure ............................ 70
Prnter, Settng Port
to llLL................................ 80
PrntCptons ........................ 8l
PrntCptons Methods.......... 83
PrntCptons Propertes........ 82
ProgressDuog .................... 83
kecords ............................... 84
kecords Methods................. 85
keportNume ........................ 85
keportCptons ..................... 87
keportCptons Methods....... 89
keportCptons Propertes..... 88
keport1te........................... 89
Sectonlont ......................... 90
Sectonlont Methods ........... 92
Sectonlont Propertes ......... 92
Sectonlormut ..................... 93
Sectonlormut Methods ....... 95
Sectonlormut Propertes ..... 95
Sectonlormutlormuus ....... 96
Sectonlormutlormuus
Methods............................. 98
Sectonlormutlormuus
Propertes........................... 98
SectonHeght ...................... 98
SectonHeght Methods ..... l00
SectonHeght Propertes ... l00
Seecton............................l00
Seecton Methods .............l04
Seecton Propertes ...........l04
SendCnLxecute .................l04
Sessonlnlo.................l05, l06
Sessonlnlo Propertes ........l06
Sortleds ...........................l07
Sortleds Methods.............l08
Sortleds Propertes...........l08
SL ...................................l08
SL Lxpressons
Methods ...........................l09
SL Lxpressons
Propertes .........................l09
SL Methods .....................lll
SL Purums Methods.........ll0
SL Purums Propertes.......ll0
SL Propertes ...................l09
Stutus .................................lll
Subreports..........................ll2
Subreports Methods ...........ll4
Subreports Propertes .........ll3
Summurylnlo .....................ll4
Summurylnlo Methods .......ll5
Summurylnlo Propertes .....ll5
1ubes ................................ll6
1ubes Methods..................ll7
1ubes Propertes................ll7
Verson ..............................ll8
Verson Methods................ll9
Verson Propertes..............ll9
\ndowuttonur .............ll9
\ndowuttonur
Methods ...........................l2l
\ndowuttonur
Propertes .........................l2l
\ndowCursor ..................l2l
\ndowCursor Methods ....l23
\ndowCursor
Propertes .........................l23
\ndowLvents...................l23
\ndowPurent ...................l24
\ndowSze ......................l26
\ndowSze Methods........l27
\ndowSze Propertes......l27
\ndowStute .....................l27
\ndowStye .....................l28
\ndowStye Methods.......l29
\ndowStye Propertes.....l29
\ndowZoom ...................l30
\ndowZoom Methods .....l30
\ndowZoom
Propertes .........................l30
T
1Crpe Component
Constunts........................... 206
Lrror Codes - VCL
Component...................... 207
Lvents................................ l66
lntroducton........................... 2
Methods ............................ l3l
Propertes .............................. 2
Propertes y Croup .............. 5
1ypes................................. 200
\ndowLvents .................. l76
1ypes
Custom Property led ....... 205
Lnumeruted, Lxport ........... 200
Lnumeruted,
ledMuppng................... 20l
Lnumeruted, lormuus ....... 20l
Lnumeruted, Ceneru......... 200
Lnumeruted, Cruph ........... 20l
Lnumeruted, Murgns......... 20l
Lnumeruted, Purumleds .. 202
Lnumeruted, Prnter/
PrntCptons .................... 202
Lnumeruted,
keportCptons ................. 202
Lnumeruted, Sectonlont ... 202
Lnumeruted, Sort/Croup .... 202
Lnumeruted, SL............... 203
Lnumeruted,
Summurylnlo ................... 203
Lnumeruted, 1ubes ........... 203
Lnumeruted, \ndow........ 203
Lnumeruted, \ndow
Cursor.............................. 203
Lnumeruted, \ndow
Lvents .............................. 203
Lvent ................................. 204
W
\ndowLvents
wCnActvute\ndow........ l77
wCnCuncetnCck.......... l78
wCnCosetnCck............ l78
wCnCose\ndow............ l79
wCnDeActvute\ndow... l80
wCnDrDetu ................. l8l
wCnDrCroup................. l82
wCnLxporttnCck........... l84
wCnlrstPugetnCck....... l85
wCnCroup1reetnCck.... l85
wCnLustPugetnCck ....... l86
wCnNextPugetnCck...... l87
ltdex!
wCnPrevousPuge
tnCck........................... l88
wCnPrnttnCck ............. l89
wCnPrntSetuptnCck..... l90
wCnkeudngkecords......... l9l
wCnkelreshtnCck ......... l92
wCnkghtMouseCck ....... l92
wCnSeurchtnCck .......... l95
wCnShowCroup ............... l96
wCnSturtLvent................... l97
wCnStopLvent................... l98
wCnZoomLeveChunge..... l99