The requested page is not available for the requested platform. You are viewing the content for Default platform.

Parameters Overview

  • 4 min to read

This document describes how to create report parameters at design time and use them in reports.

Tip

Watch this tutorial on the DevExpress YouTube Channel: DevExpress Reporting Parameters

Use Parameters

Report parameters pass data to a report before it has been generated in Print Preview. You can let users specify parameter values, or you can assign values in code.

Use report parameters in the following cases:

  • Filter

    Parameters can provide values to a report's XtraReportBase.FilterString to filter report data.

    parameters-filter-string-multi-value

    You can link the report parameter to query parameters used in the SQL string's SELECT statement to filter data at the data source level.

  • Calculated Fields

    You can include parameters into a calculated field's expression. Use a question mark (?) in front of a parameter's name.

    parameters-expression-calculated-field

  • Data Binding

    You can bind a report control to a parameter and display its value in a report. To create a new label bound to a parameter, drag the parameter from the Field List and drop it onto a band.

    ReportParameters4a

    You can refer to a parameter in mail merge. Add a question mark in front of the parameter's name.

    MailMerge_Parameters

  • Dynamic Report Layout

    Use parameters to specify which table columns are displayed in a report.

    See the How to use XtraReport's multi-value parameter as a column chooser online code sample for details.

  • Scripts

    You can access a specific parameter in the XtraReport.Parameters collection by its name when you process report data in scripts.

    private void OnBeforePrint(object sender, System.Drawing.Printing.PrintEventArgs e) {
        xrLabel1.Text = "User: " + XtraReport1.Parameters["param1"].Value;
    }
    

Add Parameters

Switch to the Field List, right-click the Parameters node and click Add Parameter in the context menu to create a report parameter at design time.

Shared_FieldList_AddParameter

This invokes the Add New Parameter dialog where you can configure the created parameter.

parameters-add-new-dialog

The dialog provides the following options.

  • Parameter.Name
    Specifies the unique name by which you can refer to the parameter.
  • Parameter.Description
    Specifies the text that appears in Print Preview alongside with the value editor.
  • Parameter.Type
    Specifies the parameter's value type. A value editor for the specified type is displayed in a Print Preview.

    You can set this property to any standard data type that matches the value's expected data type. See Create Custom Report Parameters for information on how to use other parameter types.

  • Default value
    Specifies the parameter's value. When users change a parameter's value in Print Preview, they can press Reset to return to the default value.

    reset

  • Expression
    Specifies an expression that defines the parameter's value based on specific conditions. Click the Expression property's ellipsis button and construct an expression in the invoked Expression Editor.

    reset

  • Show in the parameters panel (corresponds to the Parameter.Visible property)
    Enable this option to request the parameter value in Print Preview. Otherwise, the report assumes the default parameter value.

  • Allow multiple values (corresponds to the Parameter.MultiValue property)
    Enable this option to allow a parameter to accept a collection of values.
  • Allow null value (corresponds to the Parameter.AllowNull property)
    Enable this option if the parameter's value can be unspecified.
  • Range Value
    Enable this option if the parameter should specify a range with a start value and an end value. This option applies to Date-type parameters. See Date Range Parameters for information on how to configure a date range parameter.
  • Supports the collection of standard values
    Applies if the parameter is visible (its value is requested in Print Preview). An user can choose a value from a predefined list. You can populate this list with static values, or specify a data source from where the values are obtained.