XtraReportBase.FilterString Property

Specifies the criteria used to filter data in a report.

Namespace: DevExpress.XtraReports.UI

Assembly: DevExpress.XtraReports.v20.2.dll

NuGet Packages: DevExpress.Reporting.Core, DevExpress.WindowsDesktop.Reporting.Core

Declaration

C#

[DefaultValue("")]
[SRCategory(ReportStringId.CatData)]
public virtual string FilterString { get; set; }

VB.NET

<DefaultValue("")>
<SRCategory(ReportStringId.CatData)>
Public Overridable Property FilterString As String

Property Value

Type	Default	Description
String	String.Empty	A String value, specifying the filter criteria.

Remarks

Use the FilterString property to invoke the FilterString Editor that enables you to specify filter criteria.

At runtime, the FilterString property must be set before calling the XtraReport.CreateDocument method or any other method that calls it internally (e.g., PrintTool.ShowPreview, PrintTool.ShowPreviewDialog, PrintToolBase.Print, PrintTool.PrintDialog and all exporting methods). Setting this property is appropriate in the following event handlers.

• The XtraReportBase.DataSourceDemanded event.
• The XRControl.BeforePrint event of a report.

You can also handle the XRControl.BeforePrint event of a specific report band (e.g., the DetailBand). In this event handler, you can access the current data row using the XtraReportBase.GetCurrentRow and XtraReportBase.GetCurrentColumnValue methods and cancel printing of the band under a specific condition using the e.Cancel property.

Example

This example demonstrates how to create a report with a parameter at runtime.

After a parameter is added to the report, its value can be used in the report’s XtraReportBase.FilterString, or displayed in a XRLabel control.

Then, when the report is being previewed, an end-user can modify the parameter’s value via the Parameters UI, which is enabled using the ReportPrintTool.AutoShowParametersPanel property.

C#

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

private void simpleButton1_Click(object sender, EventArgs e) {
    // Create a report instance.
    XtraReport1 report = new XtraReport1();

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

    // Specify other parameter properties.
    param1.Type = typeof(System.Int32);
    param1.Value = 1;
    param1.Description = "Category: ";
    param1.Visible = true;

    // Add the parameter to the report.
    report.Parameters.Add(param1);

    // Specify the report's filter string.
    report.FilterString = "[CategoryID] = ?CatID";

    // Force the report creation without previously 
    // requesting the parameter value from end-users.
    report.RequestParameters = false;

    // Show the parameter's value on a Report Header band.
    XRLabel label = new XRLabel();
    label.DataBindings.Add(new XRBinding(param1, "Text", "Category: {0}"));
    ReportHeaderBand reportHeader = new ReportHeaderBand();
    reportHeader.Controls.Add(label);
    report.Bands.Add(reportHeader);

    // Assign the report to a ReportPrintTool,
    // to hide the Parameters panel,
    // and show the report's print preview.
    ReportPrintTool pt = new ReportPrintTool(report);
    pt.AutoShowParametersPanel = true;
    pt.ShowPreviewDialog();
}

VB.NET

Imports System
Imports System.Windows.Forms
Imports DevExpress.XtraReports.UI
Imports DevExpress.XtraReports.Parameters
' ...

Private Sub simpleButton1_Click(ByVal sender As Object, _
ByVal e As EventArgs) Handles simpleButton1.Click
    ' Create a report instance.
    Dim report As New XtraReport1()

    ' Create a parameter and specify its name.
    Dim param1 As New Parameter()
    param1.Name = "CatID"

    ' Specify other parameter properties.
    param1.Type = GetType(System.Int32)
    param1.Value = 1
    param1.Description = "Category: "
    param1.Visible = True

    ' Add the parameter to the report.
    report.Parameters.Add(param1)

    ' Specify the report's filter string.
    report.FilterString = "[CategoryID] = ?CatID"

    ' Force the report creation without previously 
    ' requesting the parameter value from end-users.
    report.RequestParameters = False

    ' Show the parameter's value on a Report Header band.
    Dim label As New XRLabel()
    label.DataBindings.Add(New XRBinding(param1, "Text", "Category: {0}"))
    Dim reportHeader As New ReportHeaderBand()
    reportHeader.Controls.Add(label)
    report.Bands.Add(reportHeader)

    ' Assign the report to a ReportPrintTool,
    ' to hide the Parameters panel,
    ' and show the report's print preview.
    Dim pt As New ReportPrintTool(report)
    pt.AutoShowParametersPanel = True
    pt.ShowPreviewDialog()
