CrystalReportViewer Object Model

From the user’s perspective, the CrystalReportViewer control is only used to preview reports. But, from the programmer’s perspective, it offers much more. The CrystalReportViewer object model, shown in Figure 14-x, has properties and methods that give you the ability to modify the report object, change the look and feel of the viewer, and respond to reporting events.

Figure 14-3. The CrystalReportViewer object model.

As you can see in Figure 14-x, there is a different object model for the Windows viewer and the web viewer. The web object model has more properties because web forms have options for how a page is displayed in a browser (e.g. CSS files, setting URL locations, etc.).

Although the viewer can be used to modify properties of the report object, it isn’t recommended that you do so. It is a lightweight alternative for updating the ReportDocument and only exposes a few properties. You can use it when you only need want to perform basic tasks. The problem with using the viewer to modify the report is that it conflicts with changes made directly to the ReportDocument object. Crystal Reports can use changes made to either the viewer or the ReportDocument object, but not both, and it will not keep all the changes. It is best to always make changes using the ReprotDocument class to prevent possible conflicts that will require debugging.

If you do wish to use the viewer to modify the report, there are three properties that you need to be aware of and they are covered throughout this book. The RecordSelection property filters the report data. The ParameterFieldInfo property is the ParameterFields collection (discussed in Chapter 16). The LogOnInfo property (discussed in Chapter 17) is a collection of TableLogOnInfo objects for setting the user credentials for each table.

You should use the properties of the viewer class to make changes to its visual layout. For example, you can customize the look so that it blends in with the formatting of the rest of your application. You can hide buttons that aren’t necessary or replace their functionality with your own buttons. The custom properties were already discussed in detail in Chapter 1 and you can see that names used in the object model are self-explanatory.