Business objects CRYSTAL REPORTS 9 User Manual

Crystal Reports™ 9 Technical Reference Guide

Crystal Decisions, Inc.

895 Emerson St.

Palo Alto

California, USA 94301

Issue 2.

No part of this documentation may be stored in a retrieval system, transmitted or reproduced in any way, except in accordance with the terms of the applicable software license agreement. This documentation contains proprietary information of Crystal Decisions, Inc., and/or its suppliers.

Trademark Acknowledgements

Crystal Decisions, Crystal Reports, Crystal Enterprise, Crystal Analysis, Crystal Services, Crystal Care, Crystal Assist, Crystal Applications, Info and Holos are trademarks or registered trademarks of Crystal Decisions, Inc. in the U.S. and/or other countries. All other trademarks or registered trademarks referenced are the property of their respective owners.

Contents

Chapter 1: Welcome to Crystal Enterprise Development

About Crystal Enterprise ................................................................... 2

About the guide ................................................................................ 2

Product registration .......................................................................... 5

Crystal Care technical support .......................................................... 5

Crystal Training ................................................................................. 5

Crystal Consulting ............................................................................ 6

Document conventions ..................................................................... 6

Chapter 2: What’s New in the RDC

Report Designer Component 9 (RDC) ............................................... 8

Connection information property bags ............................................. 8

Field elements in text objects ............................................................ 8

Cascading Style Sheets ...................................................................... 9

Exporting options .............................................................................. 9

Printing options ............................................................................... 10

Charting options .............................................................................11

Condition formulas ......................................................................... 12

Group name condition formulas ..................................................... 12

Source for linked OLE objects ......................................................... 12

Additional information .................................................................... 12

Crystal Reports Technical Reference Guide i

Chapter 3: Report Designer Component Object Model

Overview of the Report Designer Object Model ............................. 14

Unification of the RDC object model .............................................. 15

Runtime licensing ............................................................................ 15

Object naming conflicts .................................................................. 16

Objects and Collections .................................................................. 16

Creatable Objects ........................................................................... 16

Application Object .......................................................................... 17

Area Object ....................................................................................22

Areas Collection .............................................................................. 25

BlobFieldObject Object .................................................................. 26

BoxObject Object ........................................................................... 28

ConnectionProperty Object ............................................................ 29

ConnectionProperties Collection .................................................... 35

CrossTabGroup Object ................................................................... 37

CrossTabGroups Collection ............................................................ 38

CrossTabObject Object ................................................................... 40

Database Object ............................................................................. 42

DatabaseFieldDefinition Object ...................................................... 48

DatabaseFieldDefinitions Collection ............................................... 49

DatabaseTable Object ..................................................................... 50

DatabaseTables Collection .............................................................. 53

ExportOptions Object ..................................................................... 56

FieldDefinitions Collection ............................................................. 61

FieldElement Object ........................................................................ 62

ii Crystal Reports Technical Reference Guide

FieldElements Collection ................................................................. 66

FieldMappingData Object ............................................................... 67

FieldObject Object ......................................................................... 68

FormattingInfo Object .................................................................... 73

FormulaFieldDefinition Object ....................................................... 74

FormulaFieldDefinitions Collection ................................................ 75

GraphObject Object ....................................................................... 77

GroupNameFieldDefinition Object ................................................. 83

GroupNameFieldDefinitions Collection .......................................... 84

LineObject Object .......................................................................... 84

MapObject Object .......................................................................... 86

ObjectSummaryFieldDefinitions Collection .................................... 87

OlapGridObject Object .................................................................. 88

OleObject Object ........................................................................... 90

Page Object ....................................................................................92

PageEngine Object .......................................................................... 94

PageGenerator Object .................................................................... 97

Pages Collection ............................................................................ 103

ParameterFieldDefinition Object .................................................. 104

ParameterFieldDefinitions Collection ........................................... 111

ParameterValue Object ................................................................. 112

ParameterValues Collection .......................................................... 112

ParameterValueInfo Object .......................................................... 113

ParameterValueInfos Collection ................................................... 114

PrintingStatus Object .................................................................... 115

Crystal Reports Technical Reference Guide iii

Report Object ............................................................................... 116

ReportAlert Object ....................................................................... 129

ReportAlerts Collection ................................................................. 130

ReportAlertInstance Object .......................................................... 132

ReportAlertInstances Collection ................................................... 132

ReportObjects Collection .............................................................. 133

RunningTotalFieldDefinition Object ............................................. 133

RunningTotalFieldDefinitions Collection ...................................... 137

Section Object .............................................................................. 139

Sections Collection ....................................................................... 150

SortField Object ............................................................................ 151

SortFields Collection ..................................................................... 152

SpecialVarFieldDefinition Object ................................................. 153

SQLExpressionFieldDefinition Object ........................................... 154

SQLExpressionFieldDefinitions Collection .................................... 155

SubreportLink Object .................................................................... 157

SubreportLinks Collection ............................................................. 158

SubreportObject Object ............................................................... 159

SummaryFieldDefinition Object ................................................... 162

SummaryFieldDefinitions Collection ............................................. 164

TableLink Object ........................................................................... 165

TableLinks Collection .................................................................... 166

TextObject Object ........................................................................ 167

Examples ....................................................................................... 171

Enumerated Types ......................................................................... 201

iv Crystal Reports Technical Reference Guide

Chapter 4: Programming the Crystal Report Viewers

Enhancements to the Report Viewer ............................................. 232

Application Development with Crystal Report Viewers ................ 232

Crystal Report Viewer for ActiveX ................................................ 233

The Crystal Report Viewer Java Bean ............................................ 240

Chapter 5: Report Viewer Object Model

Report Viewer/ActiveX Object Model technical reference ........... 244

Enumerated Types ......................................................................... 265

The Report Viewer/Java Bean technical reference ........................ 267

Chapter 6: Programming the Embeddable Crystal Reports Designer Control

Overview ...................................................................................... 274

Creating a Microsoft Visual Basic sample application with

the Embeddable Designer ............................................................. 274

Creating a Microsoft Visual C++ sample application with

the Embeddable Designer ............................................................. 280

Designing reports in the Embeddable Designer ............................. 288

Chapter 7: Embeddable Crystal Reports Designer Control Object Model

Overview of the Embeddable Designer ......................................... 292

Application development with the Embeddable Designer ............. 292

Distributing the Embeddable Designer .......................................... 293

Properties and methods of the Embeddable Designer ................... 294

Crystal Reports Technical Reference Guide v

Chapter 8: Active Data

Active Data Drivers ..................................................................... 298

Crystal Data Object ...................................................................... 308

Crystal Data Source Type Library ................................................. 311

COM data provider ....................................................................... 320

Chapter 9: Crystal Data Source Object Models

Crystal Data Source Object Models .............................................. 328

Crystal Data Objects ..................................................................... 328

CrystalComObject ........................................................................ 328

Crystal Data Source Type Library ................................................. 335

Chapter 10: Creating User-Defined Functions in C

Overview of User-Defined Functions in C .................................... 340

Programming User-Defined Functions in C ................................... 340

Programming the UFL ................................................................... 343

Setting up a UFL project ............................................................... 345

Function definition ........................................................................ 346

Returning user-defined errors ....................................................... 351

Obtaining parameter values from the parameter block ................ 352

Picture function—a sample UFL function ..................................... 353

Module Definition (.def) file ......................................................... 355

UFJOB modules ............................................................................ 356

Implement InitJob and TermJob ................................................... 357

Special functions ........................................................................... 358

vi Crystal Reports Technical Reference Guide

Chapter 11: Creating User-Defined Functions in Visual Basic

Overview of User-Defined Functions in Visual Basic .................... 360

Programming User-Defined Functions in Visual Basic .................. 360

Visual Basic and Crystal Reports ................................................... 365

Sample UFL Automation Server .................................................... 369

Chapter 12: Creating User-Defined Functions in Delphi 3.0

Overview of User-Defined Functions in Delphi ............................ 372

Programming User-Defined Functions in Delphi .......................... 372

Delphi and Crystal Reports ........................................................... 376

Chapter 13: Deprecated and Retired API Reference

Retired Developer APIs ................................................................. 382

Retired P2smon.dll functions ........................................................ 383

Deprecated RDC Interfaces .......................................................... 386

Deprecated RDC Properties .......................................................... 388

Deprecated RDC Methods ............................................................ 390

Deprecated RDC Export Format Types .........................................394

Index .............................................................................. 395

Crystal Reports Technical Reference Guide vii

viii Crystal Reports Technical Reference Guide

Welcome to Crystal Enterprise

Development 1

Welcome! This chapter introduces you to developing with Crystal Enterprise, the world standard for desktop and web reporting, and provides you with an overview of the contents of this guide.

Crystal Reports Technical Reference Guide 1

About Crystal Enterprise

Crystal Enterprise is designed to work with your database to help you analyze and interpret important information. Crystal Enterprise makes it easy to create simple reports; it also has the comprehensive tools you need to produce complex or specialized reports.

Create any report you can imagine

Crystal Enterprise is designed to produce the report you want from virtually any data source. Built-in report wizards and experts guide you step by step through building reports and completing common reporting tasks. Formulas, cross-tabs, subreports, and conditional formatting help make sense of data and help you uncover important relationships that might otherwise be hidden. Geographic maps and charts communicate information visually when words and numbers are simply not enough.

Extend reporting to the Web

The flexibility of Crystal Enterprise doesn’t end with creating reports—your reports can be published in a variety of formats including Microsoft® Word and Excel, email, and even over the Web. Advanced Web reporting lets other members of your workgroup view and update shared reports inside their web browser.

Incorporate reports into applications

Application and web developers can save time and meet the needs of their users by integrating the report processing power of Crystal Enterprise into their database applications. Support for most popular development languages makes it easy to add reporting to any application.

Whether it’s the web master in IT, the promotion manager in marketing, the database administrator in finance, or the CEO, Crystal Enterprise is a powerful tool designed to help everyone analyze and interpret the information that’s important to them.

About the guide

The guide includes technical information on the development tools included with Crystal Enterprise that allow you to integrate reporting into your application. The guide covers the Report Designer Component. It also contains tutorials and samples that will further aid you with adding the power of Crystal Enterprise to your application.

2 Crystal Reports Technical Reference Guide

Chapter contents

The following is a short description of each chapter in this guide.

Chapter 1: Welcome to Crystal Enterprise Development

Welcome! This chapter introduces you to developing with Crystal Enterprise, the world standard for desktop and web reporting, and provides you with an overview of the contents of this guide.

Chapter 2: What’s New in the RDC

With the release of Crystal Enterprise version 9, Crystal Enterprise continues to improve the flexibility and power of the Report Designer Component. New features allow you to enhance the reporting experience of your users.

This chapter introduces the new features and enhancements.

Chapter 3: Report Designer Component Object Model

The Report Designer Component is the ultimate development tool for your reporting needs. In this chapter you will find a detailed description of the Report Designer Component Object Model and its properties, methods and events.

Chapter 4: Programming the Crystal Report Viewers

The Crystal Report Viewer is a front-end user interface for viewing reports. In this chapter you will find detailed information on implementing the ActiveX and Java Bean viewers in your application.

1 : Welcome to Crystal Enterprise Development

Chapter 5: Report Viewer Object Model

The Crystal Report Viewer contains an extensive object model allowing you complete control over how the viewer appears and functions. This chapter provides detailed information on the properties, methods and events of the Crystal Report Viewer object model for both the ActiveX viewer, and the Java Bean viewer.

Chapter 6: Programming the Embeddable Crystal Reports Designer Control

This chapter demonstrates how to integrate the Embeddable Crystal Reports Designer Control (Embeddable Designer) into your application. Included are tutorials on creating sample applications in both Microsoft Visual Basic and Microsoft Visual C++. A brief section on creating reports in the designer at runtime is also included.

Crystal Reports Technical Reference Guide 3

About the guide

Chapter 7: Embeddable Crystal Reports Designer Control Object Model

The Embeddable Crystal Reports Designer Control (Embeddable Designer) is a new addition to the Report Designer Component; it enables you to provide a Crystal Reports designer in your application. In this chapter, you will find a general overview of the control as well as detailed information on its properties and methods.

Chapter 8: Active Data

This chapter provides information on using active data in the Crystal Reports Development environment. Four areas are covered: the active data drivers, the Crystal Data Object, the Crystal Data Source Type Library, and the COM Data Provider. By reading these sections you will learn how to create active data reports, create recordsets, and connect to the data source through the Report Designer Component automation server.

Chapter 9: Crystal Data Source Object Models

Crystal Reports provides support for reporting off data when no true data source exists. In this chapter you will find detailed information, including properties and methods, on Crystal Data Objects and the Crystal Data Source Type Library.

Chapter 10: Creating User-Defined Functions in C

Crystal Reports allows you to create User-Defined Functions that are recognized by the Crystal Reports Formula Editor. In this chapter you will find detailed information on programming User-Defined Functions in C.

Chapter 11: Creating User-Defined Functions in Visual Basic

Crystal Reports allows you to create User-Defined Functions that are recognized by the Crystal Reports Formula Editor. In this chapter you will find detailed information on programming User-Defined Functions in Microsoft Visual Basic.

Chapter 12: Creating User-Defined Functions in Delphi 3.0

Crystal Reports allows you to create User-Defined Functions that are recognized by the Crystal Reports Formula Editor. In this chapter you will find detailed information on programming User-Defined Functions in Delphi.

Chapter 13: Deprecated and Retired API Reference

The following developer APIs, interfaces, methods, and properties are retired or deprecated. Retired features are no longer available or supported. Deprecated features, while they may be supported for backwards compatibility, are not recommended for use in the current version of Crystal Reports. Deprecated features may become obsolete in future versions of the product.

4 Crystal Reports Technical Reference Guide

Product registration

There are several ways you can register your product:

• Fill out the Product Registration form on the Crystal Decisions, Inc. web site at:

http://www.crystaldecisions.com/register/

• Print the Product Registration form and fax it to the registration fax number

closest to you. Crystal Decisions will then fax you a registration number that can be entered into the product the next time you use it.

Registration fax numbers

USA/Canada +1 (604) 681-5147 United Kingdom +44 (0) 20 8231 0601 Australia +6 2 9955 7682 Germany +49 (0) 69 9509 6182 Hong Kong +852 2893 2727 Singapore +65 777 8786

Registering the product ensures that you are kept up-to-date with product advancements.

Crystal Care technical support

To find out about the technical support programs available for Crystal Enterprise:

• Consult the enclosed Crystal Care information card.

• Go to our support web site at:

http://support.crystaldecisions.com/crystalcare/

• Contact your regional office. For details, go to:

http://www.crystaldecisions.com/contact/offices.asp

1 : Welcome to Crystal Enterprise Development

Crystal Training

Whether you’re a developer, information technology professional, or business user, we offer a wide range of Crystal Enterprise training courses designed to build or enhance your existing skills. Courses are available online, at certified training centers, or at your own site:

• For a complete list of training courses and special offers, visit:

http://www.crystaldecisions.com/training/

• Or contact your regional office. For details, go to:

http://www.crystaldecisions.com/offices/

Crystal Reports Technical Reference Guide 5

Crystal Consulting

Our global team of certified consultants and consulting partners can guide you through a corporate-wide solution—including strategy, design, integration and deployment—for the fastest results, maximum performance, and increased productivity.

• To learn more, visit:

http://www.crystaldecisions.com/consulting/

• Or contact your regional office. For details, go to:

http://www.crystaldecisions.com/offices/

Document conventions

This guide uses the following conventions:

• Commands and buttons

For easy recognition within procedures, User Interface (UI) features appear in bold type. For example: On the File menu, click New.

• Keyboard shortcuts

Delete means the Delete key, or the Del key on your numeric keypad. Enter means the Enter, Return, or CR key, depending on which of these keys appears on your keyboard.

• Key combinations

CTRL+KEY, SHIFT+KEY, and ALT+KEY are examples of key combinations. Hold down the first key in the combination and, at the same time, press the second key in the combination (designated above as KEY). For example: CTRL+C means hold the Control key down and press the letter C on your keyboard (CTRL+C is the Windows Copy command).

• Monospaced font indicates data that you enter using your keyboard. For

example: In the Formula Editor, type used to show sample code:

If Sales > 1000 Then crRed

CRViewer1.ReportSource = CRXReport

. It is also

6 Crystal Reports Technical Reference Guide

What’s New in the RDC 2

With the release of version 9, Crystal Enterprise continues to improve the flexibility and power of the Report Designer Component. New features allow you to enhance the reporting experience of your users.

This chapter introduces the new features and enhancements.

Crystal Reports Technical Reference Guide 7

Report Designer Component 9 (RDC)

Designed for Microsoft Visual Studio and other COM-based development environments, the feature-rich Report Designer Component 9 (RDC) gives developers unprecedented control over report layout and formatting for web and Windows application reporting.

Reflecting the enhanced features of the Crystal Report Engine, the RDC supports most of the new Crystal Enterprise features, including database connectivity through connection information property bags, fields in text objects, cascading style sheets, additional export options, additional printing options, additional charting options, conditional formulas for areas sections and report objects, group name condition formulas, and retrieving the path to the data source for OLE objects.

