Customizing the Report Viewer

If you ve added the Report Viewer ActiveX component to your project, you have a great deal of flexibility in customizing the way the Report Viewer appears and behaves. By default, the RDC will add the Report Viewer to its own form and add a small amount of code to supply the Report object to the Report Viewer and resize the Report Viewer whenever the form is resized.

This default behavior uses just a fraction of the Report Viewer s capabilities. The viewer has many options, exposed by its own library, which will meld it more tightly into your application. You can customize how the Report Viewer looks, what controls and toolbar buttons are available, and the Report Viewer s size . You may even perform all the functions from within code that the built-in toolbar buttons would accomplish. This allows you to make the Report Viewer show virtually no controls but the report itself, if you prefer. You can design a completely separate user interface for page control, zoom levels, printing, exporting, and more.

In addition, the Report Viewer contains a flexible event model that will fire events as the Report Viewer performs various functions, or as a user interacts with it. You can trap button clicks, drill-down selections, changes in the zoom level, and other events. You can execute extra code when any of these events occurs, or intercept the events and cancel them if you wish to not have the Report Viewer complete them.

When you add the Report Viewer to a form (or when it s added automatically by the RDC), you ll see the outline of the Report Viewer appear as an object inside the form. When you select the Report Viewer object, you ll see a large number of design-time properties appear in the Properties box in VB. This is illustrated in Figure 27-5.

Figure 27-5: The Report Viewer and its design-time properties

If you want the Report Viewer to exhibit consistent behavior during the entire application, you can change properties for the Report Viewer at design time, such as which toolbar buttons are shown, whether a report group tree is displayed, whether a user can drill down, and so on.

Most of these properties can also be set at run time by supplying the appropriate values to the Report Viewer object s properties. Because the Report Viewer object actually adds its own COM library to your project, you can get an idea of the object model, properties, methods , and events that are available by looking at the Object Browser. Press F2, or choose View Object Browser from the Visual Basic pull-down menus . Then, choose CrystalActiveXReportViewerLib10Ctl in the library drop-down list to see the object model exposed by the Report Viewer s Library.

Here s some code from the Xtreme Orders sample application that customizes several Report Viewer behaviors. The Print button is turned off on the Report Viewer by setting the EnablePrintButton property to false. The Help button is displayed on the Report Viewer by setting the EnableHelpButton property to true. The Business Objects logo animation control is turned on by setting the EnableAnimationCtrl property to true. And, the EnableDrillDown property determines whether or not a user can double-click a group in the Report Viewer to drill down (if the user chooses to show a detail report, drill-down isn t of benefit).

 CRViewer1.EnablePrintButton = False 
 CRViewer1.EnableHelpButton = True 
 CRViewer1.EnableAnimationCtrl = True 
 
 If frmXtremeOrders.chkSummary Then 
 CRViewer1.EnableDrillDown = True 
 Else 
 CRViewer1.EnableDrillDown = False 
 End If  'frmXtremeOrders.chkSummary 

Trapping Report Viewer Events

The Report Viewer library, in addition to offering a good selection of properties and methods, exposes a large number of events that allow you to trap button clicks, report-processing cycles, and drill-down attempts. These events can be used to modify the behavior of the Report Viewer, to execute some additional supplementary code when a certain event occurs, or potentially to modify report contents while it is being viewed .

A section of CrystalDevHelp.CHM covers programming the Report Viewers. You ll find complete information about which events are available for custom coding. You may also look at the Object Browser. Or, just open the code window for the Report Viewer object and look at the procedure drop-down list in the upper-right corner of the code window.

Because you can trap many events that occur during report processing and user interaction with the Report Viewer, you have tremendous power to customize your reporting application. The Xtreme Orders sample application has only three simple examples of these capabilities. If the user clicks the Help button in the Report Viewer, a message box appears indicating Custom Help Goes Here. When the user drills down on a group, a confirmation message box appears, asking the user to confirm the drill-down. If the answer is Yes, the drill-down will occur. If the answer is No, the drill-down will be canceled. And, after a user drills down and clicks the Close View button (the red X) in the Report Viewer, another confirmation message box appears, asking the user to confirm the closure. As with the original drill-down, the drill-down tab will be closed only if the user answers Yes. Otherwise, the event will be canceled .

One of the more complex parts of these examples is actually determining which group will be affected when the drill-down or drill-down tab closure occurs. Understanding this is crucial for fully exploiting the power of the event model ”trapping these events is probably of little use if you can t determine which group is actually being manipulated. The Report Viewer DrillOnGroup event makes this task easier by passing the GroupNameList parameter into the event function. This zero-based array contains an element for each group that has been drilled into previously, with the current group that is now being drilled into being the last element of the array.

