Multi-Value Report Parameters
- 6 minutes to read
This document describes how to create a multi-value parameter and use this parameter to filter report data. For information on how to use a multi-value parameter in expressions and queries, refer to the following help topic: Use Query Parameters.
Create a Multi-Value Parameter in the Report Designer
Follow the steps below to create a multi-value parameter in the Visual Studio Report Designer:
Create a report parameter and enable the Allow multiple values option (which corresponds to the parameter’s MultiValue property).
Specify a list of predefined values for the parameter. You can create a static list of values or load values from a data source. Refer to the following topics for instructions on how to do it:
Create a Multi-Value Parameter in Code
- Create a StaticListLookUpSettings or DynamicListLookUpSettings class instance and configure it with a set of predefined parameter values.
- Assign the instance to the parameter’s ValueSourceSettings property.
- Enable the parameter’s MultiValue property.
When you process multi-value report parameters in code, you may need to access the list of all parameter values. Refer to the LookUpHelper class description for details on how you can complete this task.
Example
The following example demonstrates how to create a multi-value report parameter and specify a list of predefined values loaded for the report’s data source.
using System;
using System.IO;
using System.Windows.Forms;
using DevExpress.DataAccess.ConnectionParameters;
using DevExpress.DataAccess.Sql;
using DevExpress.XtraReports.Parameters;
using DevExpress.XtraReports.UI;
// ...
// Create a report instance.
var report = new XtraReport1();
ConfigureDataSource(ref report);
// Create a multi-value parameter and specify its properties.
Parameter parameter1 = new Parameter();
parameter1.Name = "CategoryIDs";
parameter1.Type = typeof(System.Int32);
parameter1.MultiValue = true;
parameter1.Description = "Categories: ";
// Create a DynamicListLookUpSettings instance and set up its properties.
DynamicListLookUpSettings lookupSettings = new DynamicListLookUpSettings();
lookupSettings.DataSource = report.DataSource;
lookupSettings.DataMember = "Categories";
lookupSettings.DisplayMember = "CategoryName";
lookupSettings.ValueMember = "CategoryId";
// Assign the settings to the parameter's LookUpSettings property.
parameter1.LookUpSettings = lookupSettings;
// Set the parameter's Visible and SelectAllValues properties to true to
// make the parameter visible in the Parameters Panel and select all
// values as defaults.
parameter1.Visible = true;
parameter1.SelectAllValues = true;
// Add the parameter to the report's Parameters collection.
report.Parameters.Add(parameter1);
// Use the parameter to filter the report's data.
report.FilterString = "CategoryID in (?CategoryIDs)";
Filter a Report’s Data by a Multi-Value Parameter
To filter a report’s data by a multi-value parameter, use the Is any of operator for this parameter in the report’s filter string:
To filter the report’s data in code, assign a filter condition to the report’s FilterString property:
using DevExpress.XtraReports.UI;
using DevExpress.XtraReports.Parameters;
// ...
// Create a multi-value parameter and specify its properties.
Parameter parameter1 = new Parameter();
parameter1.Name = "CategoryIDs";
parameter1.MultiValue = true;
// ...
// Specify a filter condition for the report's data.
report.FilterString = "CategoryName in (?CategoryIDs)";
The filtered report is displayed after you specify parameter values.
Specify Default Values for a Multi-Value Parameter
Design Time
A multi-value parameter’s default values are selected automatically when you open a report’s Print Preview:
Use one of the following methods to specify default values:
Assign an array of values to the Default Value option (which corresponds to a parameter’s Value property). You must enter values separated with the list delimiter defined for the current culture. This means that values may not always be separated by commas, but by semicolons and other characters depending on the current culture.
Enable the Select all values property to populate the parameter value with all items from the parameter’s value source (static or dynamic).
Tip
Disable a report’s RequestParameters property to avoid the Waiting for parameter values message on the report’s Print Preview and display the report with default parameter values.
Runtime
The following example illustrates how to specify default values for a multi-value report parameter in code:
using System;
using System.Windows.Forms;
using DevExpress.XtraReports.Parameters;
// ...
// Create a report instance.
var report = new XtraReport1();
// Create a multi-value parameter.
var parameter = new Parameter() {
Name = "number",
MultiValue = true,
Type = typeof(System.Int32),
};
// Create a static list of predefined values for the parameter.
var sourceSettings = new StaticListLookUpSettings();
sourceSettings.LookUpValues.Add(new LookUpValue(1, "One"));
sourceSettings.LookUpValues.Add(new LookUpValue(2, "Two"));
sourceSettings.LookUpValues.Add(new LookUpValue(3, "Three"));
parameter.ValueSourceSettings = sourceSettings;
// Specify the parameter's default values.
parameter.Value = new int[] { 1, 3 };
// Add the parameter to the report's Parameters collection.
report.Parameters.Add(parameter);
Note
Ensure that the type of default values match the parameter type when you specify these values for the parameter.
Create an Optional Multi-Value Parameter
Optional parameters allow you to filter report data only if parameter values are specified. Otherwise, if parameter values are not set, the parameter is ignored.
Do the following to make a multi-value parameter optional.
Create a multi-value report parameter and specify its Allow null value, Default Value, and Select all values options as shown below:
Option Value Allow null value true Default Value Not specified Select all values false Disable the report’s RequestParameters property.
Assign the following filter condition to the report’s filter string:
?category Is Null or [Category ID] In (?category)
Tip
You can also use the filter string shown above to filter report data at the data source level. Refer to this help article for more information: Use Query Parameters.