CR.

NET Book by Bischof- Chapter 3 - Copyright 2003 Page 1 of 8

The process of designing reports consists of connecting to data sources and laying out the report objects
on the different report sections. When you are finished with the report it will stay the same every time it
is run. The data that it prints will change, but the report format stays the same. With Crystal Reports
for .NET, reports can give you the flexibility to make your reports dynamic. With .NET, a report is an
object-oriented class with the entire object model being exposed to your .NET program. Whether you
program with VB.NET or C# isn't important. The object model can be accessed by any of the .NET
languages.
There are three ways to use the Crystal Reports object model. The first is to use the ReportDocument
class to access virtually every class and property of the report. You can read every property of a report
and many of them can be written to during runtime. The second way is connecting and previewing a
report with the CrystalReportViewer. You can modify the properties that effect logging in to a database,
setting report parameters, and deciding which report to preview. The last way to work with the object
model is to subscribe to the events that are triggered while the report is previewed and printed. These
events are useful for knowing what part of the report is being looked at and what the user is doing. This
chapter goes into detail on all three ways of working with the report classes.

! ! " # $ % &'
! !
! ( )( *
! ! ! ! + (
, + ! + #

The ReportDocument class is the base class for all reports. It exposes properties that give your
application the ability to thoroughly examine all the report objects. Many of these properties have write
capabilities so that you can modify their values.
Each report is a class that inherits from the ReportDocument class. Figure 3-1 shows the Object
Browser window with the class for a blank report, CrystalReport1, expanded. You can see that
ReportClass is the base class for the report this class is derived from the ReportDocument class. The
members listed to the right of the figure belong to the ReportDocument class.

http://www.WillyDev.Net
CR.NET Book by Bischof- Chapter 3 - Copyright 2003 Page 2 of 8

Figure 3-1. Object Browser view of the ReportDocument class.

The ReportDocument class has seven other classes that it references. Figure 3-2 shows the
ReportDocument object model. As you can see, the class thoroughly exposes all the objects of a report.
Since the coverage is so broad and hits many topics covered in this book, the relevant classes are
covered in the appropriate chapters. For example, the classes for logging into a database, Table and
LogOnInfo, are covered in Chapter 14. The remainder of this section summarizes all the classes and
goes into detail on the two classes that aren't covered elsewhere in this book: SummaryInfo class and
ReportOptions class.

http://www.WillyDev.Net
CR.NET Book by Bischof- Chapter 3 - Copyright 2003 Page 3 of 8

Figure 3-2. The ReportDocument object model.

Every report in Visual Studio is saved as a class. Since it is a class, you can't access it directly. You
need to use an instance of the class via an object variable. There are two ways to create this object
variable. You can declare and instantiate it yourself, or you can add a ReportDocument component to
your form. Both of these methods were discussed in Chapter 2. Use the properties of the object variable
to gain access to the different collections.

Retrieving Summary Information

Various summary information is saved with each report. This information is set by the report designer
and it usually consists of such things as the report author and the report title. This information is set
during design mode by right-clicking on the report and selecting Report/Summary Info. The class that
maintains this summary information is the SummaryInfo class. There are only a half dozen poperties
that this class exposes. They are listed in Table 3-1. Although you can override the property values,
more than likely, you will only want to read from these values. This information was set by the report
designer and won't need to change during runtime.
Table 3-1. Properties of the SummaryInfo class.
Property Description
KeywordsInReport The keywords in the report.
ReportAuthor The author of the report.
ReportComments Comments about the report.
ReportSubject The subject of the report.
ReportTitle The title of the report.
The following example displays a message box showing the author of a report. You can see that
accessing these properties is very simple.
Dim myReport As New Report1()
MessageBox.Show(myReport.SummaryInfo.ReportAuthor)

http://www.WillyDev.Net
CR.NET Book by Bischof- Chapter 3 - Copyright 2003 Page 4 of 8

Setting the Report Options

The ReportOptions class only has a few properties that you can set. They are listed in Table 3-2. This
information is set during design mode by right-clicking on the report and selecting Designer/Default
Settings and selecting the Reporting tab. These properties were discussed in Chapter 2.
Table 3-2. Properties of the ReportOptions class.
Property Description
EnableSaveDataWithReport Automatically saves the latest data with the report.
EnableSavePreviewPicture Saves a thumbnail picture of the report.
EnableSaveSummariesWithReport Saves data summaries with the report.
The following example sets the EnableSaveDataWithReport property to True.
Dim myReport As New Report1()
myReport.ReportOptions.EnableSaveDataWithReport = True

Connecting to the Data Sources

The Database class is used for examining the tables used in a report and their relationships with each
other. It's also used for setting the login information before opening the report. The two collections that
is references are the Tables collection and the TableLinks collection. This class is described in Chapter
14.

Modifying the Printing Options

The PrintOptions class stores the options for how a report is sent to the printer. This can consist of the
destination printer, the paper orientation or the page margins. This is normally set during design mode.
While the majority of an application's reports will use the same settings, you can override the default
settings for specific reports. This is discussed in Chapter 19.

Exporting Reports
If your application can only send reports to the printer, then it is lacking the functionality to make your
data accessible to a variety of applications. Crystal Reports lets you export a report in many different
formats so that different applications can read the data. For example, you can export report data to an
Excel spreadsheet so that an end user can perform a statistical analysis on the data. The ExportOptions
class has the properties that specify the exporting options. This is discussed in Chapter 16.

Formatting the Report Objects

The ReportDefinition class is responsible for maintaining the collections of the basic report objects.
These objects consist of the Sections collections and the ReportObjects class. Each Section class
contains the report objects that are within that section. You can modify the formatting properties of any
of these objects. This is discussed in Chapter 7.

Changing Report Fields

Every report can have many types of fields that are used to generate the report, but don't necessarily
appear directly on the report. Some examples are grouping fields, parameter fields, and formula fields.
These fields are updateable during runtime and can be used to make your report appear totally different.
For example, you can change the grouping field so that the report sorts and summarizes in a new way.
The DataDefinition class manages the collections that control these aspects of the report. These
collections are discussed in the appropriate chapters throughout the book.

http://www.WillyDev.Net
CR.NET Book by Bischof- Chapter 3 - Copyright 2003 Page 5 of 8

Previewing reports is done with the CrystalReportViewer control. When you add this control to a form
[1]
and link it to a report, the user is able to preview the report before printing it The viewer exposes two
collections that are necessary for connecting to a report. These collections control logging in to the
different data sources as well as setting the parameter fields. These collections are already found in the
ReportDocument class, but they are provided in this class because they are the most commonly used. In
other words, it is often required to set the login and parameter information before connecting to a report.
The viewer exposes the LogOnInfo collection and the ParameterFields collection. The LogOnInfo
collection is discussed in Chapter 14. The ParameterFields collection is discussed in Chapter 5. The
CrystalReportViewer object model is shown in Figure 3-x.

Figure 3-3. The CrystalReportViewer object model.

Report classes are built with events that let you know the details of what the user is doing as they
preview a report. Your application can subscribe to these events and be alerted to what the user is doing.
Table 3-3 lists the reporting related events.

) -( $ .! #
/ 0 12 3
4% )

The events that you can subscribe to are primarily associated with the actions that a user takes while
previewing a report. Since a user can only preview a report using the CrystalReportViewer, the events

http://www.WillyDev.Net
CR.NET Book by Bischof- Chapter 3 - Copyright 2003 Page 6 of 8

are written for this class. The ReportDocument class only has the InitReport() event that can be
subscribed to.
Table 3-3. The primary events for reports.
Event Description
InitReport() Fired after a report has successfully loaded. This is the
only event available for the ReportDocument class.
This is not available for the CrystalReportViewer
class.
Drill() Fired when the user drills down on a field.
DrillDownSubReport() Fired when the user drills down on a subreport.
HandleException() Fired when an exception occurs.
Navigate() Fired when a user moves to another page on the report.
ReportRefresh() Fired when the user refreshes the report data.
Search() Fired when the user enters a search string.
ViewZoom() Fired when the user changes the zoom percentage.
The Drill() event is fired whenever a user clicks on a field to drill down on it. It passes an object of
type DrillEventArgs. This object can be examined to find out about the group level the user is currently
looking at as well as the new group level being moved to. Table 3-4 lists the properties of the
DrillEventArgs event type.
Table 3-4. Properties of the DrillEventArgs event type.
Property Description
CurrentGroupLevel Returns an integer representing the current group level.
CurrentGroupName Returns a string representing the name of the current
group level.
CurrentGroupPath
NewGroupLevel Returns an integer representing the current group level.
NewGroupName Returns a string representing the name of the current
group level.
NewGroupPath
The DrillDownSubReport() event is similar to the Drill() event and it is fired when the user drills
down on a subreport. Although their functionality is similar, this event passes an object of the
DrillDownSubreportEventArgs type. It gives you information such as the subreport name, and the page
number. Table 3-5 lists the properties of this event type.
Table 3-5. Properties of the DrillDownSubreportEventArgs event type.
Property Description
CurrentSubreportName The name of the current subreport.
CurrentSubreportPageNumber The page number that the subreport is on.
CurrentSubreportPosition Returns a Point object that tells the position of the
subreport on the viewer.
Handled Set to true if you do not want the subreport to be
drilled down to.
NewSubreportName The name of the new subreport.
NewSubreportPageNumber Sets the page number to drill down into in the
subreport.
NewSubreportPosition Returns a Point object that tells the position of the new
subreport on the viewer.
The HandleException() event is used for capturing exceptions and handling them. This is discussed
in detail in the section Handling Events.
The Navigate() event is fired when the user moves to another page in the report. This can be done by
paging forward through the report or jumping to the beginning or end of the report. Table 3-6 lists the
properties for the NavigateEventArgs event type.

http://www.WillyDev.Net
CR.NET Book by Bischof- Chapter 3 - Copyright 2003 Page 7 of 8

Table 3-6. Properties of the NavigateEventArgs event type.

Property Description
CurrentPageNumber The page number that the report is on.
Handled Set to true if you do not want to move to the new page.
NewPageNumber The page number that the user is moving to.
The ReportRefresh() event is fired when the user refreshes the report data. The only property for this
event is the Handled property. It is the same as the other events.
The Search() event is fired when the user searches for text within the report. Table 3-7 lists the
properties for this event type.
Table 3-7. Properties of the SearchEventArgs event type.
Property Description
Direction Gets or sets the direction to be backward or forward.
Use a variable of the SearchDirection type.
Handled Set to true if you do not want to search for the text.
PageNumberToBeginSearch Gets or sets the page number to start searching.
TextToSearch Gets or sets the string to search for.
The ViewZoom() event is fired when the user changes the zoom level of the preview image. This
event lets you find out the current zoom level and what the new zoom level will be. Table 3-8 lists the
properties for this event type.
Table 3-8. Properties of the ZoomEventArgs event type.
Property Description
CurrentZoomFactor Gets the current zoom factor.
Handled Set to true if you do not want to change the zoom
factor.
NewZoomFactor Gets the new zoom factor.

Crystal Reports gives you the ability to handle any errors that might occur while printing and
previewing. The benefit to handling the error yourself is that this gives you the ability to customize the
error handling process. For example, you could write the error to a log file or you can gracefully exit the
process without throwing an error message at the user.
The CrystalReportViewer class has a HandleException() event that you can subscribe to. It is fired
whenever an error occurs. This event has properties to tell you the exception class that was raised and
lets you specify a new text message for the error. Table 3-9 lists the properties for the
ExceptionEventArgs() type.
Table 3-9. Properties of the ExceptionEventArgs event type.
Property Description
Exception The class of exception that was raised.
Handled Set to true if you do not want to the error triggered.
UserData Overrides the error message.
Unfortunately, the HandleException() event is not available if you are using the ReportDocument
class. If you are printing a report directly with the ReportDocument class, there is no error-related event
that you subscribe to. You have to use the standard Try-Catch error handling statements that you use for
the rest of your application.
The following code demonstrates putting a Try Catch block around printing the report.

http://www.WillyDev.Net
CR.NET Book by Bischof- Chapter 3 - Copyright 2003 Page 8 of 8

Try
Dim myReport As New CrystalReport1()
myReport.PrintToPrinter(1, False, 0, 0)
Catch
... do error handling here
End Try

!
The ReportDocument object model exposes all the properties of your report to you. You can use the
properties and methods to modify a report during runtime. This gives you the ability to make reports
dynamic and customizable by a user's input. This chapter showed the ReportDocument object model and
many of the related class properties and methods. This gives you the foundation to understand the rest of
the object model. Within each chapter of this book that relates to parts of the object model, a full
reference and explanation of how to use the object model is given. At the end of the book is a handy
pullout card that shows the object model with example code snippets.

[1]
Using the CrystalReportViewer is discussed in Chapter 2.

http://www.WillyDev.Net