Invoke the Built-in Print Preview Form
- 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 6+, 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:
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);
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.
using DevExpress.XtraReports.UI;
using DevExpress.XtraPrinting.Caching;
//...
var storage = new MemoryDocumentStorage();
var report = new XtraReport1();
var 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:
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);
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:
using DevExpress.XtraReports.UI;
// ...
ReportPrintTool printTool = 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:
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();
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:
using DevExpress.XtraReports.UI;
// ...
var 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.
using 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.