Understanding the Parameter Classes

The parameter object model is designed to give you complete control over almost every property of the parameter. The majority of the class properties have write access. This lets you modify parameters during runtime so that you can set the current value and the user isn’t prompted to enter it via the parameter dialog boxes. If you still want the user to use the parameter dialog boxes, you can modify the default values so that you have control over what values they choose from.

The object model uses three different collections to manage parameters. These collections are listed in Table 16-1. The ParameterFieldDefinitions collection manages the parameters in the ReportDocument class. The ParameterFields collection manages the parameters in the CrystalReportViewer class. A parameter can store one value or multiple values. Since a parameter can store multiple values, a collection is used to save this data. This collection is called the ParameterValues collection. It is shared between both ParameterFieldDefinitions and ParameterFields for storing CurrentValues and DefaultValues collections (both are a ParameterValues collection).

Table 16-1. The three types of parameter collections.

It’s important to know which namespace the collections are in. When writing an application, you will refer to these namespaces to access the collections. As an alternative, you can always use the Imports statement (using in C#) so that you don’t have to write out the full namespace name. The code samples in this chapter declare the full namespace so that you can learn them.

The naming convention for the parameter classes gives them the potential to be confusing to learn. The class DataDefinition uses the classes ParameterFieldDefinitions and ParameterFieldDefinition. The CrystalReportViewer class has similar class names: ParameterFields and ParameterField. The names are almost the same except that the DataDefinition classes have the word ‘Definition’ appended to them. This helps make it clear which class each is associated with. However, the property name in the DataDefinition class for the ParameterFieldDefinitions collection is called ParameterFields. This is the same name as the collection class in the viewer classes. Having a property that has the same name as a non-compatible class can be very confusing. If you aren’t careful, you might see the ParameterFields property in the DataDefinition class and accidentally look at the object model for the ParameterFields class in the CrystalReportViewer class instead.