Connection information property bags

The new query engine for Crystal Reports introduces a new feature: each database DLL has its own unique set of custom properties. These properties allow the developer to create a dynamic user interface, based on the data sources used by the report.

The DatabaseTable Object returns the ConnectionProperties Collection through the new ConnectionProperties property. Each ConnectionProperty Object represents one of the custom property bags of the database DLL. The property bag contains such things as the name and value of the property. Using these properties, you can read the connection information for the report and then write back new connection information to your report.

Note: Many methods and properties of the DatabaseTable Object, used for connecting to a report’s data source, have been replaced by the properties available in the ConnectionProperty Object. For a complete list of these deprecated calls, see “Deprecated RDC Properties” on page 388 and “Deprecated

RDC Methods” on page 390.

Field elements in text objects

You can now exercise greater control over text objects by adding and removing fields at runtime. You are also able to exercise the same control over the field in the text object as you can with a field outside the text object.

The TextObject Object returns the FieldElements Collection through the new FieldElements property. Using this collection, you can add or delete an embedded field. Each FieldElement Object in the collection provides properties and methods that you can use to customize the embedded field within the text object.

8 Crystal Reports Technical Reference Guide

Cascading Style Sheets

At runtime, you can add a cascading style sheet (CSS) class to each report object and section (Section Object) in a report. Report objects include BlobFieldObject

Object, FieldObject Object, GraphObject Object, and so on. The (CSS) class is used

to apply formatting to reports viewed over the Web. Generally, when you create a report, you format a particular report object (for

example, a database field or a text object) within the Crystal Report Designer. When the report is rendered into HTML and viewed over the web, these formatting options are automatically converted to HTML. To change the formatting of the HTML page, you would need to make a change to the report itself.

The CSS class is set through the CSSClass property, found in the Section object and each of the report objects. This enables you to apply classes to report objects and to sections of a report, instead of manually changing the formatting of the report. You specify the name of the class, and its scope, in the Crystal Report Designer. Then you specify the value of the class through an external style sheet. The external style sheet is then applied to the report when the report is rendered to HTML.

Exporting options

There have been many enhancements to the exporting capability of Crystal Enterprise in this version. The RDC lets you program the new exporting features through properties that have been added to the ExportOptions Object.

2 : What’s New in the RDC

Paginated export to Excel, PDF, RTF, and Word formats

Export your reports—in whole or in part—directly to the popular Portable Document Format (PDF), and then distribute these reports by email, over the Web, or in print. Alternatively, take advantage of the new Rich Text Format (RTF) exporting feature, which is based on the Crystal Reports Encapsulated Page Format (EPF).

In addition, Crystal Reports now supports page-ranged export to Excel, PDF, RTF, and Word formats.

Note: Paginated export to RTF and PDF was introduced in Crystal Reports 8.5. New properties have been added to the ExportOptions Object to support these

new features, they are:

• ExcelExportAllPages

• ExcelFirstPageNumber

• ExcelLastPageNumber

• PDFExportAllPages

• PDFFirstPageNumber

• PDFLastPageNumber

• RTFExportAllPages

Crystal Reports Technical Reference Guide 9

Printing options

• RTFFirstPageNumber

• RTFLastPageNumber.

• WORDWExportAllPages

• WORDWFirstPageNumber

• WORDWLastPageNumber

Additional export options

Additional properties have been added to the ExportOptions Object to enhance exporting to Excel, text formats, and mail destinations.

ExcelConvertDateToString property

Use this property to convert data and date-time fields to string fields when exporting to Excel.

ExcelPageBreaks property

Use this property to add page breaks when exporting to Excel. The page break is in the form of a blank row of cells between exported pages.

MailPassword property and MailUserName property

Use these properties when exporting to the MAPI destination when you are required to provide a user name and password.

UseDefaultCharactersPerInch property and UserDefinedCharactersPerInch property

Use these properties to set the characters per inch when exporting to text. You can allow the default characters per inch by setting the UseDefaultCharactersPerInch property to True, or set your own value through the UserDefinedCharactersPerInch property.

Printing options

Crystal Enterprise continues to improve printing capabilities by adding new methods to the Report Object.

Print to a file

You can now export your report to a printer file using the PrintOutEx Method

(Report Object).

Set a custom paper size

You can now set a custom paper size for your report using the SetUserPaperSize

Method (Report Object).

10 Crystal Reports Technical Reference Guide

Charting options

The following additional properties have been added to the GraphObject Object to enhance charting in the RDC. Refer to the Crystal Reports User’s Guide for more information on charting in Crystal Enterprise.

Automatically scale series axis

The runtime property, EnableAutoScaleSeriesAxis, has been added so that you can automatically scale a series axis.

Set the chart axis title

New runtime properties have been added to allow you to define a title for a chart axis. The new properties are: XAxisTitle, YAxisTitle, and ZAxisTitle.

Default titles for charts

Previously, when you used the Chart Expert to create a chart, the expert didn’t assign a title to the chart unless you specified one. Now, the expert supplies the following titles by default: title, subtitle, footnote, group title, data title, data2 title, series title, x axis title, y axis title, and z axis title.

To support these enhancements, the following new properties have been added to the GraphObject Object for the Report Designer Component at runtime:

• IsTitleByDefault*

• IsSubTitleByDefault*

• IsFootnoteByDefault*

• IsGroupTitleByDefault*

• IsSeriesTitleByDefault*

• IsDataTitleByDefault*

• IsData2TitleByDefault*

• IsXAxisTitleByDefault

• IsYAxisTitleByDefault

• IsZAxisTitleByDefault

* Added in Crystal Enterprise version 8.5.

2 : What’s New in the RDC

Automatically set the series axis range

The new runtime property, AutoRangeSeriesAxis, allows you to automatically set the series axis range.

Set the minimum and maximum series axis values

You can now set the minimum and maximum series axis values using the new runtime properties: MaxSeriesAxisValue and MinSeriesAxisValue.

Set the series axis division method, division number, and number format

You can now set the series axis division method, division number, and number format using the new runtime properties: SeriesAxisDivisionMethod, SeriesAxisDivisionNumber, and SeriesAxisNumberFormat.

Crystal Reports Technical Reference Guide 11

Condition formulas

In version 9, you can now set condition formulas for all report objects, areas (Area

Object), and sections (Section Object) in a report at runtime. Report objects include BlobFieldObject Object, FieldObject Object, GraphObject Object, and so on. This

new feature allows you to set the conditional formula for each of the attributes found in the Format Editor dialog box. This offers you full conditional control over the appearance of the report object area and section. For more information, see “Format Editor dialog box“ in the Crystal Reports Online Help (crw.chm).

The conditions for the Area object, Section object, and report objects, are set through the ConditionFormula property. The type of condition formula is set as a parameter, and the formula is passed as a string.

Group name condition formulas

You can now customize the group names displayed in your report though the GroupNameConditionFormula of the GroupNameFieldDefinition Object.

Source for linked OLE objects

In this version of the RDC, you can now retrieve the path and file name of a linked OLE object using the GetLinkSource Method (OleObject Object).

Additional information

Crystal Reports product news

http://www.crystaldecisions.com/products/crystalreports/

Crystal Reports demos

http://www.crystaldecisions.com/products/crystalreports/showme/

Crystal Enterprise product news

http://www.crystaldecisions.com/products/crystalenterprise/

Product information

http://www.crystaldecisions.com/products/

Developer Zone

http://www.crystaldecisions.com/products/dev_zone/

Online support, samples and tech briefs

http://support.crystaldecisions.com/homepage/

Training and consulting

http://www.crystaldecisions.com/services/

Crystal Decisions homepage

http://www.crystaldecisions.com/homepage/

12 Crystal Reports Technical Reference Guide

Report Designer Component

Object Model 3

The Report Designer Component is the ultimate development tool for your reporting needs. In this chapter you will find a detailed description of the Report Designer Component Object Model and its properties, methods, and events.

Crystal Reports Technical Reference Guide 13

Overview of the Report Designer Object Model

14 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Unification of the RDC object model

Craxddrt.dll (Crystal Reports ActiveX Designer Design and Runtime Library) is a new unified object model that combines the runtime capabilities of the Craxdrt.dll (Crystal Reports ActiveX Designer Run Time Library) with the design time capabilities of the Craxddt.dll (Crystal Reports ActiveX Designer Design Time Library). Craxddrt.dll will replace Craxddt.dll for versions 8.5 and up. Both the Craxddrt.dll and the Craxdrt.dll contain all the objects and associated methods, properties, and events needed for creating, opening, exporting, saving, and printing a report at run time. In addition, Craxddrt.dll is either used with the RDC ActiveX Designer when designing reports at design time, or used with the Embeddable Designer when designing reports at run time. See “Embeddable Crystal Reports

Designer Control Object Model” on page 291 for more information.

Note: The RDC ActiveX Designer is only available in Microsoft Visual Basic. Prior to version 8.5, the Craxdrt.dll would be distributed with an application. Now

the developer has a choice of two automation servers to distribute. Craxdrt.dll is backwards-compatible with previous versions and contains all the new features introduced in this version. Use the Craxdrt.dll for any client-side application that does not contain the Embeddable Designer, or use it for any server-side application. Craxddrt.dll is apartment-model threaded, but is not thread safe, and can only be used in a client-side application. Although the Craxddrt.dll is a fully functional automation server for the RDC, and can work in any client-side application, it will increase the install size. Therefore, it is recommended that you only use Craxddrt.dll with the Embeddable Crystal Reports Designer Control.

Runtime licensing

Your Crystal Reports developer edition license provides the rights to distribute software applications that use or embed most files and functionality of the product, free of charge. In addition, your Crystal Reports developer edition contains new features that provide a great deal more flexibility and power for developers to embed reporting into their applications. These runtime report creation features may only be used and distributed if the appropriate licensing is obtained from Crystal Decisions by paying the required royalty fees. Please refer to the License Manager Help (License.hlp) for lists of features that are royalty-free and royalty-required.

Crystal Reports Technical Reference Guide 15

Object naming conflicts

If your project includes other libraries that contain objects named identical to those found in the Crystal Report Engine Object Library, you will encounter conflicts unless you reference the objects using a prefix. For example, if you have included the DAO Library with the Crystal Report Engine Object Library in your project, both libraries include a Database Object. In order to avoid conflicts, you must prefix the objects as follows:

CRAXDRT.Database

for the Crystal Report Engine Object Library, or

DAO.Database

for the DAO Library.

Objects and Collections

The following Objects and Collections, listed alphabetically, are discussed in this section. Properties, Methods, and Events are listed under the appropriate Object or Collection.

Note: Some of the new report creation calls are not included in the free runtime license included with Crystal Reports. For a list of calls that require additional licensing, please see the License Manager Help (License.hlp).

Creatable Objects

There are several Crystal Reports objects which can be created by passing their Prog Ids into the CreateObject function provided by Visual Basic. The table below lists these objects.

Object Prog Id

Application Object CrystalRuntime.Application ParameterValue Object CrystalRuntime.ParameterValue ParameterValues Collection CrystalRuntime.ParameterValues ParameterValueInfo Object CrystalRuntime.ParameterValueInfo ParameterValueInfos Collection CrystalRuntime.ParameterValueInfos

Note: The version number can be appended to the Prog Id (for example, CrystalRuntime.ParameterValue.9). If the version number is not specified, CreateObject will create the object using the newest version of

16 Crystal Reports Technical Reference Guide

craxdrt.dll

.

Application Object

An instance of the Application object can be created using the Visual Basic New keyword or the CreateObject function and the Prog Id CrystalRuntime.Application.9. For example:

• Using the New keyword

Dim app as New CRAXDRT.Application Set app = New CRAXDRT.Application

Or,

' Automatically creates a new instance of the object when it is first ' referenced in the code, so it doesn’t have to be set. Dim app as New Application

• Using the CreateObject function

' If the version number of the application is not specified, CreateObject ' will create an application running against the new version of ' craxdrt.dll Dim app As Application Set app = CreateObject(“CrystalRuntime.Application”)

Or,

' Specify the version number to require version 8.5 of the dll. Dim app As Application Set app = CreateObject(“CrystalRuntime.Application.8.5”)

3 : Report Designer Component Object Model

Application Object Methods

The following methods are discussed in this section:

• “CanClose Method (Application Object)” on page 17

• “GetLicenseStatus Method (Application Object)” on page 18

• “GetVersion Method (Application Object)” on page 18

• “LogOffServer Method (Application Object)” on page 18

• “LogOnServer Method (Application Object)” on page 19

• “LogOnServerEx Method (Application Object)” on page 20

• “NewReport Method (Application Object)” on page 21

• “OpenReport Method (Application Object)” on page 21

• “SetMatchLogOnInfo Method (Application Object)” on page 22

CanClose Method (Application Object)

The CanClose method indicates whether or not the “Application Object” can be destroyed. This method will return FALSE as long as there are valid Report objects in existence and at least one Report Object is in the printing-in-progress state. The Application object can only be destroyed if no instances of the “Report Object” are in the printing-in-progress state. If you obtain a Report object directly from the Report Designer Component added to your project at design time, then CanClose will always return False until you destroy that object (usually by setting it equal to Nothing).

Crystal Reports Technical Reference Guide 17

Application Object

Syntax

Function CanClose () As Boolean

Returns

• TRUE if the Engine can be closed.

• FALSE if the Engine is busy.

GetLicenseStatus Method (Application Object)

The GetLicenseStatus method is used to get the license number of the Report Creation API License and the current count of licenses in use.

Syntax

GetLicenseStatus(pMaxLicenseNumber, pLicenseUsed) As Boolean

Returns

• True if the license is active and the pLicenseUsed parameter was used in the

call.

• False if the license is not active and the pLicenseUsed parameter was used in

the call.

GetVersion Method (Application Object)

The GetVersion method returns an integer that, when converted to hex, represents the version number of the dll.

Syntax

Function GetVersion () As Integer

Returns

• Returns an integer that represents the version number of the dll when

converted to hexidecimal.

Sample

'Display the version number in a text box. Text1.text = Hex(CRXApplication.GetVersion)

LogOffServer Method (Application Object)

The LogOffServer method logs off an SQL server or other data sources such as ODBC or OLEDB provider. Use this method when you have logged on to the data source using “LogOnServer Method (Application Object)”.

Syntax

Sub LogOffServer (pDllName As String, pServerName As String,

[pDatabaseName], [pUserID], [pPassword])

18 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Parameters

Parameter Description

pDLLName Specifies the name of the DLL for the server or password protected non-SQL

table you want to log on to, for example “PDSODBC.DLL”. Note that the DLLName must be enclosed in quotes. DLL names have the following naming convention: PDB*.DLL for standard (non-SQL) databases, PDS*.DLL for SQL/ODBC databases.

pServerName Specifies the log on name for the server used to create the report. (For ODBC,

use the data source name.) This value is case-sensitive. See Remarks below.

[pDatabaseName] Specifies the name for the database used to create the report. See Remarks

below.

[pUserID] Specifies the User ID number necessary to log on to the server. See Remarks

below.

[pPassword] Specifies the password necessary to log on to the server.

Remarks

• For parameters pServerName, pDatabaseName, and pUserId, pass an empty

string (“”) to preserve the existing setting or pass a non-empty string (for example, “Server A”) to override a value that is already set in the report.

• If you try to log off a server that is still in use (i.e., there is an object variable

still in focus that holds reference to a report that requires being logged on to the server to access data) you will be unable to log off. This will apply to every object that comes from the “Report Object”, as they all hold reference to the report through their respective Report properties.

• If you assign the Report object to the ReportSource property of the “CRViewer

Object (CRVIEWERLib)”, in the Crystal Reports Report Viewer, enabling the

report to be displayed through the Report Viewer, you cannot call LogOffServer for the report until you assign a new report to the Report Viewer or close the CRViewer object.

LogOnServer Method (Application Object)

The LogOnServer method logs on to an SQL server or other data sources such as ODBC. Once logged on using this method, you will remain logged on until you call

“LogOffServer Method (Application Object)”, or until the “Application Object”, is

destroyed and craxdrt.dll is unloaded.

Syntax

Sub LogOnServer (pDllName As String, pServerName As String,

[pDatabaseName], [pUserID], [pPassword])

Crystal Reports Technical Reference Guide 19

Application Object

Parameters

Parameter Description

pDLLName Specifies the name of the DLL for the server or password protected non-SQL

table you want to log on to, for example “PDSODBC.DLL”. Note that the dllName must be enclosed in quotes. DLL names have the following naming convention: PDB*.DLL for standard (non-SQL) databases, PDS*.DLL for SQL/ODBC databases.

pServerName Specifies the log on name for the server used to create the report. (For ODBC,

use the data source name.) This value is case-sensitive. See Remarks below.

[pDatabaseName] Specifies the name for the database used to create the report. See Remarks

below.

[pUserID] Specifies the User ID number necessary to log on to the server. See Remarks

below.

[pPassword] Specifies the password necessary to log on to the server.

*When you pass an empty string (““) for this parameter, the program uses the value that’s already set in the report. If you want to override a value that’s already set in the report, use a non-empty string (that is, “Server A”).

Remarks

