This is an excerpt from the book Crystal Reports .Net Programming.
Click to read
The Crystal ReportDocument Object
The ReportDocument class is the base class for all reports. Its properties give an application the ability to thoroughly examine all the report objects. Many of these properties, but not all of them, have write capabilities so that you can modify their values.
Each report is a class that inherits from the ReportDocument class. Figure 14-1 shows the Object Browser window with the class for a blank report, CrystalReport1. 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.
Figure 14-1. Object Browser view of the ReportDocument class.
The ReportDocument class has seven other classes that it references. Figure 14-2 shows the ReportDocument object model. 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 different chapters. This chapter gives you an overview of all the classes and goes into detail on the two generic classes SummaryInfo class and ReportOptions class.
Figure 14-2. The ReportDocument object model.
Every report in Visual Studio is saved as a class. Since it is a class, you have to declare an object variable and instantiate it. 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 3. Either method gives you access to the properties of the object variable to manage the different collections.
Retrieving Summary Information
Every report has a variety of summary information saved with it. This information is set by the report designer and it usually consists of things such as the report author, the report title and report comments. 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. 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. There are only a half dozen properties that this class exposes (see Table 14-1).
Table 14-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. CrystalReport1 is the class for a generic report. Replace it with the class name of your own report.
Dim MyReport As New CrystalReport1
MessageBox.Show(MyReport.SummaryInfo.ReportAuthor)
Setting the Report Options
The ReportOptions class only has a few properties that can be set. They are listed in Table 14-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 14-2. Properties of the ReportOptions class.
| Property | Description |
|---|
| EnableSaveDataWithReport | Saves the latest data with the report. Allows report to be opened without a live data connection. |
| 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 CrystalReport1
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. This class is described in Chapter 17.
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. Table 14-3 lists the properties.
Table 14-3. PrintOptions properties.
| Property | Description |
|---|
| PageMargins | Gets the page margins. |
| ApplyPageMargins() | Sets new page margins. |
| PaperOrientation | Switch between Landscape and Portrait. |
| PaperSize | Set the paper size using pre-defined size constants. |
| PaperSource | Set the tray that the paper is printed from. |
| PrinterName | Change the printer by passing a string that exactly matches the printer name listed in the Printers Control Panel. |
Each of these properties is easy to modify. In same cases you will have to use a predefined constant to set the property (e.g. PaperOrientation and PaperSize).
| Caution |
|---|
| Changing the printer name can cause the report output to be scrambled. Each printer uses a unique printer language for producing output. If the new printer doesn’t use the same printer language as the default printer that the report was designed to use, then the report will not print correctly. For example, if a report was designed for use with an HP printer, then it is okay to switch between similar models of an HP printer. But printing this report to Acrobat PDFWriter will result in an unreadable PDF file. |
Listing 14-4. Change a report’s printer settings.
Dim MyReport As New CrystalReport1
MyReport.PrintOptions.PaperOrientation = CrystalDecisions.[Shared].PaperOrientation.Landscape
MyReport.PrintOptions.PrinterName = “HP LaserJet510”
MyReport.PrintToPrinter(1, False, 0, 0)
Exporting Reports
If your application only sends reports to the printer, 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 19.
Referencing and Formatting the Report Objects
The ReportDefinition class is responsible for maintaining the collections of the basic report objects. These objects consist of the Areas collection, Sections collection 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 15.
Changing Report Objects
Every report can have many types of fields that are used to generate the report, but don't have to appear directly on the report. Some examples are grouping fields, parameter fields, and formula fields. Even though these fields may not be shown directly on the report, they are updateable during runtime and can be used to change the report’s appearance. 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.
Get the best selling Crystal Reports .NET book on the market!
Learn to build .NET 2003 reporting solutions with this expert guide.