Previewing Reports in Windows
Most applications give the user the ability to preview a report before printing it. With Crystal Reports, this is controlled by the CrystalReportViewer control. In fact, using the viewer is the only way to preview a report in your application. The viewer is found in the Toolbox at the bottom of the other components. Double-click on it to add it to your form.
Figure 3-4 The CrystalReportViewer previewing a report.
Figure 3-4 shows the viewer previewing a report. Along the top of the viewer is a toolbar with a variety of navigational buttons. In the center is the report preview window with a Group Tree window to the left of it. Along the bottom is a status bar that shows the page number information and the current zoom factor.
By default, the toolbar buttons and Group Tree window are all enabled. Each of these features has a corresponding property that can be set in design mode, as well as during runtime, so that you can turn them on or off. For example, a report that doesn’t have any groups certainly doesn’t need to show the Group Tree window. You may also want to turn off all these features so that you can create a customized preview form using your own buttons. Having a customized preview form lets you control the user interface by using your own style of buttons. This ensures that your application has a consistent look and feel across all forms.
Table 3-1 lists the properties of the CrystalReportViewer. The properties let you enable or disable the features of the viewer. Table 3-2 lists its methods. The methods let you implement the viewer’s functionality by calling them from your own buttons. Most of these are self-explanatory, but the tables make good reference material.
Table 3-1 CrystalReportViewer Properties
| Property | Description |
|---|---|
| BackgroundImage | Displays a System.Drawing.Image object in the background of the viewer. |
| BackgroundImageLayout | Uses the System.Windows.Forms.ImageLayout enumeration to set how the background image is displayed (Tile, Center, etc.). |
| DisplayBackgroundEdge | A background edge creates a border around the edge of the report page in preview mode. Setting this to False makes the edge of the page flush against the viewer’s window. |
| DisplayGroupTree | Toggles the Group Tree window on and off. |
| DisplayStatusBar | Toggles the status bar at the bottom of the viewer. |
| DisplayToolbar | Toggles the toolbar on and off. |
| EnableDrillDown | Sets whether the user can drill down on reports. |
| EnableToolTips | Toggles the ability to show tooltips when the mouse hovers over a report object. |
| ShowCloseButton | Sets whether the Close button is available. |
| ShowExportButton | Sets whether the Export button is available. |
| ShowGotoPageButton | Sets whether the GotoPage button is available. |
| ShowGroupTreeButton | Sets whether the GroupTree button is available. |
| ShowPageNavigateButtons | Turns page navigation on/off. |
| ShowPrintButton | Sets whether the Print button is available. |
| ShowRefreshButton | Sets whether the Refresh button is available. |
| ShowTextSearchButton | Sets whether the Search button is available. |
| ShowZoomButton | Sets whether the Zoom button is available. |
| Method | Description |
|---|---|
| CloseView() | Pass a null value to close the current view. Pass a view name to close a specific view. |
| DrillDownOnGroup() | Drill down on a specific group. See Chapter 12 for details on implementing this method. |
| ExportReport() | Show the Export dialog box. |
| GetCurrentPageNumber | Return the page number being viewed. |
| PrintReport() | Show the Print dialog box. |
| RefreshReport() | Refresh the report view. The user will be prompted for the parameters and logon information again. |
| SearchForText() | Pass a string to search for. If found, it returns True and moves to the page that has the string. |
| ShowFirstPage() | Move to the first page of the report. |
| ShowGroupTree() | Shows the Group Tree window. It doesn’t take any parameters. There is no corresponding method to hide it. |
| ShowLastPage() | Move to the last page of the report. |
| ShowNextPage() | Move to the next page of the report. |
| ShowNthPage() | Pass an integer to move to that page number. |
| ShowPreviousPage() | Move to the previous page of the report. |
| Zoom() | Pass an integer to set the zoom level. |
Binding Reports to the Windows Viewer
The viewer needs to be told which report to display. This is called binding the report to the viewer. The property used for binding is the ReportSource property. There are three ways to set the ReportSource property: using the CrystalReportDocument component, passing it a non-embedded report filename, and passing it an embedded report class name. Using the CrystalReportDocument is covered in the next section, and the other two methods are covered in Chapter 14 where we discuss runtime report customization.
Using the CrystalReportDocument Component on the Viewer
Adding a CrystalReportDocument component to the form is the easiest way to specify which report to print. Everything about it is visual and there is no code to write. Add it to your form by going to the Reporting section of the Toolbox and double-clicking on it. It will automatically display the Choose a ReportDocument dialog box. This lets you select which report to display. The dropdown control lists all the reports that are part of your project. You can also select the Untyped Report option and set the Filename property. Once you select which report to use, the dialog box closes and the component gets added to your form.
The CrystalReportDocument component has to be on the same form as the viewer control. The viewer can’t reference a CrystalReportDocument component on another form.
After the component is added to the form, tell the viewer to use it by clicking on the viewer’s ReportSource property and selecting the CrystalReportDocument’s name from the dropdown list. When you run the application and open the form, the viewer automatically displays the report to the user.