For parameters pServerName, pDatabaseName, and pUserId, pass an empty string (“”) to preserve the existing setting or pass a non-empty string (for example, “Server A”) to override a value that is already set in the report.

LogOnServerEx Method (Application Object)

The LogOnServer method logs on to an SQL server or other data sources such as ODBC. Using LogOnServerEx, you can pass server type or connection information. Once logged on using this method, you will remain logged on until you call “LogOffServer Method (Application Object)”, or until the “Application

Object”, is destroyed and craxdrt.dll is unloaded.

Syntax

Sub LogOnServerEx (pDllName As String, pServerName As String,

[pDatabaseName], [pUserID], [pPassword],

[pServerType], [pConnectionString])

20 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Parameters

Parameter Description

pDLLName Specifies the name of the DLL for the server or password protected non-

SQL table you want to log on to, for example “PDSODBC.DLL”. Note that the dllName must be enclosed in quotes. DLL names have the following naming convention: PDB*.DLL for standard (non-SQL) databases, PDS*.DLL for SQL/ODBC databases.

pServerName Specifies the log on name for the server used to create the report. (For

ODBC, use the data source name.) This value is case-sensitive. See Remarks below.

[pDatabaseName] Specifies the name for the database used to create the report. See Remarks

below.

[pUserID] Specifies the User ID number necessary to log on to the server. See

Remarks below. [pPassword] Specifies the password necessary to log on to the server. [pServerType] Specifies the database Server Type. [pConnectionString] Specifies the connection string.

NewReport Method (Application Object)

The NewReport method creates a new empty Report Object.

Syntax

Function NewReport () As Report

Returns

• Returns a new empty Report Object.

OpenReport Method (Application Object)

The OpenReport method opens an existing report file, creating an instance of the Report object. Through the “Report Object”, you can change formatting, formulas, selection formulas, and sort fields for the report, then print, preview, or export the report.

Syntax

Function OpenReport (pFileName As String, [OpenMethod]) As Report

Crystal Reports Technical Reference Guide 21

Area Object

Parameters

Parameter Description

pFileName Specifies a string value indicating the file name and path of

the report that you want to open.

OpenMethod “CROpenReportMethod”. Specifies whether you want to

open the report exclusively. If you do not provide this parameter the report is opened exclusively and it cannot be opened a second time.

Returns

• Returns an instance of the “Report Object” if the report was successfully

opened.

• Returns 0 if the report file does not exist or if an error occurs.

Remarks

• The OpenMethod parameter can take the values “0” (open by default) or “1”

(open temporary copy).

SetMatchLogOnInfo Method (Application Object)

The SetMatchLogOnInfo Method sets global match log on info option, matching the log on password.

Syntax

Sub SetMatchLogOnInfo (bl As Boolean)

Parameter

Parameter Description

bl Specifies whether the option is selected (TRUE).

Area Object

The Area Object represents an area in a report. An area is a group of like sections in the report (i.e., Details A - Da, Details B - Db, etc.) that all share the same characteristics. Each section within the area can be formatted differently. This object allows you to retrieve information and set options for a specified area in your report.

22 Crystal Reports Technical Reference Guide

Area Object Properties

3 : Report Designer Component Object Model

Property Description

CopiesToPrint Integer. Gets or sets the number of copies

of each item in the Details section of the

Read/ Write

Read/

Wri te report. For example, by default, each line of the Details section only prints once. By setting this to 3, each line of the Details section would print 3 times.

DetailHeight Long. Gets the mailing label report detail

area height, in twips.

DetailWidth Long. Gets multiple column report detail

area width, in twips.

DiscardOther Groups

EnableHierarchical GroupSorting

Boolean. Gets or sets the discard other groups option.

Boolean. Gets or sets group hierarchically flag.

GroupCondition “CRGroupCondition”. Gets or sets the

group condition.

GroupCondition Field

Object. Gets or sets the group condition field.

Read

only

Read

only

Read/

Wri te

Read/

Wri te

Read/

Wri te

Read/

Wri te

GroupIndent Long. Gets or sets group indent, in twips. Read/

Wri te

GroupNumber Integer. If the area is a group area, this

returns the group number. Otherwise,

Read

only exception is thrown.

HideForDrillDown Boolean. Gets or sets hide for drill down

option.

HorizontalGap Long. Gets the horizontal gaps going

across page in a multiple column report.

InstanceIDField A field definition object. Gets the instance

ID field. See Remarks.

KeepGroup To ge th er

Boolean. Gets or sets the keep group together option.

KeepTogether Boolean. Gets or sets the keep area

together option.

Kind “CRAreaKind”. Gets which kind of area

(for example, Details, Report Header,

Read/

Wri te

Read

only

Read

only

Read/

Wri te

Read/

Wri te

Read

only Page Footer, etc.).

Name String. Gets or sets the area name. Read/

Wri te

Restriction in event handler

Can be written only when formatting idle.

None

Formatting idle.

Can be written only when formatting idle.

Formatting idle.

None

Can be written only when formatting idle.

None

Formatting idle.

Can be written only when formatting idle.

None

Can be written only when formatting idle.

Crystal Reports Technical Reference Guide 23

Area Object

Property Description

NewPageAfter Boolean. Gets or sets the new page after

options.

NewPageBefore Boolean. Gets or sets the new page before

option.

NumberOfTopOr BottomNGroups

Parent “Report Object”. Gets reference to the

ParentIDField A field definition object. Gets the parent

PrintAtBottomOf Page

RepeatGroup Header

ResetPageNumber After

Sections “Sections Collection”. Gets a Collection of

SortDirection “CRSortDirection”. Gets or sets the group

SpecifiedGroups Gets or sets the specified groups. Read/

Suppress Boolean. Gets or sets the area visibility. Read/

TopOrBottomN GroupSortOrder

TopOrBottomN SortField

Integer. Gets or sets the number of top or bottom groups.

parent object.

ID field. See Remarks. Boolean. Gets or sets the print at bottom of

page option. Boolean. Gets or sets the repeating group

header option. Boolean. Gets or sets the reset page

number after option.

all the sections in the area.

sort direction.

“CRTopOrBottomNGroupSortOrder”.

Gets or sets the top or bottom N group sort order.

“SummaryFieldDefinition Object”. Gets

or sets the top or bottom n sort field.

Read/ Write

Read/ Wri te

Read Only

Read only

Read/ Wri te

Read Only

Read/ Wri te

Wri te

Wri te Read/

Wri te

Read/ Wri te

Restriction in event handler

Can be written only when formatting idle.

Formatting idle.

None

Formatting idle.

Can be written only when formatting idle.

None

Can be written only when formatting idle.

Formatting idle.

Remarks

After getting the field definition object from the InstanceIDField or the ParentIDField property, you can use the Kind property to determine what type of field definition object it is. All field definition objects have the Kind property.

Area Object Methods

The following methods are discussed in this section:

• “SetInstanceIDField Method (Area Object)” on page 25

• “SetParentIDField (Area Object)” on page 25

24 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

SetInstanceIDField Method (Area Object)

Use the SetInstanceIDField method to set an instance ID field.

Syntax

Sub SetInstanceIDField (InstanceIDField)

Parameter

Parameter Description

InstanceIDField Specifies the instance ID field that you want to set.

SetParentIDField (Area Object)

Use the SetParentIDField method to set the parent ID field.

Syntax

Sub SetParentIDField (ParentIDField)

Parameter

Parameter Description

ParentIDField Specifies the parent ID field that you want to set.

Areas Collection

The Areas Collection contains the area objects for every area in the report. Access a specific “Area Object”in the collection using the Item property.

Areas Collection Properties

Property Description

Read/ Write

Count Long. Gets the number of areas in the collection. Read only None Item

(index)

“Area Object”. Gets an item from the Collection. Item

has an index parameter that can be either a string

Read only None

reference to the area (for example, “RH”, “PH”, “GHn”, “D”, “GFn”, “PF”, or “RF”) or a numeric, 1based index (for example, Item (1) for the Report Header area). The items in the collection are indexed in the order they are listed for each section/area.

Parent “Report Object”. Gets reference to the parent object. Read only None

Crystal Reports Technical Reference Guide 25

Restriction in event handler

BlobFieldObject Object

Remarks

Instead of using the Item property as shown, you can reference an area directly (for example, Areas(“RH”) or Areas(1)).

BlobFieldObject Object

The BlobFieldObject Object allows you to get and set information for bitmap database fields in a report.

BlobFieldObject Object Properties

Examples

“How to format a blob field object” on page 182

Property Description

BackColor OLE_COLOR. Gets or sets the object

background color.

BorderColor OLE_COLOR. Gets or sets the object

border color.

Bottom Cropping

BottomLineStyle “CRLineStyle”. Gets or sets the bottom

CloseAtPage Break

Condition Formula

CssClass String. Gets or sets the cascading style

Field “DatabaseFieldDefinition Object”. Gets

HasDrop Shadow

Long. Gets or sets bottom cropping size, in twips.

line style. Boolean. Gets or sets the close border on

page break. String. Gets or sets the condition formula.

The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables.

sheet Class.

the database field definition object containing information about the BLOB field.

Boolean. Gets or sets the border drop shadow option.

Read/ Write

Read only

Read/ Write

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

None

Can be written only when formatting idle or active.

26 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Property Description

Height Long. Gets or sets the object height, in

twips.

KeepTogether Boolean. Gets or sets the keep object

together option.

Kind “CRObjectKind”. Gets CRObjectKind

which specifies the kind of object (for

Read/ Write

Read only

example, box, cross-tab, field, etc.).

Left Long. Gets or sets the object upper left

position, in twips.

LeftCropping Long. Gets or sets the left cropping size,

in twips.

LeftLineStyle “CRLineStyle”. Gets or sets the left line

style.

Read/ Write

Name String. Gets or sets the object name. Read/

Write

Parent “Section Object”. Gets reference to the

parent object.

RightCropping Long. Gets or sets the right cropping size,

in twips.

RightLineStyle “CRLineStyle”. Gets or sets the right line

style.

Read only

Read/ Write

Suppress Boolean. Gets or sets the object visibility. Read/

Write

Top Long. Gets or sets the object upper top

position, in twips.

TopCropping Long. Gets or sets the top cropping size,

in twips.

TopLineStyle “CRLineStyle”. Gets or sets the top line

style.

Width Long. Gets or sets the object width, in

twips.

XScaling Double. Gets or sets the width scaling

factor. For example, 1 means 100%, 2

Read/ Write

Read/

Write means 200%, 0.5 means 50% etc. The scaling factor may range from 0.01 to 100.

YScaling Double. Gets or sets the height scaling

factor. For example, 1 means 100%, 2

Read/

Write means 200%, 0.5 means 50% etc. The scaling factor may range from 0.01 to 100.

Restriction in event handler

Can be written only when formatting idle or active.

None

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

None

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Crystal Reports Technical Reference Guide 27

BoxObject Object

The Box Object represents a box that has been drawn on the report. This object allows you to get information about boxes in a report.

BoxObject Object Properties

Examples

“How to format a box object” on page 184

Property Description

Bottom Long. Gets or sets the object

lower bottom position, in twips.

BottomRightSection “Section Object”. Gets the

bottom right section.

CloseAtPageBreak Boolean. Gets or sets the close

border on page break option.

ConditionFormula String. Gets or sets the

condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or printtime formulas. Condition formulas cannot have shared variables.

CornerEllipseHeight Long. Gets or sets the corner

elipse height, in twips.

CornerEllipseWidth Long. Gets or sets the corner

elipse width, in twips.

CssClass String. Gets or sets the

cascading style sheet Class.

ExtendToBottomOf Section

FillColor OLE_COLOR. Gets or sets the

HasDropShadow Boolean. Gets or sets the border

Boolean. Gets or sets the extend to bottom of section option.

fill color.

drop shadow option..

Read/ Write

Read only

Read/ Write

Restriction in event handler

Can be written only when formatting idle.

28 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Property Description

Kind “CRObjectKind”. Gets which

kind of object (for example, box, cross-tab, field, etc.).

Left Long. Gets or sets the upper left

position, in twips.

LineColor OLE_COLOR. Gets or sets the

line color.

LineStyle “CRLineStyle”. Gets or sets the

line style.

LineThickness Long. Gets or sets the line

thickness, in twips.

Name String. Gets or sets the object

name.

Parent “Section Object”. Gets reference

to the parent object.

Right Long. Gets or sets the object

lower right position, in twips.

Suppress Boolean. Gets or sets the object

visibility.

Top Long. Gets or sets the object

upper top position, in twips.

Read/ Write

Read only

Read/ Write

Read only

Read/ Write

Restriction in event handler

None

Can be written only when formatting idle or active.

Can be written only when formatting idle.

None

Can be written only when formatting idle.

ConnectionProperty Object

The ConnectionProperty Object is a property bag that stores connection information for the report. Information is dependent on the Crystal Decisions database DLL used by the report and the database drivers that support the DLL. The collection of ConnectionProperty objects can hold common properties defined in our database DLLs, connection properties from the supporting drivers, or both. For example a report based off an OLEDB (ADO) connection to Microsoft SQL Server will contain properties supplied by the database DLL (crdb_ado.dll) such as Provider, Data Source, Initial Catalog, User ID, and Password, as well as the properties supplied by the supporting drivers such as Local Identifier, Connect Timeout and so on. The values for these properties can be set to connect to the current data source for the report or to change the data source for the report.

For more information on the common connection properties see “Common

Connection Properties” on page 30.

Crystal Reports Technical Reference Guide 29

ConnectionProperty Object

ConnectionProperty Object Properties

Examples

“How to connect to a Microsoft Access database” on page 171 “How to connect to a secured Microsoft Access database” on page 173 “How to connect to an ODBC data source” on page 175 “How to connect to an OLEDB data source” on page 177 “How to change the data source” on page 178 “How to list the connection properties and connect to a report” on page 179

Property Description

ChildProperties “ConnectionProperties Collection”. Gets the

child properties of this connection property in a hierarchal property structure.

Description String. Gets or sets the description of the

connection property.

LocalizedName String. Gets or sets the localized name of the

connection property.

Name String. Gets or sets the name of the connection

property.

Value Variant. Gets or Sets the value of the connection

property. Note: Some Values are Write only. For example

the value for the Password connection property.

Common Connection Properties

The following table lists the connection properties defined in the Crystal Decisions database DLLs. Use these properties when connecting to the desired data source.

Data source

ODBC (RDO) crdb_odbc.dll

Connection property name

Connection String

Connection property value description

String. The complete connection string containting the driver information. This can be obtained from content of a File DSN.

Read/ Write

Read only

Read/ Write

Remarks

DSN, FILEDSN and Connection String are mutually exclusive

Restriction in event handler

None

30 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Data source

OLE DB (ADO) crdb_ado.dll

Connection property name

Database String. The name of the

Connection property value description

database.

Remarks

This property can be used together with the DSN, FILEDSN, and Connection String.

Database Type String. The type of file. For

example:

This is an optional property.

ODBC (RDO)

- or OLE DB (ADO)

DSN String. The ODBC data sourec

name.

DSN, FILEDSN and Connection String are mutually exclusive.

FILEDSN String. Path to the File DSN. DSN, FILEDSN and

Connection String are mutually exclusive

Password String. The password used to

connect to the data source.

This property can be used together with the DSN, FILEDSN, and Connection String.

Tr us te d_ Connection

Boolean. Set to True if you want the connection to use NT Authentication.

This property can be used together with the DSN, FILEDSN, and Connection String.

User ID String. The user name

required to connect to the data source.

This property can be used together with the DSN, FILEDSN, and Connection String.

Data Source String. The data source that

the OLE DB provider is connected to such as a file path and database name or a server

This property can be used together with the Provider and Microsoft Data Link File.

name.

Database String. The name of the

database.

This property can be used together with the Provider and Microsoft Data Link File.

Database Type String. The type of file. For

example:

This is an optional property.

ODBC (RDO)

- or OLE DB (ADO)

Crystal Reports Technical Reference Guide 31

ConnectionProperty Object

Data source

Access/Excel (DAO) crdb_dao.dll

Connection property name

Integrated Security

Connection property value description

Boolean. Set to True if you want the connection to use NT Authentication.

Microsoft Data Link File

String. The file path to the Data Link.

Password String. The password used to

connect to the data source.

Provider The name of the OLEDB

provider. For example: Microsoft.Jet.OLEDB.4.0

-orSQLOLEDB

User ID String. The user name

required to connect to the data source.

Database Name

Database Password

String. The full file path to the databse.

String. The password used to connect to the data source.

Database Type String. The type of file. For

example: ODBC (RDO)

- or OLE DB (ADO)

Session Password

Session UserID

String. The password for a system DSN.

String. The user name for a system DSN.

Remarks

This property can be used together with the Provider and Microsoft Data Link File.

Provider and Microsoft Data Link File are mutually exclusive.

This property can be used together with the Provider and Microsoft Data Link File.

Provider and Microsoft Data Link File are mutually exclusive.

This property can be used together with the Provider and Microsoft Data Link File.

This property is required for changing the location and name of the database.

This property is only required if the daabse has database level security.

This is an optional property.

You must provide System Database Path if Session UserID and Session Password are provided.

