Responding to 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.
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. |
