Understanding Crystal Report Viewers

The integration of Crystal Reports in Visual Studio .NET and availability of wizards and tools has made writing reports a piece of cake for developers. Visual Studio .NET hides all the details from developers and provides them easy to use user interface so they can concentrate on designing the layouts of the reports. But it's always a good idea to understand what goes under the hood. In this article, I will explore the Crystal Report Viewers and their functionality.

Crystal Report Viewers work as a container of a report and allow us to view a crystal report in Windows and Web applications. Crystal Reports for Visual Studio .NET provides two report viewers - Windows Forms Viewer and Web Forms Viewer. As you can guess from these names, Windows Forms Viewer control is used to view reports in Windows Forms applications and Web Forms Viewer is used to display reports in Web Forms applications.

Crystal Reports Viewer for Windows Forms

The CrystalReportViewer class defined in the CrystalDecisions.Windows.Forms namespace represents a Crystal Report Viewer for Windows Forms (viewer afterwards). This class is a user control and can be used as any other user controls. This control is available in the Toolbox and you can simply drag it to a Form to add the control to the form.

To view a report in the viewer, you simply need to set the ReportSource property of the control. The ReportSource property can be either a full name of the report file, a strongly typed report, or a ReportDocument object.

The following code snippet binds a report with hard coded full path of the report to the viewer:

crystalReportViewer1.ReportSource = @"C:\temp\Customers.rpt";

The following code snippet binds a strongly typed report to the viewer:

Customers custReport = new Customers();
crystalReportViewer1.ReportSource = custReport;

The following code snippet creates a ReportDocument object, loads a report using the Load method and binds the ReportDocument object to the viewer:

CrystalDecisions.CrystalReports.Engine.ReportDocument doc =
new CrystalDecisions.CrystalReports.Engine.ReportDocument();
doc.Load(@"C:\temp\Customers.rpt");
crystalReportViewer1.ReportSource = doc;

See my article Introduction to Crystal Reports in .NET to understand how to add a Crystal Report Viewer to a Windows Forms application and how to generate a strongly typed report.

Customizing the Behavior of Crystal Report Viewer

Using the CrystalReportViewer class members, we can customize the behavior of the viewer such as disabling or enabling viewer toolbar buttons, adding custom zoom factor, or moving to different views of the report programmatically. The default Crystal Report Viewer looks like the following:

The first four buttons on the viewer allow us to move first, previous, next, and last page of the report. The next button can be used to jump to a particular page. Next three buttons are used to close the view, print the report, and refresh the report respectively.

Next button allows you to export reports as to various files such as a pdf, tif, doc, or rtf. The next button is a toggle for grouping if a report has groups. Next two buttons are for zooming and search.

By using the properties and methods of CrystalReportViewer , we can customize the default settings of the viewer. Some of the common properties of CrystalReportViewer are following:

ActiveViewIndex and ViewCount

A page in the report is called a view. The active page is called active view. The ActiveViewIndex property gets or sets the active view in the viewer and ViewCount returns total number of views in a report.

DisplayToolbar

You can display or hide the toolbar using this property. The following code snippet hides the toolbar.

crystalReportViewer1.DisplayToolBar = false;

ShowCloseButton, ShowExportButton, ShowGotoPageButton, ShowGroupTreeButton, ShowPrintButton, ShowRefreshButton, ShowTextSearchButton, and ShowZoomButton properties can be used to show or hide the respective buttons.

CrystalReportViewer Methods

We can manage the functionality of the viewer buttons programmatically using its members. The CrystalReportViewer class provides methods to export, print, refresh, close, search, zoom, and navigation functionality. The following table lists the CrystalReportViewer class methods:

CloseView	Closes a view tab in the viewer.
DrillDownOnGroup	Drills down on a group.
ExportReport	Exports the report displayed in the viewer.
GetCurrentPageNumber	Gets the current page number of the report.
PrintReport	Prints the report displayed in the viewer.
RefreshReport	Refreshes the report displayed in the viewer.
SearchForText	Searches the report for the given text.
ShowFirstPage	Shows the first page of the report.
ShowGroupTree	Shows the group tree in the viewer.
ShowLastPage	Shows the last page of the report.
ShowNextPage	Shows the next page of the report.
ShowNthPage	Shows the specified page of the report.
ShowPreviousPage	Shows the previous page of the report.
Zoom	Changes the magnification level of the viewer

I will cover Crystal Report Viewer for Web Forms in my forthcoming articles.