32 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Data source

Oracle crdb_oracle.dll

Native connections to local databases. crdb_p2b*.dll

Native connections to server data sources. crdb_p2s*.dll

Connection property name

System

Connection property value description

String. You must provide System

Database Path

Database Type String. The type of file. For

example: ODBC (RDO)

- or -

OLE DB (ADO) Server String. The Service name. Password String. The password used to

connect to the data source. User ID String. The user name

required to connect to the data

source.

Database Path String. The full file path to the

database.

Database Type String. The type of file. For

example:

ODBC (RDO)

- or -

OLE DB (ADO) Password String. The password used to

connect to the data source. User ID String. The user name

required to connect to the data

source.

Database String. The database name.

Remarks

Database Path if Session UserID and Session Password are provided.

This is an optional property.

These include Act!, Btrieve, DB2, Dbase, FoxPro, Paradox and so on.

This property is required for changing the location and name of the database.

This is an optional property.

These include Informix, DB2 Server, Lotus Domino, and so on.

Crystal Reports Technical Reference Guide 33

ConnectionProperty Object

Data source

Field Definitions Only crdb_fielddef.dll

File Systam Data crdb_FileSystem.dll

Connection property name

Connection property value description

Database Type String. The type of file. For

example: ODBC (RDO)

- or -

OLE DB (ADO) Server String. The server name. Password String. The password used to

connect to the data source. User ID String. The user name

required to connect to the data

source.

Database Type String. The type of file. For

example:

ODBC (RDO)

- or -

OLE DB (ADO) Field

Definition File

String. The full file and path to

the Field defintion file (*.ttx).

Database Type String. The type of file. For

example:

ODBC (RDO)

- or -

OLE DB (ADO) File Mask String. A mask to filter the

types of files returned. For

example:

*.exe Include Empty

Directories Max Number

of Subdirectory

Boolean. Set to True to include

empty directories.

Integer. The number of

subdirectory levels to include. Levels

Starting Directory

String. The path to the starting

directory.

Remarks

This is an optional property.

Set this value to -1 to include all subdirectories.

34 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

ConnectionProperties Collection

The ConnectionProperties Collection is a collection of “ConnectionProperty

Object” in a report. Each object in the collection is a property bag that contains

information on a connection property. Use the Item property to access a specific ConnectionProperty Object in the Collection.

For more information on the common connection properties see “Common

Connection Properties” on page 30.

ConnectionProperties Collection Properties

Examples

“How to connect to a Microsoft Access database” on page 171 “How to connect to a secured Microsoft Access database” on page 173 “How to connect to an ODBC data source” on page 175 “How to connect to an OLEDB data source” on page 177 “How to change the data source” on page 178 “How to list the connection properties and connect to a report” on page 179

Property Definition

Count Long. Gets the number of objects in the collection. Read

Item (indexAs Long)

NameIds Variant. Returns an array containing the name of each

“ConnectionProperty Object”. Gets an item from the

Collection specified by name.

connection property in the collection.

Read/ Write

only Read

only

Read only

Restriction in event handler

None

ConnectionProperties Collection Methods

The following methods are discussed in this section:

• “Add Method (ConnectionProperties Collection)” on page 35

• “Delete Method (ConnectionProperties Collection)” on page 36

• “DeleteAll Method (ConnectionProperties Collection)” on page 37

Add Method (ConnectionProperties Collection)

Use the Add method to add a ConnectionProperty Object to the Collection as a name value pair.

Crystal Reports Technical Reference Guide 35

ConnectionProperties Collection

Examples

“How to change the data source” on page 178

Syntax

Function Add (Name As String, Value)

Parameter Description

Name Specifies the name of the connection property that you want to

Value Specifies the value of the connection property.

Remarks

Use this method if alternate connection properties are required to establish a connection to a new data source. For example changing the report’s database driver through the DLLName property in the “DatabaseTable Object”, or connecting to a report created off an OLEDB (ADO) data source to a different provider (Microsoft.Jet.OLEDB.4.0 to SQLOLEDB). Use the “Delete Method

(ConnectionProperties Collection)” or the “DeleteAll Method (ConnectionProperties Collection)”to remove any connection properties.

Delete Method (ConnectionProperties Collection)

Use the Delete method to remove a ConnectionProperty Object from the Collection.

add to the Collection.

Examples

“How to change the data source” on page 178

Syntax

Sub Delete (index)

Parameter

Parameter Description

index Specifies the index number of the Object that you want to remove

from the Collection.

Remarks

Use this method to remove any connection properties that are no longer required when connecting to a new data source. For example changing the report’s database driver through the DLLName property in the “DatabaseTable Object”, or connecting a report created off an OLEDB (ADO) data source to a different provider (Microsoft.Jet.OLEDB.4.0 to SQLOLEDB). Use the “Add Method

(ConnectionProperties Collection)” to add any new connection properties.

36 Crystal Reports Technical Reference Guide

DeleteAll Method (ConnectionProperties Collection)

Use the Delete method to remove all ConnectionProperty Objects from the Collection.

Examples

“How to change the data source” on page 178

Syntax

Sub DeleteAll ()

Remarks

Use this method to remove all existing connection properties when connecting to a new data source. For example changing the report’s database driver through the DLLName property in the “DatabaseTable Object”, or connecting a report created off an OLEDB (ADO) data source to a different provider (Microsoft.Jet.OLEDB.4.0 to SQLOLEDB). Use the “Add Method (ConnectionProperties Collection)” to add any new connection properties.

CrossTabGroup Object

The CrossTabGroup Object contains information related to CrossTabGroups in a report.

3 : Report Designer Component Object Model

CrossTabGroup Properties

Examples

“How to add, delete and format groups in a crosstab” on page 197

Property Description Read/Write Restriction in event handler

BackColor OLE_COLOR. Gets or sets the

crosstab group background color.

Condition “CRGroupCondition”. Gets or

sets the crosstab group condition.

EnableSuppress Label

EnableSuppress Subtotal

Crystal Reports Technical Reference Guide 37

Boolean. Gets or sets the crosstab group enable suppress label option.

Boolean. Gets or sets the crosstab group enable suppress subtotal option.

Read/Write Idle

CrossTabGroups Collection

Property Description Read/Write Restriction in event handler

Field A field definition object. Gets

or sets the crosstab group’s field. See Remarks.

Parent “CrossTabObject Object”. Gets

reference to the crosstab group parent object.

SortDirection “CRSortDirection”. Gets or sets

the crosstab group sort direction.

Remarks

After getting the field definition object from the Field property, you can use the Kind property to determine what type of field definition object it is. All field definition objects have the Kind property.

Read/Write Idle

Read only None

Read/Write Idle

CrossTabGroups Collection

The CrossTabGroups Collection contains CrossTabGroup Objects associated with a report.

CrossTabGroups Collection Properties

Property Description Read/Write Restriction in event handler

Count Long. Gets the CrossTabGroup

count.

Item (index As Long)

Parent “CrossTabObject Object”. Gets

“CrossTabGroup Object”. Gets

an item from the Collection.

reference to the parent object.

Read only None

CrossTabGroups Collection Methods

The following methods are discussed in this section:

• “Add Method (CrossTabGroups Collection)” on page 39

• “Delete Method (CrossTabGroups Collection)” on page 39

38 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Add Method (CrossTabGroups Collection)

Examples

“How to add, delete and format groups in a crosstab” on page 197

Use the Add method to add a field as a CrossTabGroup to the CrossTabGroups Collection.

Syntax

Function Add (Field) As CrossTabGroup

Parameter

Parameter Description

Field Specifies the field that you want to add as a CrossTabGroup to

the Collection.

Returns

Returns a CrossTabGroup Object member of the Collection.

Delete Method (CrossTabGroups Collection)

Examples

“How to add, delete and format groups in a crosstab” on page 197

Use the Delete method to remove a CrossTabGroup Object from the Collection.

Syntax

Sub Delete (index As Long)

Parameter

Parameter Description

index Specifies the index of the CrossTabGroup Object that you want

to delete from the Collection.

Crystal Reports Technical Reference Guide 39

CrossTabObject Object

The CrossTabObject Object allows you to get and set information for cross-tab objects in a report.

CrossTabObject Object Properties

Property Description Read/Write Restriction in event handler

BackColor OLE_COLOR. Gets or sets

the object background color.

BorderColor OLE_COLOR. Gets or sets

the object border color.

BottomLineStyle “CRLineStyle”. Gets or sets

the bottom line style.

CloseAtPageBreak Boolean. Gets or sets the close

border on page break option.

ConditionFormula String. Gets or sets the

condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables.

ColumnGrand TotalColor

ColumnGroups “Remarks”. Gets the column

CssClass String. Gets or sets the

EnableKeep ColumnsTogether

EnableRepeatRow Labels

EnableShowCell Margins

EnableShowGrid Boolean. Gets or sets the

OLE_COLOR. Gets or sets the column grand total color.

groups Collection.

cascading style sheet Class. Boolean. Gets or sets the

enable keep columns together option.

Boolean. Gets or sets the enable repeat row labels option.

Boolean. Gets or sets the enable show cell margins option.

enable show grid option.

Read/Write Can be written only when

formatting idle or active.

Read/Write Can be written only when

formatting idle or active.

Read/Write Can be written only when

formatting idle or active.

Read/Write Can be written only when

formatting idle or active.

Read/Write Can be written only when

formatting idle.

Read/Write Idle

Read only None

Read/Write Can be written only when

formatting idle.

Read/Write Idle

40 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Property Description Read/Write Restriction in event handler

EnableSuppress ColumnGrand Totals

EnableSuppress EmptyColumns

Boolean. Gets or sets the enable suppress column grand totals option.

Boolean. Gets or sets the enable suppress empty

Read/Write Idle

columns option.

EnableSuppress EmptyRows

Boolean. Gets or sets the enable suppress empty rows

Read/Write Idle

option.

EnableSuppress RowGrandTotals

Boolean. Gets or sets the enable suppress row grand

Read/Write Idle

totals option.

HasDropShadow Boolean. Gets or sets the

border drop shadow option.

Height Long. Gets the object height,

in twips.

KeepTogether Boolean. Gets or sets the keep

object together option.

Kind “CRObjectKind”. Gets which

Read/Write Can be written only when

formatting idle or active.

Read only Can be written only when

formatting idle or active.

Read/Write Can be written only when

formatting idle or active.

Read only None kind of object (for example, box, cross-tab, field, etc.).

Left Long. Gets or sets the upper

left position, in twips.

LeftLineStyle “CRLineStyle”. Gets or sets

the left line style.

Name String. Gets or sets the object

name.

Parent “Section Object”. Gets

Read/Write Can be written only when

formatting idle or active.

Read/Write Can be written only when

formatting idle or active.

Read/Write Can be written only when

formatting idle.

Read only None reference to the parent object.

RightLineStyle “CRLineStyle”. Gets or sets

the right line style.

RowGrandTotal Color

OLE_COLOR. Gets or sets the row grand total color.

RowGroups “Remarks”. Gets the row

Read/Write Can be written only when

formatting idle or active.

Read/Write Idle

Read Only None groups Collection.

SummaryFields “ObjectSummaryFieldDefinit

Read Only None

ions Collection”. Gets the

summary fields.

SpecifiedGroups Gets or sets the specified

groups from a row or column

Read/Write Can be written only when

formatting idle

in the crosstab.

Crystal Reports Technical Reference Guide 41

Database Object

Property Description Read/Write Restriction in event handler

Suppress Boolean. Gets or sets the

object visibility option.

Top Long. Gets or sets the object

upper top position, in twips.

To pL in e St yl e “CRLineStyle”. Gets or sets

top line style.

Width Long. Gets the object width,

in twips.

Read/Write Can be written only when

formatting idle or active.

Read/Write Can be written only when

formatting idle or active.

Read/Write Can be written only when

formatting idle or active.

Read Only Can be written only when

formatting idle or active.

Database Object

The Database Object provides properties to get information about the database accessed by a report. See “Overview of the Report Designer Object Model” on

page 14.

Database Object Properties

Property Description

ConnectionProperties “ConnectionProperties Collection”. Gets

the collection of connection properties from the table.

Links “TableLinks Collection”. Gets database

link collection.

Parent “Report Object”. Gets reference to the

parent object.

Ta bl es “DatabaseTables Collection”. Gets the

DatabaseTables Collection which specifies the database objects used in the report (for example, an Access report may contain a query or a SQL Server report may be based on a stored procedure - if so, they will be returned as part of this collection along with the database table used in the report).

Read/ Write

Read only None.

Read only None

Restriction in event handler

42 Crystal Reports Technical Reference Guide

Database Object Methods

The following methods are discussed in this section:

• “AddADOCommand Method (Database Object)” on page 43

• “AddOLEDBSource Method (Database Object)” on page 43

• “LogOffServer Method (Database Object)” on page 44

• “LogOnServer Method (Database Object)” on page 45

• “LogOnServerEx Method (Application Object)” on page 20

• “SetDataSource Method (Database Object)” on page 47

• “Verify Method (Database Object)” on page 47

AddADOCommand Method (Database Object)

Use the AddADOCommand method to add a database table to your report through an ADO connection and command.

Syntax

Sub AddADOCommand (pConnection, pCommand)

Parameters

Parameter Description

pConnection Specifies the ADO connection that you want to use. pCommand Specifies the ADO command that you want to use.

3 : Report Designer Component Object Model

AddOLEDBSource Method (Database Object)

Use the AddOLEDBSource method to add a database table to your report through an OLE DB provider.

Syntax

Sub AddOLEDBSource (pConnectionString As String, pTableName As String)

Parameters

Parameter Description

pConnectionString Specifies the connection string for the OLE DB provider. pTableName Specifies the OLE DB database table that you want to

add to your report.

Remarks

Some databases such as Oracle are case sensitive and require that proper case be applied to the database names and table names in the connection string.

Crystal Reports Technical Reference Guide 43

Database Object

'Instantiate the report object. Set m_Report = New CrystalReport1

' Convert the database driver to ODBC. m_Report.Database.ConvertDatabaseDriver "p2sodbc.dll", True

' Set the logon information for the ODBC data source. ' If the logon information is not set, an error will be produced when the ' report is previewed or exported. m_Report.Database.Tables(1).SetLogOnInfo "Xtreme Sample Database", "", "", ""

' Verify the database. ' If the database is not verified before exporting, an error will be produced. ' If the database is not verified before previewing the report, the user may be ' prompted when the report is refreshed in the Crystal Report Viewer. m_Report.Database.Verify

LogOffServer Method (Database Object)

The LogOffServer method logs off an SQL server, ODBC or other data source. Use this method when you have logged on to the data source using LogOnServer. This method can be invoked only in formatting Idle mode.

Syntax

Sub LogOffServer (pDllName As String, pServerName As String,

[pDatabaseName], [pUserID], [pPassword])

Parameters

Parameter Description

pDllName Specifies the name of the DLL for the server or password protected non-SQL

table you want to log on to, for example "PDSODBC.DLL". Note that the dllName must be enclosed in quotes. DLL names have the following naming convention: PDB*.DLL for standard (non-SQL) databases, PDS*.DLL for SQL/ODBC databases.

pServerName Specifies the log on name for the server used to create the report. For ODBC,

use the data source name. This value is case-sensitive. See Remarks below. [pDatabaseName] Specifies the name for the database used to create the report. See Remarks below. [pUserID] Specifies the User ID number necessary to log on to the server. See Remarks

below. [pPassword] Specifies the password necessary to log on to the server.

44 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Remarks

• When you pass an empty string ("") for pServerName, pDatabaseName, or

pUserID, the program uses the value that's already set in the report. If you want to override a value that's already set in the report, use a non-empty string (for example, "Server A").

• If you try to log off a server that is still in use (that is, there is an object variable

still in focus that holds reference to a report that requires being logged on to the server to access data) you will be unable to log off. This will apply to every object that comes from the “Report Object”, as they all hold reference to the report through their respective Report properties.

• If you assign the Report object to the ReportSource property of the “CRViewer

Object (CRVIEWERLib)”, in the Crystal Reports Report Viewer, enabling the

report to be displayed through the Report Viewer, you cannot call LogOffServer for the report until you assign a new report to the Report Viewer or close the CRViewer object.

LogOnServer Method (Database Object)

The LogOnServer method logs on to an SQL server, ODBC or other data source. Once logged on using this method, you will remain logged on until you call LogOffServer or until the Application Object is destroyed and craxdrt.dll is unloaded. This method can be invoked only in formatting Idle mode.

Syntax

Sub LogOnServer (pDllName As String, pServerName As String,

[pDatabaseName], [pUserID], [pPassword])

Parameters

Parameter Description

pDllName Specifies the name of the DLL for the server or password protected non-

SQL table you want to log on to, for example "PDSODBC.DLL". Note that the dllName must be enclosed in quotes. DLL names have the following naming convention: PDB*.DLL for standard (non-SQL) databases, PDS*.DLL for SQL/ODBC databases.

pServerName Specifies the log on name for the server used to create the report. For ODBC,

use the data source name. This value is case-sensitive. See Remarks below.

[pDatabaseName] Specifies the name for the database used to create the report. See Remarks

