Parameters Overview

• Dec 04, 2020
• 4 minutes to read

Report parameters pass data to a report before it is generated in preview.

The Document Viewer displays the Parameters panel that shows editors for the visible report parameters and allows users to specify parameter values.

The Parameters panel displays the specified parameters values. Disable the report’s RequestParameters option to let the Document Viewer create a document with predefined parameter values and avoid the “Waiting for parameter values” message in Preview.

To hide the Parameters panel, disable the Parameter.Visible property for all report parameters.

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.

  

  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.

  

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

  

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

  

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

  C#

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

  VB.NET

  Private Sub OnBeforePrint(ByVal sender As Object, ByVal e As System.Drawing.Printing.PrintEventArgs)
     XRLabel1.Text = "User: " + XtraReport1.Parameters("param1").Value
  End Sub
  

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.

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

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.

  

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

  

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

  • Dynamic values

    Specify a data source, data adapter (for a DataSet only) and data member for the parameter values storage. ValueMember defines a data field that provides values to the parameter. DisplayMember defines a data field that stores values displayed in Print Preview.

    

    The specified data member’s value type should match the specified Parameter.Type.

    Use the LookUpSettings.FilterString property to filter parameter values and implement cascading parameters.

    Specify the LookUpSettings.SortOrder and LookUpSettings.SortMember properties to sort parameter values.

    See How to assign a list of dynamic values to a report parameter for a code sample.

  • Static values

    Switch to this tab to specify a static list of values. Each value should have a description that is displayed in a Print Preview.

    

    See How to assign a list of static values to a report parameter for a code sample.