Delivering Reports with the Windows Forms Viewer

After reports are imported into or referenced from a Visual Studio .NET project, the next obvious step is to have a way to view those reports. This section covers report viewing in Windows Forms applications.

Windows Forms is the new .NET technology for building rich-client applications. It is the evolution of the COM and ActiveX platform that Crystal Reports was so popular in. When it came to .NET, Business Objects decided to write a native .NET control based on the Windows Forms technology. This control is simply called the Windows Forms Viewer. Its corresponding class name is CrystalDecisions.Windows.Forms.CrystalReportViewer.

Like other Windows Forms controls, this control ultimately inherits from the System.Windows.Forms.Control class. It has many public methods and properties that enable you to drive the appearance and behavior. In addition to these runtime capabilities, the Windows Forms Viewer has design-time support to increase the efficiency and ease of using the control. The control can be found in the toolbox on the Windows Forms tab. You can see what the control looks like after being dropped onto a form in Figure 29.3.

Figure 29.3. A Crystal Report displayed in the Windows Forms Viewer control.

The ReportSource Property

Although there are many properties and methods, the ReportSource property is key. It is this property that is used to indicate to the viewer which report it should display. Because the ReportSource property's data type is object, it can accept multiple types of values, the most common of which are listed here:

• Filename The full path to an RPT file as a String object.

• Report object An instance of a CrystalDecisions.CrystalReports.Engine.ReportDocument class. This report should already have been loaded by calling the ReportDocument's Load method.

• Strongly typed report object An instance of a strongly typed report object derived from ReportClass.

The following code shows VB.NET examples of setting these types of report source objects:

' #1  A filename as a string Viewer.ReportSource = "C:\Program Files\My Application\Reports\Sales.rpt" ' #2  a ReportDocument object Dim Report = As New ReportDocument() Report.Load("C:\Program Files\My Application\Reports\Sales.rpt") Viewer.ReportSource = Report ' #3  A strongly-typed report object Dim Report As New SalesReport() Viewer.ReportSource = Report

If the viewer is visible when the ReportSource property is set, it displays the report immediately. If the viewer is not visible yet, that is, the form has not been shown yet, the viewer waits until it is shown onscreen to display the report. After a report source is provided to the viewer, it maintains that report until the viewer is destroyed or another report source is passed into it.

Because the viewer can generically accept report filenames and report objects, a single viewer can be reused for viewing multiple reports. One of the ways you could handle this is to create a form dedicated to report viewing. This form would contain the Windows Forms viewer. To easily invoke this form and pass in a report source, make the viewer a public variable and then create a shared method to accept a report source as an argument. An example of this function is shown here:

Public Shared Sub Display(ByVal ReportSource As Object)     Dim newForm As New ReportViewerForm()     newForm.Viewer.ReportSource = ReportSource     newForm.ShowDialog() End Sub

After this is in place, to invoke the report viewer from anywhere in the application, use the following code:

strReportPath = ... ReportViewerForm.Display(strReportPath)

Customizing the Windows Forms Viewer

There are many properties and methods of the report viewer that can be used to customize its appearance. The first level of customization is to show or hide the individual components of the viewer. The group tree on the left side can be shown or hidden via the DisplayGroupTree Boolean property. The toolbar works the same way via the DisplayToolbar property.

In addition to hiding the entire toolbar, each button or button group on the toolbar has corresponding properties that allow them to be individually hidden or shown. These properties can be found in the property browser or accessed via code. They all start with Show, such as ShowExportButton, ShowPrintButton, and so on. The names should be self-explanatory.

Tip

There is a status bar at the bottom of the viewer that does not have a corresponding show/hide property. It tends to not add a lot of value and ends up more of an annoyance than anything. A trick to hide this status bar is to drop a panel control onto the form and drop the viewer onto the panel. Set the viewer's Dock property to Fill so that the viewer always sizes itself to the size of the surrounding panel. Then set the DockPadding.Bottom property of the viewer to 20. This sizes the height of the viewer to 20 pixels more than the panel, effectively hiding the status bar below the extents of the panel. Keep in mind that any methods and properties that need to be accessed from the report viewer after you've done this need to be accessed via the panel object's controls collection. Figure 29.4 shows the report viewer with no group tree, no toolbar, and the status bar hidden.

Figure 29.4. The Report Viewer is shown here with its status bar hidden.

Another property that can be used to change the behavior of the report viewer is the EnableDrillDown property. Setting this Boolean property to false disables the user from performing any drill-down operations. Finally, the SelectionFormula and ViewTimeSelectionFormula properties can be used to create and append filters to the report. Keep in mind that the filtering is actually done by the report engine, but the report viewer simply exposes the property and then sends the information down to the report engine. The SelectionFormula property should be used when creating or overwriting a selection formula. To append to an existing formula, use the ViewTimeSelectionFormula property, which automatically appends using an AND operator.