below.

[pUserID] Specifies the User ID number necessary to log on to the server. See Remarks

below.

[pPassword] Specifies the password necessary to log on to the server.

Crystal Reports Technical Reference Guide 45

Database Object

Remarks

When you pass an empty string ("") for this parameter, the program uses the value that's already set in the report. If you want to override a value that's already set in the report, use a non-empty string (for example, "Server A").

LogOnServerEx Method (Database Object)

The LogOnServerEx method logs on to an SQL server, ODBC or other data source. Using this method, you can pass ServerType and ConnectionString info. Once logged on using this method, you will remain logged on until you call LogOffServer or until the Application Object is destroyed and craxdrt.dll is unloaded. This method can be invoked only in formatting Idle mode.

Syntax

Sub LogOnServerEx (pDllName As String, pServerName As String,

[pDatabaseName], [pUserID], [pPassword], [pServerType], [pConnectionString])

Parameters

Parameter Description

pDllName Specifies the name of the DLL for the server or password protected non-

pServerName Specifies the log on name for the server used to create the report. For

[pDatabaseName] Specifies the name for the database used to create the report. See Remarks

[pUserID] Specifies the User ID number necessary to log on to the server. See

[pPassword] Specifies the password necessary to log on to the server. [pServerType] Specifies the database Server Type. [pConnectionString] Specifies the connection string.

SQL table you want to log on to, for example "PDSODBC.DLL". Note that the dllName must be enclosed in quotes. DLL names have the following naming convention: PDB*.DLL for standard (non-SQL) databases, PDS*.DLL for SQL/ODBC databases.

ODBC, use the data source name. This value is case-sensitive. See Remarks below.

below.

Remarks below.

Remarks

When you pass an empty string ("") for this parameter, the program uses the value that's already set in the report. If you want to override a value that's already set in the report, use a non-empty string (for example, "Server A").

46 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

SetDataSource Method (Database Object)

The SetDataSource method is used to provide information about a data source to the database driver associated with this Database object at runtime. For instance, if a report has been designed using the Crystal Active Data Driver this method can be used to provide an active data source for the report, such as a DAO, ADO, or RDO Recordset or a CDO Rowset. In this case, the object passed to the second parameter of this method replaces, at runtime, the field definition file used to create the report. This method can be invoked only in formatting Idle mode. When using a secure connection such as SQL Server, some additional code is required (see Remarks below).

Syntax

Sub SetDataSource (data, [dataTag], [tableNumber])

Parameters

Parameter Description

data Variant data passed to the database driver. For example, with Active data, this

must be a Recordset object if you are using DAO, ADO, or the Visual Basic data control. This must be a Rowset object if you are using CDO.

[dataTag] A value indicating the type of data being passed to the DatabaseTable object

[tableNumber] Specifies the index number of the table to be set. Default value = 1.

in the Data parameter. Currently, the only possible value is 3. This value must be used for all Active data sources including DAO, ADO, RDO, CDO, and the Visual Basic data control.

Remarks

• When the data source uses a secure connection, such as SQL Server, additional

information must be passed in the "form load" event before the call to view the report. For example,

DataEnvironment1.Command1 Report.Database.SetDataSource (DataEnvironment1.rsCommand1)

• SetDataSource method is used to set a datasource at runtime. If the report is

initially created and then saved, and then later run using either the RDC or CRW, the runtime datasource (DAO, ADO, or RDO Recordset) cannot be recreated. The user will not be able to run or preview the report.

Verify Method (Database Object)

The Verify method verifies that the location of the database is still valid and checks to see if any changes have been made to table design, etc. If there are any changes to the database, the Verify method will update the report automatically to reflect these changes. See Remarks below. This method can be invoked only in formatting Idle mode.

Crystal Reports Technical Reference Guide 47

DatabaseFieldDefinition Object

Syntax

Sub Verify ()

Remarks

Prior to calling Verify, you can use the “CheckDifferences Method (DatabaseTable

Object)” to determine what kind of differences, if any, exist between the report

table and the physical table. pDifferences parameter of CheckDifferences method will pass back one or more bitwise (XOR’d) “CRTableDifferences” enums indicating the information that you want to retrieve.

DatabaseFieldDefinition Object

The DatabaseFieldDefinition Object represents a database field used in the report. This object provides properties for getting information on database fields in the report.

DatabaseFieldDefinition Object Properties

Property Definition

DatabaseField DisplayName

DatabaseFieldName String. Gets the name of the field in

Kind “CRFieldKind”. Gets which kind of

Name String. Gets the unique Crystal

NextValue Variant. Gets the field next value. Read

NumberOfBytes Integer. Gets the number of bytes

Parent “Report Object”. Gets reference to the

String. Gets the display name for the field in the database.

the database (for example, Product ID).

field (for example, database, summary, formula, etc.).

formula form name of the field within the report as {table.FIELD} (for example, {product.PRODUCT ID}).

required to store the field data in memory.

parent object.

Read/ Write

Read Only

Read only

only

Read only

Restriction in event handler

None

Can be read only when top-level Report object is formatting active.

None

48 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Property Definition

PreviousValue Variant. Gets the field previous value. Read

TableAliasName String. Gets the alias for the table

containing the field.

Value Variant. Gets the field current value. Read

Va lu eTy pe “CRFieldValueType”. Gets which

type of value is found in the field.

Read/ Write

only

Read only

only

Read only

Restriction in event handler

Can be read only when top-level Report object is formatting active.

None

Can be read only when top-level Report object is formatting active.

None

DatabaseFieldDefinitions Collection

The DatabaseFieldDefinitions Collection is a collection of database field definition objects. One object exists in the collection for every database field accessed by the report. Access a specific “DatabaseFieldDefinition Object” in the collection using the Item property.

DatabaseFieldDefinitions Collection Properties

Property Description

Count Long. Gets the number of “DatabaseFieldDefinition

Object”, in the collection.

Item (index As Long)

Parent “DatabaseTable Object”. Reference to the parent object. Read

“DatabaseFieldDefinition Object”. Item has an index

parameter that is a numeric, 1-based index for the object that you want to retrieve (for example, Item (1) for the first database field in the collection). The items in the collection are indexed in the order they appear in the database table.

Read/ Write

Read only

only

Restriction in event handler

None

Remarks

Instead of using the Item property as shown, you can reference a database directly (for example, DatabaseFieldDefinitions(1)).

Crystal Reports Technical Reference Guide 49

DatabaseTable Object

DatabaseFieldDefinitions Collection Methods

The following method is discussed in this section:

• “GetItemByName Method (DatabaseFieldDefinitions Collection)” on page 50

GetItemByName Method (DatabaseFieldDefinitions Collection)

Use the GetItemByName method to retrieve a DatabaseFieldDefinition object by name.

Syntax

Sub GetItemByName(name As String, databaseFieldDefinition)

Parameters

Parameter Description

name The item’s unique name. databaseFieldDefinition “DatabaseFieldDefinition Object”. An object to

hold the retrieved item.

DatabaseTable Object

The DatabaseTable Object refers to a database table accessed by the report.

DatabaseTable Object Properties

Examples

“How to connect to a Microsoft Access database” on page 171 “How to connect to a secured Microsoft Access database” on page 173 “How to connect to an ODBC data source” on page 175 “How to connect to an OLEDB data source” on page 177 “How to change the data source” on page 178

Property Description

ConnectBuffer String

DatabaseType “CRDatabaseType”. Gets the database

DescriptiveName String. Gets the table descriptive name. Read

50 Crystal Reports Technical Reference Guide

String. Gets the table connect buffer string. Read

table type

Read/ Write

only Read

only

Restriction in event handler

None

3 : Report Designer Component Object Model

Property Description

Read/ Write

DllName String. Gets the table driver DLL name. Read

only

Fields “DatabaseFieldDefinitions Collection

Properties”. Gets the collection of database

Read only

fields in the table.

Location String. Gets or sets the location of the

database table.

Name String. Gets or sets the alias name for the

database table used in the report.

Parent “Database Object”. Reference to the parent

object.

Read/ Wri te

Read only

DatabaseTable Object Methods

The following methods are discussed in this section:

• “CheckDifferences Method (DatabaseTable Object)” on page 51

• “SetDataSource Method (DatabaseTable Object)” on page 51

• “SetTableLocation Method (DatabaseTable Object)” on page 52

• “TestConnectivity Method (DatabaseTable Object)” on page 53

CheckDifferences Method (DatabaseTable Object)

Use the CheckDifferences method to determine what kind(s) of differences were found between the report table and the physical table.

Restriction in event handler

None

Can be written only when formatting idle.

None

Syntax

Sub CheckDifferences (pDifferences As Long, [reserved])

Parameters

Parameter Description

pDifferences “CRTableDifferences”. Bitwise constants specify the table

difference(s) (XOR’d), if any.

[reserved] Reserved. Do not use.

SetDataSource Method (DatabaseTable Object)

The SetDataSource method is used to provide information about a data source to the database driver associated with this DatabaseTable object at runtime. For instance, if a report has been designed using the Crystal Active Data Driver this method can be used to provide an active data source for the report, such as a DAO, ADO, or RDO Recordset or a CDO Rowset. In this case, the object passed to the

Crystal Reports Technical Reference Guide 51

DatabaseTable Object

second parameter of this method replaces, at runtime, the field definition file used to create the report. This method can be invoked only in formatting Idle mode. When using a secure connection such as SQL Server, some additional code is required (see Remarks below).

Syntax

Sub SetDataSource (data, [dataTag])

Parameters

Parameter Description

data Variant data passed to the database driver. For example, with

Active data, this must be a Recordset object if you are using DAO, ADO, or the Visual Basic data control. This must be a Rowset object if you are using CDO.

[dataTag] A value indicating the type of data being passed to the

DatabaseTable object in the Data parameter. Currently, the only possible value is 3. This value must be used for all Active data sources including DAO, ADO, RDO, CDO, and the Visual Basic data control.

Remarks

• When the data source uses a secure connection, such as SQL Server, additional

information must be passed in the "form load" event before the call to view the report. For example,

DataEnvironment1.Command1 Report.DatabaseTable.SetDataSource (DataEnvironment1.rsCommand1)

• SetDataSource method is used to set a datasource at runtime. If the report is

initially created and then saved, and then later run using either the RDC or CRW, the runtime datasource (DAO, ADO, or RDO Recordset) cannot be recreated. The user will not be able to run or preview the report.

SetTableLocation Method (DatabaseTable Object)

The SetTableLocation method is used to set the DatabaseTable location, sublocation, and connect buffer string.

Examples

“How to connect to a Microsoft Access database” on page 171 “How to connect to a secured Microsoft Access database” on page 173

Syntax

Sub SetTableLocation (pLocation As String, pSubLocation As String,

pConnectBufferSting As String)

52 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Parameters

Parameter Description

pLocation Specifies the location of the database table (file path and name.ext). pSubLocation Specifies the sublocation of the database table. pConnectBufferSting Specifies the connection buffer string.

Remarks

For example:

object.SetTableLocation "xtreme.mdb", "Customer", ""

TestConnectivity Method (DatabaseTable Object)

The TestConnectivity method tests to see if the database can be logged on to with the current information and if the database table can be accessed by the report.

Syntax

Function TestConnectivity () As Boolean

Returns

• TRUE if the database session, log on, and location information is all correct.

• FALSE if the connection fails or an error occurs.

DatabaseTables Collection

The DatabaseTables Collection is a collection of DatabaseTable objects. A DatabaseTable object exists for every database object (for example, table, query, stored procedure, etc.) accessed by the report. Access a specific DatabaseTable Object in the collection using the Item property.

DatabaseTables Collection Properties

Property Description

Count Long. Gets the number of database objects in the

collection.

Item (indexAs Long)

“DatabaseTable Object”. Item has an index parameter

that is a numeric, 1-based index (for example, Item (1)). The items in the collection are indexed in the

Read/ Write

Read only

order in which they were added to the report.

Parent “Database Object”. Reference to the parent object. Read

only

Crystal Reports Technical Reference Guide 53

Restriction in event handler

None

DatabaseTables Collection

Remarks

Instead of using the Item property as shown, you can reference a table directly (for example, DatabaseTable(1)).

DatabaseTables Collection Methods

The following methods are discussed in this section:

• “Add Method (DatabaseTables Collection)” on page 54

• “AddStoredProcedure Method (DatabaseTables Collection)” on page 55

• “Delete Method (DatabaseTables Collection)” on page 56

Add Method (DatabaseTables Collection)

Use the Add method to add a database table to the report.

Syntax

Sub Add (pLocation As String, [pSubLocation], [pConnectInfo],

[tableType], [pDllName], [pServerName], [pServerType], [pDatabaseName], [pUserID], [pPassword])

Parameters

Parameter Description

pLocation Specifies the location of the database table that you want

to add to the report.

[pSubLocation] Specifies the sublocation of the database table that you

want to add to the report. [pConnectInfo] Specifies the connection string. [tableType] Specifies the type of database table that you want to add

[pDllName] Specifies the DLL name for the database containing the

[pServerName] Specifies the database Server Name. [pServerType] Specifies the database Server Type. [pDatabaseName] Specifies the database (file path and name.ext) containing

[pUserID] Specifies the User’s ID. [pPassword] Specifies the User’s Password.

to the report.

table that you want to add.

the table that you want to add.

Remarks

• DatabaseTables.Add method is very generic and can be used to add tables to a

report from all kinds of data sources (for example, PC Table, SQL Server, ODBC, OLE DB provider, ADO, RDO, DAO Recordset).

54 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

• For example:

object.Add "xtreme.mdb", "Customer"

• You may use Add() to add a stored procedure to a report. No inital values are

passed to the procedure’s parameters so you need to set the values later using other API functions. To pass parameter values at the time of adding the stored procedure, use the “AddStoredProcedure Method (DatabaseTables

Collection)” instead.

AddStoredProcedure Method (DatabaseTables Collection)

Use the AddStoredProcedure method to add a stored procedure and its initial parameter values to the report.

Syntax

Sub AddStoredProcedure (pLocation as String,

[pSubLocation],[pConnectionInfo],[tableType],[pDllName], [pServerType],[pDatabaseName],[pUserID],[pPassword],[paramValueInfos])

Parameters

Parameter Description

pLocation Specifies the location of the database table that you want to add to the report. [pSubLocation] Specifies the sublocation of the database table that you want to add to the

[pConnectInfo] Specifies the connection string. [tableType] Specifies the type of database table that you want to add to the report. [pDllName] Specifies the DLL name for the database containing the table that you want

[pServerName] Specifies the database Server Name. [pServerType] Specifies the database Server Type. [pDatabaseName] Specifies the database (file path and name.ext) containing the table that you

[pUserID] Specifies the User’s ID. [pPassword] Specifies the User’s Password. [ParamValuesInfos] ParameterValueInfos Collection. Specifies the initial values for the stored

report.

to add.

want to add.

procedure’s parameters.

Remarks

AddStoredProcedure() has one additional parameter that Add() does not have: ParamValuesInfos. This parameter allows the initial values for the stored procedure’s parameters to be passed at the same time as the procedure is added to the report. If you do not want to pass initial parameter values, use “Add Method

(DatabaseTables Collection)” instead.

Crystal Reports Technical Reference Guide 55

ExportOptions Object

Delete Method (DatabaseTables Collection)

Use the Delete method to remove a database table from the Collection.

Syntax

Sub Delete (index As Long)

Parameter

Parameter Description

index Specifies the 1-based index number in the Collection of the

database table that you want to delete.

ExportOptions Object

The ExportOptions object provides properties and methods for retrieving information and setting options for exporting your report (that is, export format, destination, etc.). An ExportOptions Object is obtained from the ExportOptions property of the “Report Object”.

ExportOptions Object Properties

Property Description

ApplicationFile Name

String. Gets or sets the destination application file name.

Read/ Write

Read/ Wri te

Restriction in event handler

Set before exporting report to an application destination.

CharFieldDelimiter String. Gets or sets the character used to

separate fields in character separated text

Read/ Wri te

None

formats. This character delimits every field in the file.

CharString Delimiter

String. Gets or sets the character used to separate strings in character separated text

Read/ Wri te

None

formats. This character delimits only string fields (numeric, date fields, etc., have no delimiter).

DestinationDLL Name

String. Gets the Internal Name property of the DLL used to export the report to a

Read only

None

certain destination. The destination is set in the DestinationType property.

DestinationType “CRExportDestinationType”. Gets or sets

the export destination type.

56 Crystal Reports Technical Reference Guide

Read/ Wri te

None

3 : Report Designer Component Object Model

Property Description

DiskFileName String. Gets or sets the file name if the

report is exported to a disk.

Read/ Write

Read/

Wri te When exporting to HTML use HTMLFileName. When exporting to XML use XMLFileName.

ExcelAreaGroup Number

Integer. Gets or sets the base area group number if the area type is group area when

Read/

Wri te exporting to Excel.

ExcelAreaType “CRAreaKind”. Gets or sets the base area

type if not using constant column width

Read/

Wri te when exporting to Excel.

ExcelConstant ColumnWidth

ExcelConvertDate To St ri ng

ExcelExportAll Pages

