XtraReport.CreateDocument() Method

Creates a document from the XtraReport object, so it can be displayed or printed.

Namespace: DevExpress.XtraReports.UI

Assembly: DevExpress.XtraReports.v20.2.dll

Declaration

public void CreateDocument()
Public Sub CreateDocument

Remarks

Calling the CreateDocument method creates a report document that is ready to preview, print and export.

The newly created document can then be accessed via the PrintingSystemBase.Document property of a report's XtraReport.PrintingSystem, and the page collection is available via the XtraReport.Pages property. To see a code example, refer to the following help topic: Merging Reports.

NOTE

Once the document creation process has started, it will run until the document is complete. It cannot be interrupted or canceled during this process. To create a report document asynchronously in a separate task, use the CreateDocumentAsync(CancellationToken) method instead.

To be able to access document pages progressively as they are created, as well as interrupt or cancel the document creation, call the CreateDocument method overload with the buildForInstantPreview parameter set to true.

The CreateDocument method is called internally from the following methods (i.e., you do not need to call CreateDocument before calling one of these methods).

Calling the CreateDocument method is not required after assigning a report to the ASPxDocumentViewer or ASPxWebDocumentViewer control.

An explicit call to the CreateDocument method is required only to refresh the document (and after making changes to the report), prior to showing its preview, or before printing and/or exporting.

If a report contains parameters and the XtraReport.RequestParameters property is set to true, calling the CreateDocument method will not invoke the Parameters form that enables end-users to enter parameter values, unless DevExpress.XtraPrinting.v20.2.dll is added to the project's reference list and the following code is executed.

using DevExpress.XtraReports.UI;
// ...

private void button1_Click(object sender, EventArgs e) {
    XtraReport1 report = new XtraReport1();
    ReportPrintTool tool = new ReportPrintTool(report);
    report.CreateDocument();
}

If you call the CreateDocument method after this code assigns a ReportPrintTool to the report, it invokes a dialog that requests report parameter values.

ReportParameters3

NOTE

An attempt to call the CreateDocument method for a report that does not contain a DetailBand raises an exception (specifically, when creating a report in code). Add this band to the report even if you do not need to display information within it.

Examples

This example illustrates the use of the XtraReport.CreateDocument method. The report's Print Preview is shown by using ReportPrintTool.

In this example, an XRLabel object contained in the XtraReport1 class has its Modifiers property set to public.

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

private void button1_Click(object sender, EventArgs e) {
    // Create a report and assign to a Print Tool.
    XtraReport1 report = new XtraReport1();
    ReportPrintTool printTool = new ReportPrintTool(report);

    // Show the report's preview for the first time.
    printTool.ShowPreviewDialog();

    // Change the report's contents.
    ((XtraReport1)printTool.Report).xrLabel1.BackColor = Color.Blue;

    // Create the report's document.
    printTool.Report.CreateDocument();

    // Show the report's preview for the second time.
    printTool.ShowPreviewDialog();
}

Implements

See Also