Programming with the ReportDocument Class

The ReportDocument class manages every report object in the report. It has a collection class that is fully populated with every report parameter. Each parameter object can be assigned a value prior to printing the report.

To set a parameter’s value, first get a reference to parameter field object. In the ReportDocument class, a parameter field is represented with the ReportFieldDefinition class. Once you have a reference to it, you can modify any of its properties.

The ReportFieldDefinition class has two properties that you are most concerned with: the CurrentValues and DefaultValues collections. Both of these collection objects are of the ParameterValues class. If you recall from Chapter 5, a parameter can have a single value or it can have multiple values. Since it can have more than one value then a collection is needed to store the values. The ParameterValues collection class is where these values are stored.

A parameter is either a discrete value or a range value and each is represented by a different class. The ParameterDiscreteValue class is for discrete values. The ParameterRangeValue class is for range values.

The ParameterDiscreteValue class only has one property to set: Value. This is the parameter’s value. It is of type Object so that you can assign any data type to it as long as it is compatible with the data type that the parameter uses.

The ParameterRangeValue class has four values to set: StartValue, EndValue, LowerBoundType and UpperBoundType. The two value parameters are used to define the lower and upper bounds of the range. The two bound-type parameters are used to set whether the endpoint is inclusive or exclusive. If it is inclusive, then the value is included as part of the range. If it is exclusive, then the endpoint is not included as a part of the range. For example, let’s say the range is 0 to 10 and the LowerBoundType is BoundExclusive and the UpperBoundType is BoundInclusive. This range would include all numbers from 1 to 10. If the bound-type is NoBound, then there will be no bounds for that parameter and you do not need to enter a value for it.

After populating the ParameterValues collection with one or more values, you have to assign it to either the CurrentValues property or the DefaultValues property. Do this by calling the ApplyCurrentValues() method or the ApplyDefaultValues() method. Pass each method the ParameterValues collection object.

Programming parameters with the ReportDocument class consists of 8 steps:

Get a reference to the parameter field object that you want to modify. Use caution when declaring the variables because you have to declare an object of the ParameterFieldDefinition class, but get a reference to it using the ParameterFields property.
Instantiate a ParameterValues collection object.
Instantiate a parameter value object. This will either be of the ParameterDiscreteValue class or the ParameterRangeValue class.
Set the properties of the new parameter value object.
Add the parameter value object to the ParameterValues collection using the Add() method.
Repeat steps 3-5 for each parameter value object.
Assign the ParameterValues collection to the appropriate parameter field property using either the ApplyCurrentValues() method or the ApplyDefaultValues() method.
Set the ReportSource property of the CrystalReportViewer object so that the report gets displayed.

Listing 16-2 illustrates these steps. It creates two parameters that are discrete values and assigns them to the DefaultValues collection. Since we want the user to be prompted with the new default values, then there is no need to modify the CurrentValues property. The inline comments explain the steps that are taking place.

Listing 16-2. Use the report document to modify a discrete parameter.
'Use the ReportDocument object to create two default parameters
Dim MyReport As New CrystalReport1()
Dim ParameterFieldDefinition As _
CrystalDecisions.CrystalReports.Engine.ParameterFieldDefinition
Dim ParameterValues As CrystalDecisions.Shared.ParameterValues
Dim ParameterDiscreteValue As _
CrystalDecisions.Shared.ParameterDiscreteValue
'Step 1:Get a reference to the parameter field to modify
ParameterFieldDefinition = _
MyReport.DataDefinition.ParameterFields.Item("Location")
'Step 2: Instantiate a ParameterValues collection object.
ParameterValues = New CrystalDecisions.Shared.ParameterValues()
'Step 3: Instatiate a ParameterValue object.
'This example uses a discrete value
ParameterDiscreteValue = _
New CrystalDecisions.Shared.ParameterDiscreteValue()
'Step 4: Assign a value to the object
ParameterDiscreteValue.Value = "Louisville, KY"
'Step 5: Add it to the ParameterValues collection using the Add() method
ParameterValues.Add(ParameterDiscreteValue)
'Step 6: Repeat steps 3-5 for additional parameters
ParameterDiscreteValue = _
New CrystalDecisions.Shared.ParameterDiscreteValue()
ParameterDiscreteValue.Value = "San Diego, CA"
ParameterValues.Add(ParameterDiscreteValue)
'Step 7: Assign the ParameterValues collection to the parameter field.
'Do this with either the CurrentValues or DefaultValues collection
ParameterFieldDefinition.ApplyDefaultValues(ParameterValues)
'Step 8: Print or Preview the report
CrystalReportViewer1.ReportSource = MyReport