End Sub

Related GitHub Examples

The following code snippets (auto-collected from DevExpress Examples) contain references to the FilterString property.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

C#

Reporting_how-to-create-a-side-by-side-report-e920/CS/MasterReport.cs#L11

private void xrSubreport1_BeforePrint(object sender, System.Drawing.Printing.PrintEventArgs e) {
    ((XRSubreport)sender).ReportSource.FilterString = "[EmployeeID] = 1";
}

Reporting_how-to-assign-a-list-of-dynamic-values-to-a-report-parameter-e4081/CS/DynamicParameterValues/XtraReport1.cs#L36

this.Parameters.Add(parameter1);
this.FilterString = "[ProductID] = ?parameterProduct";

Reporting_how-to-assign-a-list-of-static-values-to-a-report-parameter-e4082/CS/StaticParameterValues/XtraReport1.cs#L36

this.Parameters.Add(parameter1);
this.FilterString = "[ProductID] = ?parameterProduct";

Reporting_how-to-implement-a-master-detail-report-by-adjusting-the-filterstring-property-at-e543/CS/MasterDetailFilterString/XtraReport1.cs#L15

    int orderId = Convert.ToInt32(this.GetCurrentColumnValue("OrderID"));
    ((DetailReportBand)sender).FilterString = string.Format("[OrderID] = {0}", orderId);
}

Reporting_how-to-show-the-checkedcomboboxedit-editor-in-the-parameters-dialog-e1404/CS/WindowsApplication1/XtraReport1.cs#L29

private void XtraReport1_ParametersRequestSubmit(object sender,DevExpress.XtraReports.Parameters.ParametersRequestEventArgs e) {
    this.FilterString = @"[CategoryID] In ("+e.ParametersInformation[0].Parameter.Value +")";
}

VB.NET

Reporting_how-to-create-a-side-by-side-report-e920/VB/MasterReport.vb#L14

Private Sub xrSubreport1_BeforePrint(ByVal sender As Object, ByVal e As System.Drawing.Printing.PrintEventArgs) Handles xrSubreport1.BeforePrint
    CType(sender, XRSubreport).ReportSource.FilterString = "[EmployeeID] = 1"
End Sub

Reporting_how-to-implement-a-master-detail-report-by-adjusting-the-filterstring-property-at-e543/VB/MasterDetailFilterString/XtraReport1.vb#L17

    Dim orderId As Integer = Convert.ToInt32(Me.GetCurrentColumnValue("OrderID"))
    DirectCast(sender, DetailReportBand).FilterString = String.Format("[OrderID] = {0}", orderId)
End Sub

Reporting_how-to-show-the-checkedcomboboxedit-editor-in-the-parameters-dialog-e1404/VB/WindowsApplication1/XtraReport1.vb#L27

Private Sub XtraReport1_ParametersRequestSubmit(ByVal sender As Object, ByVal e As DevExpress.XtraReports.Parameters.ParametersRequestEventArgs) Handles MyBase.ParametersRequestSubmit
    Me.FilterString = "[CategoryID] In (" & e.ParametersInformation(0).Parameter.Value.ToString() & ")"
End Sub

Reporting_how-to-create-a-master-detail-report-type-using-two-report-layouts-at-runtime-e1063/VB/WindowsFormsApplication1/Form1.vb#L31

Private Sub Form1_BeforePrint(ByVal sender As Object, ByVal e As System.Drawing.Printing.PrintEventArgs)
    CType(sender, XRSubreport).ReportSource.FilterString = "[CategoryID] = " & Convert.ToInt32((CType(sender, XRSubreport)).Report.GetCurrentColumnValue("CategoryID")).ToString()
End Sub

reporting-winforms-export-xls-diff-sheets/VB/WindowsApplication1/Form1.vb#L25

Dim report As XtraReport1 = New XtraReport1()
report.FilterString = ""
report.CreateDocument(False)

Implements

DevExpress.Data.IFilterStringContainer.FilterString