ExcelFirstPage Number

ExcelLastPage Number

ExcelPageBreaks Boolean. Gets or sets export to Excel has

ExcelTabHas ColumnHeadings

ExcelUseConstant ColumnWidth

ExcelUseTabular Format

ExcelUseWorksheet Functions

Double. Gets or sets the column width when exporting to Excel.

Boolean. Gets or sets export to Excel has converting date values to strings option.

Boolean. Gets or sets export to Excel with all pages.

Long. Gets or sets export to Excel for first page number.

Long. Gets or sets export to Excel for last page number.

page break option. Boolean. Gets or sets exporting to Excel

has column headings option. Boolean. Gets or sets export to Excel to use

constant column width. Boolean. Gets or sets exporting to Excel to

use tabular format. Boolean. Gets or sets export to Excel to use

worksheet functions to represent subtotal

Read/

Wri te

Read/

Wri te

Read/

Wri te

Read/

Wri te

Read/

Wri te

Read/

Wri te

Read/

Wri te

Read/

Wri te

Read/

Wri te

Read/

Wri te fields in the report.

Exchange DestinationType

“CRExchangeDestinationType”. Gets or

sets the Exchange destination type for

Read/

Wri te reports exported to Exchange folders.

ExchangeFolder Path

String. Gets or sets the path of the Exchange folder for reports exported to

Read/

Wri te Exchange (for example, “MyFolders@Inbox”).

ExchangePassword String. Sets Exchange password. Write

only

Restriction in event handler

None

Crystal Reports Technical Reference Guide 57

ExportOptions Object

Property Description

ExchangeProfile String. Gets or sets a user profile for

accessing an Exchange folder for reports

Read/ Write

Read/ Wri te

exported to Exchange.

ExchangePathHas ColumnHeadings

FormatDLLName String. Gets the Internal Name property of

Boolean. Gets or sets the column heading option when exporting to Exchange.

the DLL used to export the report to a

Read/ Wri te

Read

only certain format type. The export format type is set in the FormatType property.

FormatType “CRExportFormatType”. Gets or sets the

format type for the exported report (for

Read/

Wri te example, text, Excel, etc.).

HTMLEnable SeperatedPages

Boolean. Gets or sets the option to create seperated pages when exporting to HTML

Read/

Wri te format.

HTMLFileName String. Gets or sets the HTML file name for

reports exported to HTML format.

HTMLHasPage Navigator

Boolean. Gets or sets the option to display a page navigator on each page of a report

Read/

Wri te

Read/

Wri te exported to HTML format.

LotusDomino Comments

LotusDomino DatabaseName

LotusNotesForm Name

MailBccList String. Gets or sets a Blind Carbon Copy

String. Gets or sets the destination Lotus Domino comments.

String. Gets or sets the destination Lotus Domino database name.

String. Gets or sets the destination Lotus Domino form name.

(BCC) list for reports e-mailed to a VIM e-

Read/

Wri te

Read/

Wri te

Read/

Wri te

Read/

Wri te mail account.

MailCcList String. Gets or sets a Carbon Copy (CC) list

for reports e-mailed.

MailMessage String. Gets or sets the e-mail message

included with e-mailed reports.

MailSubject String. Gets or sets the e-mail subject

heading for reports being e-mailed.

MailToList String. Gets or sets the To list for reports

being e-mailed.

Read/

Wri te

Read/

Wri te

Read/

Wri te

Read/

Wri te

MailUserName String. Gets or sets mail user name. Read/

Wri te

Restriction in event handler

None

58 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Property Description

NumberOfLines PerPage

Integer. Gets or sets the number of lines to appear per page option for reports exported to a paginated text format.

ODBCDataSource Name

ODBCDataSource Password

ODBCDataSource UserID

String. Gets or sets the ODBC data source for reports exported to ODBC.

String. Sets the ODBC data source password.

String. Gets or sets the user name used to access an ODBC data source for reports exported to ODBC.

ODBCExportTable Name

String. Gets or sets the database table in the ODBC data source that the report file exported to ODBC will be appended to. You can also create a new table using this property.

Parent “Report Object”. Reference to the parent

object.

PDFExportAll Pages

Boolean. Gets or sets whether or not to export all pages of the report to Portable Document Format(PDF). PDFExportAllPages must be set to false when setting PDFFirstPageNumber and PDFLastPageNumber.

PDFFirstPage Number

Long. Gets or sets the start page, of a page export range, when exporting to PDF. PDFExportAllPages must be set to False or this value is ignored.

PDFLastPage Number

Long. Gets or sets the end page, of a page export range, when exporting to PDF. PDFExportAllPages must be set to False or this value is ignored.

RTFExportAllPages Boolean. Gets or sets whether or not to

export all pages of the report to Rich Text Format(RTF). RTFExportAllPages must be set to false when setting RTFFirstPageNumber and RTFLastPageNumber.

RTFFirstPage Number

Long. Gets or sets the start page, of a page export range, when exporting to RTF. RTFExportAllPages must be set to False or this value is ignored.

Read/ Write

Read/ Wri te

Wri te only

Read/ Wri te

Read only

Read/ Wri te

Restriction in event handler

None

Crystal Reports Technical Reference Guide 59

ExportOptions Object

Property Description

RTFFLastPage Number

Long. Gets or sets the end page, of a page export range, when exporting to RTF. RTFExportAllPages must be set to False or this value is ignored.

UseDefault CharactersPerInch

UserDefined CharactersPerInch

UseReportDate Format

Boolean. Gets or sets use default characters per inch option.

Long. Gets or sets user defined characters per inch.

Boolean. Gets or sets whether the date format used in the report should also be used in the exported report. Can be used for Data Interchange Format (DIF), Record Style Format, and comma, tab, or character separated format.

UseReportNumber Format

Boolean. Gets or sets whether the number format used in the report should also be used in the exported report. Can be used for Data Interchange Format (DIF), Record Style Format, and comma, tab, or character separated format.

XMLAllow MultipleFiles

Boolean. Gets or sets allow multiple files, when exporting to XML. When set to True the Schema file for the report will be exported along with the XML file. The Schema file will be either an XML schema (.xsd) or a Document Type Definition (.dtd), depending on the options selected in the XML Forma dilaog box. For more information see “Customizing XML report definitions” in the Crystal Reports User’s

Guide

XMLFileName String. Gets or sets the file name if the

report is exported to a disk.

Read/

Write

Read/

Wri te

Read/

Wri te

Read/

Wri te

Read/

Wri te

Read/

Wri te

Read/

Wri te

Read/

Wri te

Restriction in event handler

None

Remarks

For backwards compatibility the FormatDllName and DestinationDllName properties return the Internal Name property of the associated DLL. The Internal Name property of the DLL is found in the DLLs Properties Dialog box under the Version tab. For a list of export DLLs see “Export Destination” and “Export Format” in the Runtime help (Runtime.hlp).

60 Crystal Reports Technical Reference Guide

ExportOptions Object Methods

The following methods are discussed in this section:

• “PromptForExportOptions Method (ExportOptions Object)” on page 61

• “Reset Method (ExportOptions Object)” on page 61

PromptForExportOptions Method (ExportOptions Object)

The PromptForExportOptions method prompts the user for export information using default Crystal Report Engine dialog boxes.

Syntax

Sub PromptForExportOptions ()

Reset Method (ExportOptions Object)

The Reset method clears all ExportOptions properties.

Syntax

Sub Reset ()

FieldDefinitions Collection

The FieldDefinitions Collection contains the various types of XXXFieldDefinition Objects (for example, DatabaseFieldDefinition, FormulaFieldDefinition, SummaryFieldDefinition). For the current release, developers can access the FieldDefinitions Collection only through the ConditionFields Property of GraphObject.

3 : Report Designer Component Object Model

FieldDefinitions Collection Properties

Property Description

Count Long. Gets the collection count. Read

Item (index As Long)

Parent “Report Object”. Reference to the parent object. Read

Crystal Reports Technical Reference Guide 61

A field definition object. Gets the collection item. See Remarks.

Remarks

After getting the field definition object from the Item property, you can use the Kind property to determine what type of field definition object the item is. All field definition objects have the Kind property.

Read/ Write

only Read

only

Restriction in event handler

None

FieldElement Object

FieldDefinitions Collection Methods

The following methods are discussed in this section:

• “Add Method (FieldDefinitions Collection)” on page 62

• “Delete Method (FieldDefinitions Collection)” on page 62

Add Method (FieldDefinitions Collection)

Use the Add method to add the specified Field to the FieldDefinitions Collection.

Syntax

Sub Add (Field)

Parameter

Parameter Description

Field Specifies the Field that you want to add to the Collection.

Delete Method (FieldDefinitions Collection)

Use the Delete method to remove the specified Field from the FieldDefinitions Collection.

Syntax

Sub Delete (Field)

Parameter

Parameter Description

Field Specifies the Field that you want to delete from the Collection.

FieldElement Object

The FieldElement Object represents a field object embedded in a text field. This object provides properties for retrieving field element information from a text object (for example, line spacing, the number of decimal places, font color). A FieldElement Object is obtained from the Item property of the “FieldElements

Collection” on page 66.

62 Crystal Reports Technical Reference Guide

FieldElement Object Properties

3 : Report Designer Component Object Model

Property Description

AmPmType “CRAMPMType”. Gets or sets the AM/

PM type option.

AmString String. Gets or sets the AM string. Read/

BooleanOutput Ty pe

CharacterSpacing Long. Gets or sets the character spacing.

Color OLE_COLOR. Gets or sets the font

ConditionFormula String. Gets or sets the condition

CurrencyPosition Ty pe

CurrencySymbol String. Gets or sets the currency

CurrencySymbol Ty pe

DateCalendar Ty pe

DateEraType “CRDateEraType”. Gets or sets the date

DateFirst Separator

DateOrder “CRDateOrder”. Gets or sets the date

DatePrefix Separator

DateSecond Separator

DateSuffix Separator

“CRBooleanOutputType”. Gets or sets

the Boolean output type.

OLE_COLOR. Gets or sets the object background color.

color.

formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables.

“CRCurrencyPositionType”. Gets or

sets the currency position type.

symbol.

“CRCurrencySymbolType”. Gets or

sets the currency symbol type.

“CRDateCalendarType”. Gets or sets

the date calendar type.

era type. String. Gets or sets the date first

separator.

order. String. Gets or sets the date prefix

separator. String. Gets or sets the date second

separator. String. Gets or sets the date suffix

separator

Read/ Write

Read/ Wri te

Wri te Read/

Wri te

Read/ Wri te

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Crystal Reports Technical Reference Guide 63

FieldElement Object

Property Description

DateWindows DefaultType

“CRDateTimeFieldFormatConditionFo rmulaType”. Gets or sets the date

Read/ Write

Read/ Wri te

windows default type.

DayType “CRDayType”. Gets or sets the day

type.

DecimalPlaces Integer. Gets or sets the number

decimal places.

Read/ Wri te

DecimalSymbol String. Gets or sets the decimal symbol. Read/

Wri te

DisplayReverse Sign

FieldDefinition A field definition object. Gets the field

Boolean. Gets or sets the reverse sign option.

definition. See Remarks.

Read/ Wri te

Read Only

FirstLineIndent Long. Gets or sets the first line indent. Read/

Wri te

Font IFontDisp. Gets or sets the standard

OLE font.

HourMinute Separator

String. Gets or sets the hour minute separator.

HourType “CRHourType”. Gets or sets the hour

type.

LeadingDay Position

LeadingDay Separator

“CRLeadingDayPosition”. Gets or sets

the leading day position option. String. Gets or sets the leading day

separator.

LeadingDayType “CRLeadingDayType”. Gets or sets the

leading day type.

LeftIndent Long. Gets or sets the left indent, in

twips.

Read/ Wri te

LineSpacing Double. Gets the line spacing. Read

Only

LineSpacingType “CRLineSpacingType”. Gets the line

spacing type.

MaxNumberOf Lines

MinuteSecond Separator

Integer. Gets or sets the maximum number of line for a string memo field.

String. Gets or sets minute second separator.

MinuteType “CRMinuteType”. Gets or sets the

minute type.

Read Only

Read/ Wri te

Restriction in event handler

Can be written only when formatting idle.

Can be written only when formatting idle or active.

None

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

None

Can be written only when formatting idle or active.

64 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Property Description

MonthType “CRMonthType”. Gets or sets month

type.

NegativeType “CRNegativeType”. Gets or sets

number negative type.

Parent “TextObject Object”. Reference to the

parent object.

Read/ Write

Read/ Wri te

Read only

PmString String. Gets or sets the PM string. Read/

Wri te

RightIndent Long. Gets or sets the right indent, in

twips.

RoundingType “CRRoundingType”. Gets or sets the

number rounding type.

SecondType “CRSecondType”. Gets or sets the

seconds type.

Suppress Boolean. Gets or sets the object

visibility.

SuppressIf Duplicated

Boolean. Gets or sets the suppress if duplicate option.

SuppressIfZero Boolean. Gets or sets the suppress if

zero option.

TextFormat “CRTextFormat”. Gets or sets the text

format option for string memo fields.

Thousands Separators

Boolean. Gets or sets the enable thousands separators option.

ThousandSymbol String. Gets or sets the thousand

separator symbol.

Tim eBase “CRTimeBase”. Gets or sets the time

base.

UseLeadingZero Boolean. Gets or sets the number uses

leading zero option.

UseOneSymbol PerPage

Boolean. Gets or sets the use one symbol per page option.

UseSystemDefaults Boolean. Gets or sets the use system

defaults formatting option.

Ye ar Typ e “CRYearType”. Gets or sets the year

type.

ZeroValueString String. Gets or sets the zero value string

for number field format.

Read/ Wri te

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Crystal Reports Technical Reference Guide 65

FieldElements Collection

Remarks

After getting the field definition object from the FieldDefiniton property, you can use the Kind property to determine what type of field definition object it is. All field definition objects have the Kind property.

FieldElement Object Methods

The following method is discussed in this section:

• “SetLineSpacing Method (FieldElement Object)” on page 66

SetLineSpacing Method (FieldElement Object)

Use the SetLineSpacing method to get and set the line spacing and line spacing type.

Syntax

Sub SetLineSpacing (LineSpacing As Double,

LineSpacingType As CRLineSpacingType)

Parameters

Parameter Description

LineSpacing Specifies the line spacing. LineSpacingType Specifies the line spacing type. Use one of “CRLineSpacingType”.

FieldElements Collection

The FieldElements collection contains the FieldElement objects defined in a text field. Access a specific object in the collection using the Item property.

FieldElements Collection Properties

Property Definition

Count Long. Gets the number of objects in the collection. Read

Item (indexAs Long)

Parent “TextObject Object”. Gets reference to the parent object. Read

66 Crystal Reports Technical Reference Guide

“FieldElement Object”. Gets an item from the

Collection specified by the parameter index.

Read/ Write

only Read

only

Restriction in event handler

None

FieldElements Collection Methods

The following methods are discussed in this section:

• “Add Method (FieldElements Collection)” on page 67

• “Delete Method (FieldElements Collection)” on page 67

Add Method (FieldElements Collection)

The Add method is used to add a FieldElement object to the Collection.

Syntax

Function Add (position As Long, Field)

Parameter Description

position Specifies the index where you would like to add the FieldElement

to the Collection.

Field Specifies the FieldElement that you want to add to the Collection.

Delete Method (FieldElements Collection)

Use the Delete method to remove a FieldElement Object from the Collection.

Syntax

Sub Delete (index)

3 : Report Designer Component Object Model

Parameter

Parameter Description

index Specifies the index number of the Object that you want to remove

from the Collection.

FieldMappingData Object

The FieldMappingData Object provides information related to FieldMapping Events. This Object can be accessed through the Report Object FieldMapping Event.

FieldMappingData Object Properties

Property Description Read/Write

FieldName String. Gets or sets the field name. Read/Write None MappingTo

FieldIndex

Crystal Reports Technical Reference Guide 67

Integer. Gets or sets the index of the mapping to field index in the field list of the new database.

Read/Write None

Restriction in event handler

FieldObject Object

Property Description Read/Write

TableName String. Gets or sets field’s table name. Read/Write None Va lu eTy pe “CRFieldValueType”. Gets the value type

that is in the field.

Read only None

Restriction in event handler

FieldObject Object

The FieldObject Object represents a field found in a report (for example, special field, database field, parameter field, etc.). This object provides properties for retrieving information for a field in your report. A FieldObject Object is obtained from the Item property of the “ReportObjects Collection” on page 133, (for example, ReportObjects.Item(Index), where the index can be the 1-based index number of the item or an Object name).

FieldObject Object Properties

Property Description

AmPmType “CRAMPMType”. Gets or sets the

AM/PM type option.

AmString String. Gets or sets the AM string. Read/

BackColor OLE_COLOR. Gets or sets the object

background color.

BooleanOutput Ty pe

BorderColor OLE_COLOR. Gets or sets the object

BottomLineStyle “CRLineStyle”. Gets or sets bottom line

CanGrow Boolean. Gets or sets can the grow

CharacterSpacing Long. Gets or sets the character

CloseAtPageBreak Boolean. Gets or sets the close border

