Learning the Parameter Classes

Up to this point in the chapter, all the work you’ve done with parameters used the SetParameterValue() method. This method is useful because it is easy to use and it covers over 90% of the work that most people will do with parameters. If the previous sections showed you everything you need to update parameters in your application, then you don’t need the rest of this chapter and you can skip forward. However, as mentioned earlier, the SetParameterValue() method does have its limitations. If you find that you need to do advanced parameter customization, then you need to learn the parameter object model in detail so that you understand each parameter class and the methods and properties available. The remainder of this chapter focuses on explaining the parameter object model and giving you sample code to work with its methods and properties.

The parameter object model is designed to give you complete control over almost every property of parameter. The majority of its 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 the user chooses 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.

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.

The parameter classes are designed with two approaches in mind. The first approach is that you are using the CrystalReportViewer control to preview the report. The second approach is modifying parameters with the ReportDocument object. Both approaches can be used to modify the current value or the default values. But they do so in different ways.

The object model in Figure 16-1 shows two columns of classes. The left column has the classes related to the ReportDocument object. The right column has the classes for the CrystalReportViewer class. At the bottom of the diagram are the classes that store the actual parameter values. These classes are shared by both columns.

Figure 16-1. The classes of the Parameter object model.

When looking at the individual classes of both columns in more detail, you see that there are a lot of similarities between them. Let’s start at the top and work our way down. The top most classes are the ReportDocument class and CrystalReportViewer class. Below the ReportDocument class is the DataDefinition class. Below each class is a collection class that stores the parameters. Under the collection class is the actual parameter field class. The two parameter field classes, ParameterFieldDefinition and ParameterField, have all the properties that you set when using the Create New Parameter dialog box in design mode (e.g. prompt text, min and max values, sort order, etc.). You can see that they have many properties in common.

The parameter field classes use a collection class to store the current values and the default values. The ParameterValues collection holds ParameterValue objects. Since the current value and default value of a parameter can store either a single discrete value or a range of values, there are two classes that are used to represent this. The ParameterDiscreteValue class only holds a single value. The ParameterRangeValue class stores a range value (it has an upper and lower range).

All of the parameter classes have a variety of properties that are enumeration data types. These enumerations are used to store a pre-determined set of values that the property can have. Since there are so many of the enumeration types, they are listed separately from the main parameter object model. See Figure 16-2 for each enumeration used. Since these represent the options that you can set for a parameter, they have already been discussed earlier in Chapter 5.

Figure 16-2. The enumeration constants of the Parameter object model.