This is an excerpt from the book Crystal Reports .Net Programming.
Click to read
CrystalReportViewer Object Model
Previewing reports is done with the CrystalReportViewer control. The viewer can be used as an alternative to the ReportDocument class for modifying reports during runtime. It is a lightweight control and only exposes a few properties. You can use it when you only need want to perform basic tasks.
The viewer exposes three properties for modifying a report. 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. These collections are already found in the ReportDocument class, but they are provided in this class in case you don’t need to work directly with the ReportDocument class.
Figure 14-3. The CrystalReportViewer object model.
| Tip |
|---|
| I prefer making all runtime modifications using only the ReportDocument object and not the CrysalReportViewer control. It is by far the most robust of the two objects. By learning the ReportDocument properties andmethods, you don’t have to learn the viewer class. The only time you can’t perform modifications with the ReportDocument object is when you are writing Report Web Services. This requires using the viewer object to make runtime modifications. |
Responding to Crystal Events
Report classes are built with events that let you respond to the actions that the user is doing as they preview a report. Your application can subscribe to these events and be alerted when they occur. The events that can be subscribed to are primarily associated with the actions that a user takes while previewing a report. Since a user can only preview a report using the CrystalReportViewer, the events are written for this class. The ReportDocument class only has the InitReport() event that can be subscribed to. Table 14-4 lists the reporting related events.
| Note |
|---|
| The CrystalReportViewer also has the standard events associated with all controls (e.g. Click, GotFocus, etc.) However, these are not unique to Crystal Reports, so if you need more information about them, please consult MSDN. |
Table 14-4. The primary events for reports.
| Event | Description |
|---|
| InitReport() | Fired after a report has been successfully loaded. This is the only event available for the ReportDocument class. This is not available for the CrystalReportViewer class. |
| Drill() | Fired when the user drills down on a field. |
| DrillDownSubReport() | Fired when the user drills down on a subreport. |
| HandleException() | Fired when an exception occurs. |
| Navigate() | Fired when a user moves to another page on the report. |
| ReportRefresh() | Fired when the user refreshes the report data. |
| Search() | Fired when the user enters a search string. |
| ViewZoom() | Fired when the user changes the zoom percentage. |
The Drill() event is fired whenever a user clicks on a field to drill down on it. It passes an object of type DrillEventArgs. This object can be examined to find the group level the user is currently looking at as well as the new group level being moved to. Table 14-5 lists the properties of the DrillEventArgs event type.
Table 14-5. Properties of the DrillEventArgs event type.
| Property | Description |
|---|
| CurrentGroupLevel | Returns an integer representing the current group level. |
| CurrentGroupName | Returns a string representing the name of the current group level. |
| NewGroupLevel | Returns an integer representing the new group level. |
| NewGroupName | Returns a string representing the group level name. |
The DrillDownSubReport() event is similar to the Drill() event and it is fired when the user drills down on a subreport. Although the functionality is similar, this event passes an object of the DrillDownSubreportEventArgs type. It gives you information such as the subreport name and the page number. Table 14-6 lists the properties of this event type.
Table 14-6. Properties of the DrillDownSubreportEventArgs event type.
| Property | Description |
|---|
| CurrentSubreportName The name of the current subreport. |
| CurrentSubreportPageNumber | The page number that the subreport is on. |
| CurrentSubreportPosition | Returns a Point object that tells the position of the subreport on the viewer. |
| Handled | Set to true if you do not want the subreport to be drilled down to. |
| NewSubreportName | The name of the new subreport. |
| NewSubreportPageNumber | Sets the page number to drill down into. |
| NewSubreportPosition | Returns a Point object that tells the position of the new subreport on the viewer. |
The HandleException() event is used for capturing exceptions and handling them. This is discussed in detail in the section Handling Exceptions.
The Navigate() event is fired when the user moves to another page in the report. This can be done by paging forward through the report or jumping to the beginning or end of the report. Table 14-7 lists the properties for the NavigateEventArgs event type.
Table 14-7. Properties of the NavigateEventArgs event type.
| Property | Description |
|---|
| CurrentPageNumber | The page number that the report is on. |
| Handled | Set to True if you do not want to move to the new page. |
| NewPageNumber | The page number that the user is moving to. |
The ReportRefresh() event is fired when the user refreshes the report data. The only property for this event is the Handled property. It is the same as the other events.
The Search() event is fired when the user searches for text within the report. Table 14-8 lists the properties for this event type.
Table 14-8. Properties of the SearchEventArgs event type.
| Property | Description |
|---|
| Direction | Gets or sets the direction to be backward or forward. Use a variable of the SearchDirection type. |
| Handled | Set to True if you do not want to search for the text. |
| PageNumberToBeginSearch | Gets or sets the page number to start searching. |
| TextToSearch | Gets or sets the string to search for. |
The ViewZoom() event is fired when the user changes the zoom level of the preview image. This event lets you find out the current zoom level and what the new zoom level will be. Table 14-9 lists the properties for this event type.
Table 14-9. Properties of the ZoomEventArgs event type.
| Property | Description |
|---|
| CurrentZoomFactor | Gets the current zoom factor. |
| Handled | Set to true if you do not want to change the zoom factor. |
| NewZoomFactor | Gets the new zoom factor. |
Handling Exceptions
Crystal Reports gives you the ability to handle any errors that might occur while printing and previewing. The benefit to handling the error yourself is that you can customize the error handling process. For example, you could write the error to a log file or you can gracefully exit the process without throwing an error message at the user.
The CrystalReportViewer class has a HandleException() event that you can subscribe to. It is fired whenever an error occurs. This event has properties to tell you the exception class that was raised and lets you specify a new text message for the error. Table 14-10 lists the properties for the ExceptionEventArgs() type.
Table 14-10. Properties of the ExceptionEventArgs event type.
| Property | Description |
|---|
| Exception | The class of exception that was raised. |
| Handled | Set to True if you do not want to the error triggered. |
| UserData | Overrides the error message. |
Unfortunately, the HandleException() event is not available if you are using the ReportDocument class. If you are printing a report directly with the ReportDocument class, there is no error-related event that you subscribe to. You have to use the standard Try-Catch error handling statements that you use for the rest of your application.
Try
Dim myReport As New CrystalReport1()
myReport.PrintToPrinter(1, False, 0, 0)
Catch
... do error handling here
End Try
To read all my books online, click here for the Crystal Reports ebooks.
Get the best selling Crystal Reports .NET book on the market!
Learn to build .NET 2003 reporting solutions with this expert guide.