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. Since a user can only preview a report using the CrystalReportViewer, the events are written for this class. Table 14-5 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-5. The primary events for reports.
| Event | Description |
|---|---|
| AfterRender( | Fired after the HTML page is rendered. |
| AfterRenderContent( | Fired after the content on the HTML page is rendered. |
| AfterRenderObject( | Fired after each report object is rendered onto the report |
| BeforeRender( | Fired before the HTML page is rendered. |
| BeforeRenderContent( | Fired before the HTML content is rendered. |
| BeforeRenderObject( | Fired before each report object is rendered onto the report. |
| 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. |
| ReportBookmarkNavigation( | Fires after the user navigates to a report part in the same report or another 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 it’s being moved to. Table 14-6 lists the properties of the DrillEventArgs event type.
Table 14-6. Properties of the DrillEventArgs event type.
| Property | Description |
|---|---|
| CurrentGroupLeve | Returns an integer representing the current group level. |
| CurrentGroupNam | Returns a string representing the name of the current group level. |
| CurrentGroupPat | A string representation of the group number and the current group level. |
| NewGroupLeve | Returns an integer representing the new group level. |
| NewGroupNam | Returns a string representing the group level name. |
| NewGroupPat | A string representation of the group number and group level being drilled into. |
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-7 lists the properties of this event type.
Table 14-7. Properties of the DrillDownSubreportEventArgs event type.
| Property | Description |
|---|---|
| CurrentSubreportNam | The name of the current subreport. |
| CurrentSubreportPageNumbe | The page number that the subreport is on. |
| CurrentSubreportPositio | Returns a Point object that tells the position of the subreport on the viewer. |
| Handle | Set to true if you do not want the subreport to be drilled down to. |
| NewSubreportNam | The name of the new subreport. |
| NewSubreportPageNumbe | Sets the page number to drill down into. |
| NewSubreportPositio | Returns a Point object that tells the position of the new subreport on the viewer. |
TheHandleException() event is used for capturing exceptions and handling them. This is discussed in detail in the section Handling Exceptions.
TheNavigate() 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-8 lists the properties for the NavigateEventArgs event type.
Table 14-8. Properties of the NavigateEventArgs event type.
| Property | Description |
|---|---|
| CurrentPageNumbe | The page number that the report is on. |
| GroupPat | A string representation of the group number and the current group level. |
| Handle | Set to True if you do not want to move to the new page. |
| NewPageNumbe | The page number that the user is moving to. |
TheReportRefresh() 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-9 lists the properties for this event type.
Table 14-9. 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. |
TheViewZoom() 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-10 lists the properties for this event type.
Table 14-10. Properties of the ZoomEventArgs event type.
| Propert | Description |
|---|---|
| CurrentZoomFacto | Gets the current zoom factor. |
| Handled | Set to true if you do not want to change the zoom factor. |
| NewZoomFacto | Gets the new zoom factor. |
