Skip to main content

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.

multi-value-parameters-preview

Tip

Refer to this help article for information on how to use multi-value parameters in an SQL query: Specify 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:

  1. Create a report parameter and enable the Allow multiple values option (which corresponds to the parameter’s MultiValue property).

    Enable the Allow multiple values option

  2. 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

  1. Create a StaticListLookUpSettings or DynamicListLookUpSettings class instance and configure it with a set of predefined parameter values.
  2. Assign the instance to the parameter’s ValueSourceSettings property.
  3. 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

View Example: Create a Multi-Value Report Parameter

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.Windows.Forms;
using DevExpress.XtraReports.Parameters;
// ...
// 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:

parameters-multi-value-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.

parameters-multi-value-filter-report

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:

Specify default values for a multi-value parameter

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).

    Specify default values for a multi-value parameter

  • Enable the Select all values property to populate the parameter value with all items from the parameter’s value source (static or dynamic).

    Select all values as defaults for a multi-value parameter

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.

Create an optional multi-value parameter

Do the following to make a multi-value parameter optional.

  1. Create a multi-value report parameter and specify its Allow null value, Default Value, and Select all values options as shown below:

    parameters-multi-value-optional-settings

    Option Value
    Allow null value true
    Default Value Not specified
    Select all values false
  2. Disable the report’s RequestParameters property.

    report-requestparameters-disable

  3. Assign the following filter condition to the report’s filter string:

    ?category Is Null or [Category ID] In (?category)
    

    parameters-multi-value-empty-value

    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: Specify Query Parameters.