“CRBooleanFieldFormatConditionFor mulaType”. Gets or sets the Boolean

output type.

border color.

style.

option.

spacing.

on page break option.

Read/ Write

Write Read/

Write

Read/ Write

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

68 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Property Description

ConditionFormula String. Gets or sets the condition

formula. The condition formula can be

Read/ Write

Read/

Write based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables.

CssClass String. Gets or sets the cascading style

sheet Class.

CurrencyPosition Ty pe

“CRCurrencyPositionType”. Gets or

sets the currency position type.

CurrencySymbol String. Gets or sets the currency

symbol.

CurrencySymbol Ty pe

“CRCurrencySymbolType”. Gets or

sets the currency symbol type.

DateCalendarType “CRDateCalendarType”. Gets or sets

the date calendar type.

DateEraType “CRDateEraType”. Gets or sets the

date era type.

DateFirstSeparator String. Gets or sets the date first

separator.

DateOrder “CRDateOrder”. Gets or sets the date

order.

DatePrefix Separator

DateSecond Separator

DateSuffix Separator

DateWindows DefaultType

String. Gets or sets the date prefix separator.

String. Gets or sets the date second separator.

String. Gets or sets the date suffix separator

“CRDateTimeFieldFormatConditionFo rmulaType”. Gets or sets the date

Read/

Write

Read/

Write

Read/

Write

Read/

Write

Read/

Write

Read/

Write

Read/

Write

Read/

Write

Read/

Write

Read/

Write

Read/

Write

Read/

Write windows default type.

DayType “CRDayType”. Gets or sets the day

type.

DecimalPlaces Integer. Gets or sets the number

decimal places.

Read/

Write

Read/

Write

DecimalSymbol String. Gets or sets the decimal symbol. Read/

Write

Restriction in event handler

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Crystal Reports Technical Reference Guide 69

FieldObject Object

Property Description

DisplayReverse Sign

EnableTight Horizontal

Boolean. Gets or sets the reverse sign option.

Boolean. Gets or sets the tight horizontal option.

Field Object. Gets the field definition object

(for example, ParameterFieldDefinition

Read/ Write

Read only

Object).

FirstLineIndent Long. Gets or sets the first line indent. Read/

Write

Font IFontDisp. Gets or sets the standard

OLE font.

HasDropShadow Boolean. Gets or sets the border drop

shadow option.

Height Long. Gets or sets object height, in

twips.

HorAlignment “CRAlignment”. Gets or sets the

horizontal alignment.

HourMinute Separator

String. Gets or sets the hour minute separator.

HourType “CRHourType”. Gets or sets the hour

type.

KeepTogether Boolean. Gets or sets the keep object

together option.

Kind “CRObjectKind”. Gets which kind of

object (for example, box, cross-tab,

Read/ Write

Read only

field.)

LeadingDay Position

LeadingDay Separator

LeadingDayType “CRLeadingDayType”. Gets or sets the

Left Long. Gets or sets the object upper left

LeftIndent Long. Gets or sets the left indent, in

LeftLineStyle “CRLineStyle”. Gets or sets the left line

“CRLeadingDayPosition”. Gets or sets

the leading day position option. String. Gets or sets the leading day

separator.

leading day type.

position, in twips.

twips.

style.

Read/ Write

LineSpacing Double. Gets the line spacing. Read

Only

Restriction in event handler

Can be written only when formatting idle or active.

None

Can be written only when formatting idle.

Can be written only when formatting idle or active.

None

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

None

70 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Property Description

LineSpacingType “CRLineSpacingType”. Gets the line

spacing type.

MaxNumberOf Lines

MinuteSecond Separator

Integer. Gets or sets the maximum number of line for a string memo field.

String. Gets or sets minute second separator.

MinuteType “CRMinuteType”. Gets or sets the

minute type.

MonthType “CRMonthType”. Gets or sets month

type.

Read/

Write

Read

Only

Read/

Write

Read/

Write

Read/

Write

Read/

Write

Name String. Gets or sets the object name. Read/

Write

NegativeType “CRNegativeType”. Gets or sets

number negative type.

Read/

Write

NextValue Variant. Gets the field next value. Read

only

Parent “Section Object”. Reference to the

parent object.

Read

only

PmString String. Gets or sets the PM string. Read/

Write

PreviousValue Variant. Gets the field previous value. Read

only

RightIndent Long. Gets or sets the right indent, in

twips.

RightLineStyle “CRLineStyle”. Gets or sets the right

line style.

RoundingType “CRRoundingType”. Gets or sets the

number rounding type.

SecondType “CRSecondType”. Gets or sets the

seconds type.

Suppress Boolean. Gets or sets the object

visibility.

SuppressIf Duplicated

Boolean. Gets or sets the suppress if duplicate option.

SuppressIfZero Boolean. Gets or sets the suppress if

zero option.

TextColor OLE_COLOR. Gets or sets the object

text color.

Read/

Write

Read/

Write

Read/

Write

Read/

Write

Read/

Write

Read/

Write

Read/

Write

Read/

Write

Restriction in event handler

None

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Crystal Reports Technical Reference Guide 71

FieldObject Object

Property Description

TextFormat “CRTextFormat”. Gets or sets the text

format option for string memo fields.

TextRotationAngle “CRRotationAngle”. Gets or sets the

text rotation angle.

Thousands Separators

ThousandSymbol String. Gets or sets the thousand

Tim eBase “CRTimeBase”. Gets or sets the time

Top Long. Gets or sets the object upper top

To pL in eS ty le “CRLineStyle”. Gets or sets the top line

UseLeadingZero Boolean. Gets or sets the number uses

UseOneSymbolPer Page

UseSystemDefaults Boolean. Gets or sets the use system

Value Variant. Gets the field current value. Read

Width Long. Gets or sets the object width, in

Ye ar Typ e “CRYearType”. Gets or sets the year

ZeroValueString String. Gets or sets the zero value

Boolean. Gets or sets the enable thousands separators option.

separator symbol.

base.

position, in twips.

style.

leading zero option. Boolean. Gets or sets the use one

symbol per page option.

defaults formatting option.

twips.

type.

string for number field format.

Read/ Write

Only Read/

Write Read/

Write

Restriction in event handler

Can be written only when formatting idle.

Can be written only when formatting idle or active.

FieldObject Object Methods

The following methods are discussed in this section:

• “SetLineSpacing Method (FieldObject Object)” on page 72

• “SetUnboundFieldSource Method (FieldObject Object)” on page 73

SetLineSpacing Method (FieldObject Object)

Use the SetLineSpacing method to get and set the line spacing and line spacing type.

72 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Syntax

Sub SetLineSpacing (LineSpacing As Double,

LineSpacingType As CRLineSpacingType)

Parameters

Parameter Description

LineSpacing Specifies the line spacing. LineSpacingType Specifies the line spacing type. Use one of “CRLineSpacingType”.

SetUnboundFieldSource Method (FieldObject Object)

Use the SetUnbound FieldSource Method to bind a DataSource to an unbound field.

Syntax

Sub SetUnboundFieldSource (pUnboundFieldSource As String)

Parameter

Parameter Description

pUnboundFieldSource BSTR specifies the datasouce, Crystal formula format. See Remarks below.

Remarks

For example:

object.SetUnboundFieldSource("{Customer.CustomerID}")

FormattingInfo Object

The FormattingInfo object contains information about the section currently being formatted.

FormattingInfo Object Properties

Property Description

IsEndOfGroup Boolean. Gets whether the current formatting

section is the end of a group.

IsRepeatedGroup Header

Boolean. Gets whether the current formatting section is a repeated group header.

IsStartOfGroup Boolean. Gets whether the current formatting

section is the start of a group.

Crystal Reports Technical Reference Guide 73

Read/ Write

Read only

Restriction in event handler

None

FormulaFieldDefinition Object

The FormulaFieldDefinition Object provides properties and methods for retrieving information and setting options for any named formula field in a report.

FormulaFieldDefinition Object Properties

Property Description

FormulaField Name

Kind “CRFieldKind”. Gets what kind of field (for

Name String. Gets the unique name of the formula

NextValue Variant. Gets the field next value. Read

NumberOf Bytes

Parent “Report Object”. Gets reference to the parent

PreviousValue Variant. Gets the field previous value. Read

Text String. Gets or sets the text of the formula.

Value Variant. Gets the field current value. Read

Va lu eTy pe “CRFieldValueType”. Gets which type of

String. Gets the formula field name as it appears in the RDC Dataview Panel.

example, database, summary, formula, etc.).

field in Crystal formula format as it would be referenced in the report (for example, {@ExampleFormula}).

Integer. Gets the number of bytes required to store the field data in memory.

object.

The formula text is changed immediately in the report. If you generate a report with an invalid formula, you may receive an exception error. Syntax can be Crystal Refort or Visual Basic. See Remarks below.

value is found in the field.

Read/ Write

Read only

only

Read only

only

Read/ Wri te

only

Read only

Restriction in event handler

None

Ca n be r ead o nly w hen top-level Report object is formatting active.

None

Ca n be r ead o nly w hen top-level Report object is formatting active.

Can be written only when formatting idle.

Ca n be r ead o nly w hen top-level Report object is formatting active.

None

Remarks

Crystal Reports 9 supports formulas in Crystal Reports syntax and Visual Basic syntax. When setting text to a formula, the syntax is determined by the FormulaSyntax property of the parent “Report Object”. The default syntax is Crystal Report syntax (crCrystalSyntaxFormula).

74 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

FormulaFieldDefinition Object Methods

The following method is discussed in this section:

• “Check Method (FormulaFieldDefinition Object)” on page 75

Check Method (FormulaFieldDefinition Object)

The Check method checks formulas for errors (syntax errors).

Syntax

Sub Check (pBool As Boolean, ppErrorString As String)

Parameters

Parameter Description

pBool Boolean value indicating the condition of the formula string. Will be set to TRUE

ppErrorString Specifies the error message string if the formula contains an error.

if the formula is valid and FALSE if the formula contains one or more errors.

FormulaFieldDefinitions Collection

The FormulaFieldDefinitions Collection is a collection of named formulas in the report. Access a specific “FormulaFieldDefinition Object”, in the collection using the Item property.

FormulaFieldDefinitions Collection Properties

Property Description Read/Write

Count Long. Gets the number of formula field definitions

in the collection.

Item (index As Long)

Parent “Report Object”. Gets reference to the parent object. Read only None

“FormulaFieldDefinitions Collection”. Gets

collection item. See Remarks below.

Remarks

Instead of using the Item property as shown, you can reference a formula field directly (for example, FormulaFieldDefinitions(1)).

Read only None

Restriction in event handler

FormulaFieldDefinitions Collection Methods

The following methods are discussed in this section:

• “Add Method (FormulaFieldDefinitions Collection)” on page 76

Crystal Reports Technical Reference Guide 75

FormulaFieldDefinitions Collection

• “Delete Method (FormulaFieldDefinitions Collection)” on page 76

• “GetItemByName Method (FormulaFieldDefinitions Collection)” on page 76

Add Method (FormulaFieldDefinitions Collection)

Use the Add method to add the specified formula field to the FormulaFieldDefinitions Collection.

Syntax

Function Add (formulaName As String,

Text As String) As FormulaFieldDefinition

Parameters

Parameter Description

formulaName Specifies the formula field that you want to add to the Collection. Text Specifies the text of the formula field that you want to add.

Returns

Returns a FormulaFieldDefinition member of the Collection.

Delete Method (FormulaFieldDefinitions Collection)

Use the Delete method to remove the specified formula field from the FormulaFieldDefinitions Collection.

Syntax

Sub Delete (index)

Parameter

Parameter Description

index Specifies the formula field that you want to delete from the Collection.

GetItemByName Method (FormulaFieldDefinitions Collection)

Use the GetItemByName method to retrieve a FormulaFieldDefinition object by name.

Syntax

Sub GetItemByName(name As String, formulaFieldDefinition)

Parameters

Parameter Description

name The item’s unique name. formulaFieldDefinition A FormulaFieldDefinition object to hold the retrieved item.

76 Crystal Reports Technical Reference Guide

GraphObject Object

The GraphObject Object represents a graph/chart found in a report. This object provides properties for retrieving information and setting options for a graph in your report (that is, graph data type — group, detail or graph display type — bar, pie, and so on.).

GraphObject Object Properties

Examples

“How to format a graph object (chart)” on page 185

3 : Report Designer Component Object Model

Property Description

AutoRange Data2Axis

AutoRange DataAxis

AutoRange SeriesAxis

BackColor OLE_COLOR. Gets or sets the object

BarSize “CRBarSize”. Gets or sets the bar size. Read/

BorderColor OLE_COLOR. Gets or sets the object border

BottomLineStyle “CRLineStyle”. Gets or sets the bottom line

CloseAt PageBreak

ConditionFields “FieldDefinitions Collection”. Gets the

Condition Formula

Boolean. Gets or sets the auto range option for data2 axis. See Remarks below.

Boolean. Gets or sets the auto range option for data axis. See Remarks below.

Boolean. Gets or sets the auto range option for series axis.

background color.

color.

style.

Boolean. Gets or sets the close border on page break option.

condition fields Collection. String. Gets or sets the condition formula.

The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables.

Read/ Write

Write Read/

Write

Read/ Write

Read only

Read/ Write

Restriction in event handler

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

None

Can be written only when formatting idle.

Crystal Reports Technical Reference Guide 77

GraphObject Object

Property Description

CrossTabObject “CrossTabObject Object”. Gets the crosstab

object if this is a CrossTab chart.

CssClass String. Gets or sets the cascading style sheet

Class.

Data2Axis DivisionMethod

Data2Axis DivisionNumber

Data2Axis Gridline

Data2Axis NumberFormat

DataAxis DivisionMethod

DataAxis DivisionNumber

DataAxis Gridline

DataAxis NumberFormat

“CRDivisionMethod”. Gets or sets the

data2 axis division method. Long. Gets or sets the data2 axis division

number.

“CRGridlineType”. Gets or sets the data2

axis grid line type.

“CRNumberFormat”. Gets or sets the data2

axis number format.

“CRDivisionMethod”. Gets or sets the data

axis division method. Long. Gets or sets the data axis division

number.

“CRGridlineType”. Gets or sets the data

axis grid line type.

“CRNumberFormat”. Gets or sets the data

axis number format.

DataLabelFont IFontDisp. Gets or sets standard OLE font

for chart data labels.

DataPoint “CRGraphDataPoint”. Gets or sets the

graph data points on risers.

DataTitleFont IFontDisp. Gets or sets standard OLE font

for chart data title.

DataType “CRGraphDataType”. Returns which type

of data used in the graph.

DataValue NumberFormat

EnableAuto ScaleDataAxis

EnableAuto ScaleData2Axis

EnableAutoScale SeriesAxis

EnableFor EachRecord

“CRNumberFormat”. Gets or sets the data

value number format. Boolean. Gets or sets the data axis auto-

scale option. Boolean. Gets or sets the data2 axis auto-

scale option. Boolean. Gets or sets the series axis auto-

scale option. Boolean. Gets or sets the enable for each

record option.

Read/ Write

Read only

Read/ Write

Read only

Read/ Write

Restriction in event handler

None

Can be written only when formatting idle.

None

Can be written only when formatting idle.

78 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Property Description

EnableShow Legend

EnableSummarize Va lu e s

Boolean. Gets or sets the show legend option.

Boolean. Gets or sets the enable summarize values option.

Read/ Write

FootNote String. Gets or sets the footnote. Read/

Write

FootnoteFont IFontDisp. Gets or sets standard OLE font

for chart footnote.

Read/ Write

GraphColor crgraphcolor. Gets or sets the graph color. Read/

Write

GraphDirection “CRGraphDirection”. Gets or sets the

graph direction.

GraphType “CRGraphType”. Gets or sets the graph

type.

GroupAxis Gridline

“CRGridlineType”. Gets or sets the group

axis grid line type.

GroupLabelFont IFontDisp. Gets or sets standard OLE font

for chart group labels.

Read/ Write

GroupsTitle String. Gets or sets the groups title. Read/

Write

GroupTitleFont IFontDisp. Gets or sets standard OLE font

for chart group title.

HasDropShadow Boolean. Gets or sets the border drop

shadow option.

Height Long. Gets or sets the object height, in

twips.

IsFootnote

Boolean. Gets or sets footnote default flag. Read/

ByDefault

IsGroupsTitleBy Default

IsSeriesTitleBy

Boolean. Gets or set groups title default flag.

Boolean. Gets or sets series title default flag. Read/

Default

IsSubTitleBy

Boolean. Get or sets subtitle default flag. Read/

Default

Read/ Write

Write

Read/ Write

Write

Restriction in event handler

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Crystal Reports Technical Reference Guide 79

GraphObject Object

Property Description

Read/ Write

IsTitleByDefault Boolean. Gets or sets title default flag. Read/

Write

IsXAxisTitleBy Default

IsYAxisTitleBy Default

IsZAxisTitleBy Default

KeepTogether Boolean. Gets or sets keep object together

Kind “CRObjectKind”. Gets which kind of object

Left Long. Gets or sets the object upper left

Boolean. Gets or sets X axis title default flag.

