Invoke the Built-in Print Preview Form

Sep 26, 2024
6 minutes to read

Note

An active license for the DevExpress Reporting Subscription is required to use the API in this tutorial.

This topic describes how to display a report in the Print Preview form that ships with DevExpress Reporting for WinForms.

ReportPrintTool Methods

Create the ReportPrintTool class instance and use any of the methods below to invoke a Print Preview form and view a report in a WinForms application.

Note

If your WinForms application targets .NET, add the DevExpress.Win.Reporting NuGet package to this application to use the ReportPrintTool class.

The ShowRibbonPreview and ShowRibbonPreviewDialog methods show a form with a ribbon toolbar.
The ShowPreview and ShowPreviewDialog methods invoke a form with a standard toolbar.

You can specify the default or custom look and feel settings as the method parameter.

Preview Light-Weight Reports

Pass the report instance to the ReportPrintTool constructor as a parameter. Use one of the ShowPreview methods to invoke the Print Preview form.

The following code calls different ReportPrintTool methods to preview a report:

C#
VB.NET

csharp

using DevExpress.XtraReports.UI;
using DevExpress.LookAndFeel;
// ...
ReportPrintTool printTool = new ReportPrintTool(new XtraReport1());

// Invoke the Ribbon Print Preview form  
// and load the report document into it. 
printTool.ShowRibbonPreview();

// Invoke the Ribbon Print Preview form modally 
// with the specified look and feel settings. 
printTool.ShowRibbonPreviewDialog(UserLookAndFeel.Default);

// Invoke the Print Preview form  
// and load the report document into it. 
printTool.ShowPreview();

// Invoke the Print Preview form modally 
// with the specified look and feel settings. 
printTool.ShowPreviewDialog(UserLookAndFeel.Default);

Imports DevExpress.XtraReports.UI
Imports DevExpress.LookAndFeel
' ...
Dim printTool As New ReportPrintTool(New XtraReport1())

' Invoke the Ribbon Print Preview form  
' and load the report document into it. 
printTool.ShowRibbonPreview()

' Invoke the Ribbon Print Preview form modally 
' with the specified look and feel settings. 
printTool.ShowRibbonPreviewDialog(UserLookAndFeel.Default)

' Invoke the Print Preview form  
' and load the report document into it. 
printTool.ShowPreview()

' Invoke the Print Preview form modally 
' with the specified look and feel settings. 
printTool.ShowPreviewDialog(UserLookAndFeel.Default)

The viewer automatically starts the document creation process and displays document pages as soon as they are ready.

Preview Large Reports

Use the CachedReportSource component to preview a large report that contains over 10,000 pages. The CachedReportSource component stores generated pages in the file system, database, or compressed memory streams. The dedicated storage allows you to overcome memory allocation limitations and avoid the OutOfMemory exception. The size of a document is limited only by the available storage space. A substantial increase in the number of pages does not lead to a significant increase in memory consumption.

The CachedReportSource may decrease overall performance because of the time required to store a page and retrieve it from the storage. You should test your application and decide whether it can benefit from the CachedReportSource component.

The following code creates a CachedReportSource instance that uses the MemoryDocumentStorage storage type for the specified report.

C#
VB.NET

csharp

using DevExpress.XtraReports.UI;
using DevExpress.XtraPrinting.Caching;
//...
    var storage = new MemoryDocumentStorage();
    var report = new XtraReport1();
    var cachedReportSource = new CachedReportSource(report, storage);

Imports DevExpress.XtraReports.UI
Imports DevExpress.XtraPrinting.Caching
'...
    Private storage = New MemoryDocumentStorage()
    Private report = New XtraReport1()
    Private cachedReportSource = New CachedReportSource(report, storage)

Instead of memory storage, you can use the FileDocumentStorage or DbDocumentStorage storage type.

Use the ReportPrintTool constructor with the CachedReportSource instance passed as a parameter, and call one of the ShowPreview methods to preview a report:

C#
VB.NET

csharp

using DevExpress.XtraReports.UI;
using DevExpress.LookAndFeel;
using DevExpress.XtraPrinting.Caching;
// ...
var storage = new MemoryDocumentStorage();
var report = new XtraReport1();
var cachedReportSource = new CachedReportSource(report, storage);

ReportPrintTool printTool = new ReportPrintTool(cachedReportSource);

// Invoke the Ribbon Print Preview form  
// and load the report document into it. 
printTool.ShowRibbonPreview();

// Invoke the Ribbon Print Preview form modally 
// with the specified look and feel settings. 
printTool.ShowRibbonPreviewDialog(UserLookAndFeel.Default);

// Invoke the Print Preview form  
// and load the report document into it. 
printTool.ShowPreview();

// Invoke the Print Preview form modally 
// with the specified look and feel settings. 
printTool.ShowPreviewDialog(UserLookAndFeel.Default);

