Multi-Value Report Parameters

  • 5 minutes to read

This document describes how to create a multi-value parameter and filter report data by the specified parameter values.

multi-value-parameters-preview

TIP

See Specify Query Parameters for information on how to use multi-value parameters in an SQL query.

Create a Multi-Value Parameter

Follow these steps to create a multi-value parameter at design time:

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

    multi-value-parameters-create-parameter

  2. Specify a list of predefined values for the parameter. See the following topics for more information:

To create a multi-value report parameter in code, follow the steps below.

  1. Create a StaticListLookUpSettings or DynamicListLookUpSettings class instance and configure it with a set of predefined parameter values.
  2. Assign the newly created instance to the parameter's ValueSourceSettings property.
  3. Enable the parameter's Parameter.MultiValue property. It allows the parameter to have more than one value.
using System;
using System.Windows.Forms;
using DevExpress.XtraReports.Parameters;
// ...

// Create a parameter and specify its name.
Parameter parameter1 = new Parameter();
parameter1.Name = "CategoryIDs";

// Specify other parameter properties.
parameter1.Type = typeof(System.Int32);
parameter1.MultiValue = true;
parameter1.Description = "Categories: ";

DynamicListLookUpSettings lookupSettings = new DynamicListLookUpSettings();
lookupSettings.DataSource = report.DataSource;
lookupSettings.DataMember = "Categories";
lookupSettings.DisplayMember = "CategoryName";
lookupSettings.ValueMember = "CategoryId";

parameter1.LookUpSettings = lookupSettings;
parameter1.Visible = true;
parameter1.SelectAllValues = true;

report.FilterString = "CategoryName in (?CategoryIDs)";

Filter a Report by a Multi-Value Parameter

Use the Is any of operator in the report’s filter string:

parameters-multi-value-filter-string

To filter report data in code, specify the report’s FilterString property.

using DevExpress.XtraReports.UI;
using DevExpress.XtraReports.Parameters;

// ...
// Create a parameter and specify its name. 
Parameter parameter1 = new Parameter(); 
parameter1.Name = "CategoryIDs"; 
Parameter1.Visible = true; 

//... 
// Filter report data  
report.FilterString = "CategoryName in (?CategoryIDs)";  

The filtered report is displayed after a user specifies parameter values.

parameters-multi-value-filter-report

Pre-Select Parameter Values

Use one of the following methods to pre-select multiple parameter values when a report is first rendered.

parameters-multi-value-preselect-values

  • Assign an array of values to the Default Value (corresponds to Parameter.Value) property.

    parameters-multi-value-preselect-values-specify

  • Set the Expression property to an expression that evaluates to an array of values. You can use data source fields and other parameters in expressions.

    parameters-multi-value-preselect-values-expression

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

    multi-value-parameters-select-all

TIP

Disable the report's RequestParameters property to avoid the Waiting for parameter values message in Preview and display the report with pre-selected parameter values.

The following example illustrates how to pre-select values for a multi-value report parameter in code:

using System;
using System.Windows.Forms;
using DevExpress.XtraReports.Parameters;
// ...

// Create a report instance.
XtraReport report = new XtraReport();

// Add a parameter to the report.
report.Parameters.Add(
    new Parameter() {
        Name = "category",
        Type = typeof(System.Int32),
        MultiValue = true,
        ValueSourceSettings = new DynamicListLookUpSettings() {
            DataSource = report.DataSource,
            DataMember = "Categories",
            ValueMember = "CategoryID",
            DisplayMember = "CategoryName",
            SortMember = "CategoryName",
            SortOrder = DevExpress.Data.ColumnSortOrder.Ascending
        }
    });

// Specify parameter values.
report.Parameters["category"].Value = new int[] { 1, 2, 3 };
NOTE

Parameter values should match the parameter's type.

Optional Multi-Value Parameter

You can leave the parameter unspecified and display all report data. A user optionally chooses parameter values to filter the report.

parameters-multi-value-optional

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

Configure the parameter as follows:

parameters-multi-value-optional-settings

Property Value
Allow null value true
Default Value Not specified
Expression Not specified
Select all values false

Disable the report's RequestParameters property.

report-requestparameters-disable

Use the following report 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. See the Specify Query Parameters topic for more information.