Boolean. Gets or sets Y axis title default flag.

Boolean. Gets or sets Z axis title default flag.

option.

(for example, box, cross-tab).

position, in twips.

Read/ Write

Read only

Read/ Write

LeftLineStyle “CRLineStyle”. Gets or sets the left line style. Read/

Write

LegendFont IFontDisp. Gets or sets standard OLE font

for legend.

LegendLayout “CRPieLegendLayout”. Gets or sets the

legend layout for a pie chart.

LegendPosition “CRLegendPosition”. Gets or sets the

legend position.

MarkerShape “CRMarkerShape”. Gets or sets the marker

shape.

MarkerSize “CRMarkerSize”. Gets or sets the marker

size.

MaxData2Axis Va lu e

MaxDataAxis Va lu e

MaxSeriesAxis Va lu e

Double. Gets or sets data2-axis max value. See Remarks below.

Double. Gets or sets data-axis max value. See Remarks below.

Double. Gets or sets series axis max value. See Remarks below.

Read/ Write

Restriction in event handler

Can be written only when formatting idle or active.

None

Can be written only when formatting idle or active.

Can be written only when formatting idle.

80 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Property Description

MinData2Axis Va lu e

MinDataAxis Va lu e

MinSeriesAxis Va lu e

Double. Gets or sets data2-axis min value. See Remarks below.

Double. Gets or sets data-axis min value. See Remarks below.

Double. Gets or sets series axis min value. See Remarks below.

Read/ Write

Name String. Gets or sets the object name. Read/

Write

Parent “Section Object”. Gets reference to the

parent object.

PieSize “CRPieSize”. Gets or sets the size for pie

charts.

RightLineStyle “CRLineStyle”. Gets or sets the right line

style.

SeriesAxis DivisionMethod

SeriesAxis DivisionNumber

SeriesAxis NumberFormat

SeriesAxis Gridline

“CRDivisionMethod”. Gets or sets the

series axis division method. Long. Gets or sets the series axis division

number.

“CRNumberFormat”. Gets or sets the series

axis number format.

“CRGridlineType”. Gets or sets the series

axis grid line type.

SeriesLabelFont IFontDisp. Gets or sets standard OLE font

for chart series labels.

Read only

Read/ Write

SeriesTitle String. Gets or sets the series title. Read/

Write

SeriesTitleFont IFontDisp. Gets or sets standard OLE font

for chart series title.

SliceDetachment “CRSliceDetachment”. Gets or sets the slice

detachment.

Read/ Write

SubTitle String. Gets or sets subtitle. Read/

Write

SubTitleFont IFontDisp. Gets or sets standard OLE font

for chart subtitle.

SummaryFields “SummaryFieldDefinitions Collection”.

Gets the summary fields Collection.

Read/ Write

Read only

Suppress Boolean. Gets or sets the object visibility. Read/

Write

Restriction in event handler

Can be written only when formatting idle.

None

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

None

Can be written only when formatting idle or active.

Crystal Reports Technical Reference Guide 81

GraphObject Object

Property Description

Read/ Write

Title String. Gets or sets the title. Read/

Write

TitleFont IFontDisp. Gets or sets standard OLE font

for chart title.

Top Long. Gets or sets the object upper top

position, in twips.

To pL in e St yl e “CRLineStyle”. Gets or sets the top line

style.

ViewingAngle “CRViewingAngle”. Gets or sets the

viewing angle.

Width Long. Gets or sets the object width, in

twips.

Read/ Write

XAxisTitle String. Gets or sets the title for X axis. Read/

Write

Y2AxisTitle String. Gets or sets the title Y2 axis. Read/

Write

YAxisTitle String. Gets or sets the title for Y axis. Read/

Write

ZAxisTitle String. Gets or sets the title for Z axis. Read/

Write

Restriction in event handler

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Remarks

Properties Max/MinData/SeriesAxisValue will be ignored if the corresponding AutoRangeData/SeriesAxis property is set to TRUE. If the Max/ MinDataDataAxis/Series properties are set at runtime, then the corresponding AutoRangeData/SeriesAxis must be set to FALSE.

This property must be set to FALSE... ...or this property will be ignored

AutoRangeData2Axis MaxData2AxisValue AutoRangeDataAxis MaxDataAxisValue AutoRangeData2Axis MinData2AxisValue AutoRangeDataAxis MinDataAxisValue AutoRangeSeriesAxis MaxSeriesAxisValue AutoRangeSeriesAxis MinSeriesAxisValue

82 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

GroupNameFieldDefinition Object

The GroupNameFieldDefinition Object provides properties and methods for retrieving information on a group name field found in a report (for example, number of group, value type). A GroupNameFieldDefinition Object can be obtained from the Field property of the “FieldMappingData Object” when the specified field is a group name field or from a “GroupNameFieldDefinitions

Collection” retrieved from the GroupNameFields property of the “Report Object”.

GroupNameFieldDefinition Object Properties

Examples

“How to format a group in the section format event” on page 200

Property Description

GroupName ConditionFormula

GroupNameField Name

GroupNumber Integer. If the area is a group, this gets the

Kind “CRFieldKind”. Gets which kind of field

Name String. Gets the field definition unique

NextValue Variant. Gets the field next value. Read

NumberOfBytes Integer. Gets the number of bytes required

Parent “Report Object”. Gets reference to the

PreviousValue Variant. Gets the field previous value. Read

Value Variant. Gets the field current value. Read

Va lu eTy pe “CRFieldValueType”. Gets which type of

String. Gets or sets the group name condition formula.

String. Gets the group name field name. Read

group number. Otherwise, exception is thrown.

(for example, database, summary, formula).

formula name in Crystal Report formula syntax.

to store the field data in memory.

parent object.

value is found in the field.

Read/ Write

Read/ Wri te

only Read

only

Read only

only

Read only

only

Read only

Restriction in event handler

Can be written only when formatting idle.

None

Can be read only when top-level Report object is formatting active.

None

Can be read only when top-level Report object is formatting active.

None

Crystal Reports Technical Reference Guide 83

GroupNameFieldDefinitions Collection

The GroupNameFieldDefinitions Collection is a collection of named groups in the report. Access a specific “GroupNameFieldDefinition Object” in the collection using the Item property.

GroupNameFieldDefinitions Collection Properties

Property Description

Count Long. Gets the number of group name field

definitions in the Collection.

Item (indexAs Long)

Parent “Report Object”. Gets reference to the parent object. Read

“GroupNameFieldDefinition Object”. Gets the

specified object from the Collection. Item has an index parameter that is the 1-based index number of the Object in the Collection. The items in the collection are indexed in the order they were added to the report.

Remarks

Instead of using the Item property as shown, you can reference a group name field directly (for example, GroupNameFieldDefinitions(1)).

Read/ Write

Read only

only

LineObject Object

The LineObject Object represents a line drawn on a report. This object provides properties for getting information for lines on a report.

LineObject Object Properties

Property Description

Bottom Long. Gets or sets the line lower bottom

position, in twips.

Condition Formula

String. Gets or sets the condition formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables.

Read/ Write

Read/ Wri te

Restriction in event handler

None

Restriction in event handler

Can be written only when formatting idle.

84 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Property Description

CssClass String. Gets or sets the cascading style

sheet Class.

Read/ Write

Read/ Wri te

EndSection “Section Object”. Gets the end section. Read

only

ExtendToBottom OfSection

Kind “CRObjectKind”. Gets which kind of object

Left Long. Gets or sets the object upper left

Boolean. Gets or sets the extend to bottom of section option.

(for example, box, cross-tab, field).

position, in twips.

Read/ Wri te

Read only

Read/ Wri te

LineColor OLE_COLOR. Gets or sets the line color. Read/

Wri te

LineStyle “CRLineStyle”. Gets or sets the line style.

See Remarks below.

LineThickness Long. Gets or sets the line thickness, in

twips.

Read/ Wri te

Name String. Gets or sets object name. Read/

Wri te

Parent “Section Object”. Gets reference to the

parent object.

Right Long. Gets or sets the line lower right

position, in twips.

Read only

Read/ Wri te

Suppress Boolean. Gets or sets the object visibility. Read/

Wri te

Top Long. Gets or sets the object upper top

position, in twips.

Read/ Wri te

Restriction in event handler

Can be written only when formatting idle.

None

Can be written only when formatting idle.

None

Can be written only when formatting idle.

None

Can be written only when formatting idle.

Remarks

For property LineStyle, crLSDoubleLine and crLSNoLine are not valid.

Crystal Reports Technical Reference Guide 85

MapObject Object

The MapObject Object represents a geographic map object in a report. This object provides properties for getting information for Map objects in a report.

MapObject Object Properties

Examples

“How to format a map object” on page 187

Property Description

BackColor OLE_COLOR. Gets or sets the object

background color.

BorderColor OLE_COLOR. Gets or sets the object

border color.

BottomLine Style

CloseAtPage Break

Condition Formula

CssClass String. Gets or sets the cascading style

HasDrop Shadow

Height Long. Gets or sets the object height, in

KeepTogether Boolean. Gets or sets the keep object

Kind “CRObjectKind”. Gets which kind of

Left Long. Gets or sets the object upper left

LeftLineStyle “CRLineStyle”. Gets or sets the left

“CRLineStyle”. Gets or sets the bottom

line style. Boolean. Gets or sets the close border

on page break option. String. Gets or sets the condition

formula. The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables.

sheet Class. Boolean. Gets or sets the border drop

shadow option.

twips.

together option.

object (for example, box, cross-tab, field).

position, in twips.

line style.

Read/ Write

Read only

Read/ Write

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

None

Can be written only when formatting idle or active.

86 Crystal Reports Technical Reference Guide

3 : Report Designer Component Object Model

Property Description

Name String. Gets or sets the object name. Read/

Parent “Section Object”. Gets reference to the

parent object.

RightLineStyle “CRLineStyle”. Gets or sets the right

line style.

Suppress Boolean. Gets or sets the object

visibility.

Top Long. Gets or sets the object upper top

position, in twips.

To pL in e St yl e “CRLineStyle”. Gets or sets the top

line style.

Width Long. Gets or sets the object width, in

twips.

Read/ Write

Write Read

only Read/

Write Read/

Write

Restriction in event handler

Can be written only when formatting idle.

None

Can be written only when formatting idle or active.

ObjectSummaryFieldDefinitions Collection

ObjectSummaryFieldDefinitions is a Collection of “SummaryFieldDefinition

Object” Objects.

ObjectSummaryFieldDefinitions Collection Properties

Property Description

Count Long. Gets the number of object summary field

definitions in the Collection.

Item (indexAs Long)

Parent “Report Object”. Gets reference to the parent object. Read

“SummaryFieldDefinition Object”. Gets the specified

object from the Collection. Item has an index parameter that is the 1-based index number of the Object in the Collection. The items in the collection are indexed in the order they were added to the report.

Read/ Write

Read only

only

Restriction in event handler

None

ObjectSummaryFieldDefinitions Collection Methods

The following methods are discussed in this section:

• “Add Method (ObjectSummaryFieldDefinitions Collection)” on page 88

• “Delete Method (ObjectSummaryFieldDefinitions Collection)” on page 88

Crystal Reports Technical Reference Guide 87

OlapGridObject Object

Add Method (ObjectSummaryFieldDefinitions Collection)

Use the Add method to add the specified object summary field to the ObjectSummaryFieldDefinitions Collection.

Syntax

Sub Add (summaryField)

Parameter

Delete Method (ObjectSummaryFieldDefinitions Collection)

Use the Delete method to remove the specified object summary field from the ObjectSummaryFieldDefinitions Collection.

Syntax

Sub Delete (index As Long)

Parameter

Parameter Description

summaryField Specifies the object summary field that you want to add to

the Collection.

Parameter Description

index Specifies the object summary field that you want to delete from

the Collection.

OlapGridObject Object

The OlapGridObject Object represents an Olap Object in a report.

OlapGridObject Object Properties

Examples

“How to format an olap grid object” on page 188

Property Description

BackColor OLE_COLOR. Gets or sets the object

background color.

BorderColor OLE_COLOR. Gets or sets the object

border color.

88 Crystal Reports Technical Reference Guide

Read/ Write

Restriction in event handler

Can be written only when formatting idle or active.

3 : Report Designer Component Object Model

Property Description

BottomLineStyle “CRLineStyle”. Gets or sets the

bottom line style.

CloseAtPageBreak Boolean. Gets or sets the close

border on page break option.

ConditionFormula String. Gets or sets the condition

formula. The condition formula can

Read/ Write

Read/

Write be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or print-time formulas. Condition formulas cannot have shared variables.

HasDropShadow Boolean. Gets or sets the border

drop shadow option.

Height Long. Gets the object height, in

twips.

KeepTogether Boolean. Gets or sets the keep object

together option.

Kind “CRObjectKind”. Gets report object

kind.

Left Long. Gets or sets the object upper

left position, in twips.

LeftLineStyle “CRLineStyle”. Gets or sets the left

line style.

Read/

Write

Read

only

Read/

Write

Read

only

Read/

Write

Read/

Write

Name String. Gets or sets the object name. Read/

Write

Parent “Section Object”. Gets reference to

the parent object.

RightLineStyle “CRLineStyle”. Gets or sets the

right line style.

Suppress Boolean. Gets or sets the object

visibility.

Top Long. Gets or sets the object upper

top position, in twips.

TopLineStyle “CRLineStyle”. Gets or sets the top

line style.

Width Long. Gets the object width, in

twips.

Read

only

Read/

Write

Read/

Write

Read/

Write

Read/

Write

Read

only

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

None

Can be written only when formatting idle or active.

None

Can be written only when formatting idle or active.

Crystal Reports Technical Reference Guide 89

OleObject Object

The OleObject Object represents an OLE object in a report. This object provides properties for getting information for OLE objects in a report.

OleObject Object Properties

Examples

“How to format an OLE object” on page 189

Property Description

BackColor OLE_COLOR. Gets or sets the object

BorderColor OLE_COLOR. Gets or sets the object

Bottom Cropping

BottomLine Style

CloseAtPage Break

Condition Formula

CssClass String. Gets or sets the cascading style

Formatted Picture

HasDrop Shadow

Height Long. Gets or sets the object height, in

KeepTogether Boolean. Gets or sets the keep object

Kind “CRObjectKind”. Gets which kind of

background color.

border color. Long. Gets or sets the bottom cropping

size, in twips.

“CRLineStyle”. Gets or sets the bottom

line style. Boolean. Gets or sets the close border on

page break option. String. Gets or sets the condition formula.

The condition formula can be based on recurring records or on summary fields, but it cannot be based on print-time fields, such as running totals or printtime formulas. Condition formulas cannot have shared variables.

sheet Class. IPictureDisp. Gets or sets the specified

picture during formatting.

Boolean. Gets or sets the border drop shadow option.

twips.

together option.

object (for example, box, cross-tab, field).

Read/ Write

Read/ Wri te

Read only

Restriction in event handler

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be written only when formatting idle or active.

Can be written only when formatting idle.

Can be read or written only when top-level Report object is formatting active.

Can be written only when formatting idle or active.

None

90 Crystal Reports Technical Reference Guide

Business objects CRYSTAL REPORTS 9 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

About Crystal Enterprise

About the guide

Chapter contents

Product registration

Crystal Care technical support

Crystal Training

Crystal Consulting

Document conventions

What’s New in the RDC 2

Report Designer Component 9 (RDC)

Connection information property bags

Field elements in text objects

Cascading Style Sheets

Exporting options

Paginated export to Excel, PDF, RTF, and Word formats

Printing options

Additional export options

Charting options

Condition formulas

Group name condition formulas

Source for linked OLE objects

Additional information

Overview of the Report Designer Object Model

Unification of the RDC object model

Runtime licensing

Object naming conflicts

Objects and Collections

Creatable Objects

Application Object

Application Object Methods

Area Object

Area Object Properties

Area Object Methods

Areas Collection

Areas Collection Properties

BlobFieldObject Object

BlobFieldObject Object Properties

BoxObject Object

BoxObject Object Properties

ConnectionProperty Object

ConnectionProperty Object Properties

Common Connection Properties

ConnectionProperties Collection

ConnectionProperties Collection Properties

ConnectionProperties Collection Methods

CrossTabGroup Object

CrossTabGroup Properties

CrossTabGroups Collection

CrossTabGroups Collection Properties

CrossTabGroups Collection Methods

CrossTabObject Object

CrossTabObject Object Properties

Database Object

Database Object Properties

Database Object Methods

DatabaseFieldDefinition Object

DatabaseFieldDefinition Object Properties

DatabaseFieldDefinitions Collection

DatabaseFieldDefinitions Collection Properties

DatabaseTable Object

DatabaseFieldDefinitions Collection Methods

DatabaseTable Object Properties

DatabaseTable Object Methods

DatabaseTables Collection

DatabaseTables Collection Properties

DatabaseTables Collection Methods

ExportOptions Object

ExportOptions Object Properties

ExportOptions Object Methods

FieldDefinitions Collection

FieldDefinitions Collection Properties

FieldElement Object

FieldDefinitions Collection Methods

FieldElement Object Properties

FieldElements Collection

FieldElement Object Methods