Imports DevExpress.XtraReports.UI
Imports DevExpress.LookAndFeel
Imports DevExpress.XtraPrinting.Caching
' ...
Dim storage = New MemoryDocumentStorage()
Dim report = New XtraReport1()
Dim cachedReportSource1 = New CachedReportSource(report, storage)

Dim printTool As New ReportPrintTool(cachedReportSource)

' Invoke the Ribbon Print Preview form  
' and load the report document into it. 
printTool.ShowRibbonPreview()

' Invoke the Ribbon Print Preview form modally 
' with the specified look and feel settings. 
printTool.ShowRibbonPreviewDialog(UserLookAndFeel.Default)

' Invoke the Print Preview form  
' and load the report document into it. 
printTool.ShowPreview()

' Invoke the Print Preview form modally 
' with the specified look and feel settings. 
printTool.ShowPreviewDialog(UserLookAndFeel.Default)

The viewer automatically starts the document creation process and displays document pages as soon as they are ready. You should not call the CachedReportSource.CreateDocumentAsync method before creating the ReportPrintTool instance.

Display an Empty Print Preview

Create the ReportPrintTool instance for an empty report (a report that does not contain report controls) to invoke an empty Print Preview form without the document:

C#
VB.NET

csharp

using DevExpress.XtraReports.UI;
// ...
ReportPrintTool printTool = new ReportPrintTool(new XtraReport());
printTool.ShowRibbonPreview();

Imports DevExpress.XtraReports.UI
' ...
Dim printTool As New ReportPrintTool(New XtraReport())
printTool.ShowRibbonPreview()

Specify the Print Preview Window Caption and Icon

Use the ReportPrintTool.PreviewRibbonForm.IconOptions and ReportPrintTool.PreviewRibbonForm.Text properties to define a caption and an icon for the Print Preview window:

C#
VB.NET

csharp

using DevExpress.XtraReports.UI;
// ...
XtraReport1 report = new XtraReport1();
ReportPrintTool tool = new ReportPrintTool(report);
tool.PreviewRibbonForm.Text = "My caption";
tool.PreviewRibbonForm.IconOptions.Image = System.Drawing.Image.FromFile("red.png");
tool.PreviewRibbonForm.IconOptions.ShowIcon = true;
tool.ShowRibbonPreview();

Imports DevExpress.XtraReports.UI
' ...
Dim report As New XtraReport1()
Dim tool As New ReportPrintTool(report)
tool.PreviewRibbonForm.Text = "My caption"
tool.PreviewRibbonForm.IconOptions.Image = System.Drawing.Image.FromFile("red.png")
tool.PreviewRibbonForm.IconOptions.ShowIcon = True
tool.ShowRibbonPreview()

Enable DirectX Rendering

The GDI+ library is the default rendering engine for Print Preview elements. If a preview displays a document that contains many pages, this engine might render this document slowly. To boost rendering performance, you can switch to the DirectX rendering engine. The following code sample demonstrates how to do it for the Ribbon Print Preview:

C#
VB.NET

csharp

using DevExpress.XtraReports.UI;
// ...
var printTool = new ReportPrintTool(new XtraReport1());
printTool.PreviewRibbonForm.PrintControl.UseDirectXPaint = DevExpress.Utils.DefaultBoolean.True;
printTool.ShowRibbonPreviewDialog();

Imports DevExpress.XtraReports.UI
' ...
Dim printTool = New ReportPrintTool(New XtraReport1())
printTool.PreviewRibbonForm.PrintControl.UseDirectXPaint = DevExpress.Utils.DefaultBoolean.True
printTool.ShowRibbonPreviewDialog()

You can also set the EnableSmoothScrolling property to True to implement smooth page scrolling in DirectX mode.

C#
VB.NET

csharp

using DevExpress.XtraReports.UI;
// ...
printTool.PreviewRibbonForm.PrintControl.UseDirectXPaint = DevExpress.Utils.DefaultBoolean.True;
printTool.PreviewRibbonForm.PrintControl.EnableSmoothScrolling = DevExpress.Utils.DefaultBoolean.True;

Imports DevExpress.XtraReports.UI
' ...
printTool.PreviewRibbonForm.PrintControl.UseDirectXPaint = DevExpress.Utils.DefaultBoolean.True
printTool.PreviewRibbonForm.PrintControl.EnableSmoothScrolling = DevExpress.Utils.DefaultBoolean.True

Note that smooth scrolling might require more application resources to render the pages.

The following limitations apply to the Print Preview when it uses DirectX rendering:

The Cached Report Source component is not supported.
The XRRichText control is rendered as an image. The default GDI+ library is used to render this control.
String sizes in a document might be greater compared with the case when the GDI+ library is used to render the document.

Per-Monitor V2 Support

The Document Viewer for WinForms supports Per-Monitor V2 DPI awareness mode. Refer to the following topic for more information on this mode and on how to enable it in your WinForms Reporting application: Graphics Performance and High DPI.