Programming the Parameter Classes

Before you can use the parameter classes to pass values to the parameter objects, you need to understand how values are classified. When a report with parameters loads, the user is shown a dialog box to enter values for each parameter. The dialog box frequently shows a pre-populated list of values to choose from. The values in the list are called Default Values. When the user enters a value for a parameter, it could be a single value or possibly multiple values. The value that the user enters is called the Current Value.

A .NET program can modify either the default values or the current values. To design your application so that the user enters all the values on a .NET form and doesn’t get the parameter dialog box, set the current values with your application. On the other hand, you might let the user get prompted with the parameter dialog box but you want to set the default values listed. For example, you can simulate a data-bound listbox by setting the default value list to show data in a table. This is done by overriding the default values that were assigned to the parameter when the report was designed.

When setting parameter values, either set the current value or the default values, but not both. Setting the current value and setting the default values are mutually exclusive operations. If you set a parameter’s current value, then the user never sees the dialog box and the default values are ignored. When you want the user to enter a parameter, set the default values but not the current values. Since there is no current value, the user will be prompted to enter it.

Considering that the parameter field classes of the ReportDocument class and the CrystalReportViewer class look so similar, you might assume that once you learn how to program with one class, you automatically know how to program with the other class. Unfortunately, this is not the case. Although there are many similarities, the differences are significant enough that you have to be very careful to make sure you understand the nuances between them. Paying close attention to the code examples in this section will save you headaches.

From a conceptual standpoint, the parameter objects in the ReportDocument class and the CrystalReportViewer class are the same. Both of them can modify the current values and default values of a parameter. This leads to the question of which one should you use in your application. This is determined by the other functionality your application implements. If your application only needs to modify the parameters, then you can use the CrystalReportViewer class to make these changes. However, if you are making other changes that can only be implemented with the ReportDocument class (e.g. changing formulas or the formatting of report objects) then you have to use the ReportDocument class. The logic is that if you are already working with the ReportDocument classes, then you should continue using these classes to modify the parameters as well. Crystal Decisions officially states that you cannot make report modifications with both classes simultaneously. You have to use one or the other.