If your report contains only one level of grouping (as does the Xtreme Orders sample report), the GroupNameList will always contain just element 0 ”the group that was drilled down to. However, if your report contains multiple levels of grouping, you ll have the extra benefit of determining how deep and which groups are included in the group that is currently being drilled down to. For example, if your report is grouped on three levels ”Country, State, and City ”a user may first drill down on Canada. This will fire the DrillOnGroup event, and the GroupNameList array will contain only element 0, Canada. Then, in the Canada drill- down tab, the user might double-click BC. This will again fire the DrillOnGroup event, and the GroupNameList array will now contain two elements, Canada in element 0 and BC in element 1. Then, if the user double-clicks Vancouver in the BC drill-down tab, yet another DrillOnGroup event will fire. Inside this event, the GroupNameList array will contain elements 0, 1, and 2 ”Canada, BC, and Vancouver.

If you are concerned about only the lowest level of grouping, just query the last element of the GroupNameList array by using the VB UBound function. Even though the Xtreme Orders report contains only one level of grouping (thereby always allowing GroupNameList(0) to be used to determine the group), the UBound function has been used for upward compatibility.

The other argument passed to the DrillOnGroup event is UseDefault. This Boolean value can be set to true or false inside the event to determine whether the drill-down actually occurs. If UseDefault is set to true (or left as is), the drill-down will occur. If it is set to false inside the DrillOnGroup event, the drill-down will be canceled and no drill-down tab will appear for the group in the Report Viewer.

Here s the sample code from the Xtreme Orders application. Note that the actual group being drilled on is included in the message box and that the results of the message box determine whether or not the drill-down occurs.

 Private Sub CRViewer1_DrillOnGroup(GroupNameList As Variant, _ 
 ByVal DrillType As CrystalActiveXReportViewerLib10Ctl.CRDrillType,_ 
 UseDefault As Boolean) 
 If MsgBox("Are you sure you want to drill down on '" & _ 
 GroupNameList(UBound(GroupNameList)) & _ 
 "'?", vbQuestion + vbYesNo, "Xtreme Orders Report") = vbNo Then 
 UseDefault = False 
 End If  'MsgBox("Are you sure you want to drill down... 
 End Sub 

The other Report Viewer event that is used in the Xtreme Orders sample application is CloseButtonClicked. This event fires whenever a user clicks the red X in the Report Viewer to close the current drill-down tab (known in the Report Viewer object model as the current view ). Again, the sample application simply displays a confirming message box asking whether or not the user really wants to close the drill-down tab. By setting the UseDefault parameter inside the event code, the drill-down tab is closed or not closed, based on the user s choice.

As when drilling down, the actual drill-down tab that s being closed needs to be known inside the event (it s just being included in the message box in this example). Because the CloseButtonClicked event doesn t pass a GroupNameList or similar parameter into the event, a little more sleuthing has to be done to determine what the current view is. This is where both the Report Viewer s GetViewPath method and its ActiveViewIndex property come into play.

The ActiveViewIndex property simply returns an integer (one based) indicating which drill-down tab is the currently selected tab. While this is helpful, it doesn t return the actual string containing the group name of the tab being viewed. This must be accomplished by using the GetViewPath method of the Report Viewer object. This method accepts one argument, a numeric index indicating the tab in the Report Viewer window for which you want to see the view path . The method returns a one-based string array that includes the actual views (or group names ) that are included in the drill-down tab whose index is provided as the argument to GetViewPath. As with GroupNameList, you can then determine the actual name of the current tab being closed by accessing the last element (using the UBound function) of the array.

Examine the following code closely:

 Private Sub CRViewer1_CloseButtonClicked(UseDefault As Boolean) 
 If MsgBox("Close '" & _ 
 CRViewer1.GetViewPath(CRViewer1.ActiveViewIndex) 
 (UBound(CRViewer1.GetViewPath(CRViewer1.ActiveViewIndex))) _ 
 & "' Drill-Down tab?", vbQuestion + vbYesNo, _ 
 "Xtreme Order Report") = vbNo Then 
 UseDefault = False 
 End If  'MsgBox("Close... 
 End Sub 

Note  

Due to width restrictions in the book, the line of sample code in the preceding example that demonstrates the CRViewer1.GetViewPath command is broken after the first right parenthesis. If you look at the sample application, you ll notice that this is a continuous line, which is required for proper VB interpretation of the line.

Notice that GetViewPath is supplied with the ActiveViewIndex property. This will return a string array containing all the groups that are included in the current drill-down tab. Even though the Xtreme Orders report contains only one level of grouping, the UBound function is still used to retrieve the last element of the array returned by GetViewPath. This provides upward compatibility if you ever choose to add multiple groups to the report.

The RDC provides additional Report Viewer support for the familiar Crystal Reports Select Expert and Search Expert, as well as a Text Search feature. Buttons for these tools can be enabled or disabled at design time or run time. And, you can programmatically perform both formula-based and text-based searches with the Report Viewer s SearchByFormula and SearchForText methods.

Caution  

If you are integrating an external .RPT file with the RDC, and you wish to trap drill- down events from within the Report Viewer, ensure that the Create Group Tree option is checked from File Report Options in Crystal Reports. If you don t specifically set this option, you may get an error when the Report Viewer attempts to trap drill-down events.