Quick Guide to Print Preview Customization

Aug 18, 2023
8 minutes to read

This document describes how to access various Print Preview UI elements.

Tip

See the following documents for a detailed Print Preview GUI overview:

Accessing Print Preview Elements

Accessing a Print Preview Form

The following Print Preview forms are available:

Tip

The Print Preview Form classes are not used independently. Use the see DocumentViewer control to create a custom Print Preview form.

The following example illustrates how to access a Print Preview form in code when using a default Print Preview form:

C#
VB.NET

csharp

using DevExpress.XtraPrinting.Preview;
using DevExpress.XtraReports.UI;
// ...

private void button1_Click(object sender, System.EventArgs e) {
    // Create a Print Tool with an assigned report instance.
    ReportPrintTool printTool = new ReportPrintTool(new XtraReport1());

    // Access the Print Preview forms.
    PrintPreviewFormEx printPreviewForm = printTool.PreviewForm;
    PrintPreviewRibbonFormEx printPreviewRibbonForm = printTool.PreviewRibbonForm;

    // ...
}

Imports DevExpress.XtraPrinting.Preview
Imports DevExpress.XtraReports.UI
' ...

Private Sub button1_Click(sender As Object, e As System.EventArgs)
    ' Create a Print Tool with an assigned report instance. 
    Dim printTool As New ReportPrintTool(New XtraReport1())

    ' Access the Print Preview forms. 
    Dim printPreviewForm As PrintPreviewFormEx = printTool.PreviewForm
    Dim printPreviewRibbonForm As PrintPreviewRibbonFormEx = printTool.PreviewRibbonForm

    ' ... 
End Sub

Accessing a Print Control

Use the PrintPreviewFormExBase.PrintControl property to access the PrintControl displaying a document in a default Print Preview form:

C#
VB.NET

csharp

using DevExpress.XtraPrinting.Control;
using DevExpress.XtraPrinting.Preview;
using DevExpress.XtraReports.UI;
// ...

private void button1_Click(object sender, System.EventArgs e) {
    // Create a Print Tool with an assigned report instance.
    ReportPrintTool printTool = new ReportPrintTool(new XtraReport1());

    // Access the Print Preview forms.
    PrintPreviewFormEx printPreviewForm = printTool.PreviewForm;
    PrintPreviewRibbonFormEx printPreviewRibbonForm = printTool.PreviewRibbonForm;

    // Access different Print Preview forms' Print Control.
    PrintControl printControl1 = printPreviewForm.PrintControl;
    PrintControl printControl2 = printPreviewRibbonForm.PrintControl;

    // ...
}

Imports DevExpress.XtraPrinting.Control
Imports DevExpress.XtraPrinting.Preview
Imports DevExpress.XtraReports.UI
' ...

Private Sub button1_Click(sender As Object, e As System.EventArgs)
    ' Create a Print Tool with an assigned report instance.
    Dim printTool As New ReportPrintTool(New XtraReport1())

    ' Access the Print Preview forms.
    Dim printPreviewForm As PrintPreviewFormEx = printTool.PreviewForm
    Dim printPreviewRibbonForm As PrintPreviewRibbonFormEx = printTool.PreviewRibbonForm

    ' Access different Print Preview forms' Print Control.
    Dim printControl1 As PrintControl = printPreviewForm.PrintControl
    Dim printControl2 As PrintControl = printPreviewRibbonForm.PrintControl

    ' ...
End Sub

You can use the DocumentViewer control that is a PrintControls descendant to create a custom Print Preview form.

Accessing a Dock Manager

Use the PrintControl‘s PrintControl.DockManager property to access the Dock Manager that maintains dock panels in a Print Preview.

C#
VB.NET

csharp

using DevExpress.XtraBars.Docking;
using DevExpress.XtraPrinting.Control;
using DevExpress.XtraPrinting.Preview;
using DevExpress.XtraReports.UI;
// ...

private void button1_Click(object sender, System.EventArgs e) {
    // Create a Print Tool with an assigned report instance.
    ReportPrintTool printTool = new ReportPrintTool(new XtraReport1());

    // Access the Print Preview forms.
    PrintPreviewFormEx printPreviewForm = printTool.PreviewForm;
    PrintPreviewRibbonFormEx printPreviewRibbonForm = printTool.PreviewRibbonForm;

    // Access different Print Preview forms' Print Control.
    PrintControl printControl = printPreviewForm.PrintControl;
    // PrintControl printControl = printPreviewRibbonForm.PrintControl;

    // Access the Dock Manager.
    DockManager dockManager = printControl.DockManager;

    // ...
}

Imports DevExpress.XtraBars.Docking
Imports DevExpress.XtraPrinting.Control
Imports DevExpress.XtraPrinting.Preview
Imports DevExpress.XtraReports.UI
' ...

Private Sub button1_Click(sender As Object, e As System.EventArgs)
    ' Create a Print Tool with an assigned report instance.
    Dim printTool As New ReportPrintTool(New XtraReport1())

    ' Access the Print Preview forms.
    Dim printPreviewForm As PrintPreviewFormEx = printTool.PreviewForm
    Dim printPreviewRibbonForm As PrintPreviewRibbonFormEx = printTool.PreviewRibbonForm

    ' Access different Print Preview forms' Print Control.
    Dim printControl As PrintControl = printPreviewForm.PrintControl
    ' Dim printControl As PrintControl = printPreviewRibbonForm.PrintControl

    ' Access the Dock Manager.
    Dim dockManager As DockManager = printControl.DockManager

    ' ...
End Sub

Accessing Print Preview Toolbars

A Print Preview form can feature any of the following toolbars:

Standard Toolbar
Ribbon Toolbar

A RibbonControl and PrintRibbonController instances are automatically created when adding a DocumentViewer to a form and creating a ribbon toolbar for it.

Tip

You can provide custom functionality to a Print Preview by adding custom BarItem objects to its toolbar and handling their click events. See the following tutorials for detailed instructions:

Accessing a Printing System

A PrintControl‘s PrintControl.PrintingSystem property provides access to a Printing System that is used to generate document pages, print documents, and export them to various formats.

Printing System provides the following main settings:

PrintingSystemBase.Document - provides access to a rendered document.
PrintingSystemBase.Pages - provides access to a document’s collection of pages.
PrintingSystemBase.PageSettings - specifies various print options, such as paper kind, page orientation, page margins and printer name.
PrintingSystemBase.ExportOptions - specifies the options for document export to supported formats.

The following code illustrates how to access a Printing System and some of its main settings:

C#
VB.NET

csharp

using DevExpress.XtraPrinting;
using DevExpress.XtraPrinting.Control;
using DevExpress.XtraPrinting.Preview;
using DevExpress.XtraReports.UI;
// ...

private void button1_Click(object sender, System.EventArgs e) {
    // Create a Print Tool with an assigned report instance.
    ReportPrintTool printTool = new ReportPrintTool(new XtraReport1());

    // Access the Print Preview forms.
    PrintPreviewFormEx printPreviewForm = printTool.PreviewForm;
    PrintPreviewRibbonFormEx printPreviewRibbonForm = printTool.PreviewRibbonForm;

    // Access different Print Preview forms' Print Control.
    PrintControl printControl = printPreviewForm.PrintControl;
    //PrintControl printControl = printPreviewRibbonForm.PrintControl;

    // Access the Printing System and the created document.
    PrintingSystemBase printingSystem = printControl.PrintingSystem;

    // Access supported export format options.
    DocxExportOptions docxExportOptions = printingSystem.ExportOptions.Docx;
    PdfExportOptions pdfExportOptions = printingSystem.ExportOptions.Pdf;

    // Access the page settings.
    XtraPageSettingsBase pageSettings = printingSystem.PageSettings;

    // ...
}

Imports DevExpress.XtraPrinting
Imports DevExpress.XtraPrinting.Control
Imports DevExpress.XtraPrinting.Preview
Imports DevExpress.XtraReports.UI
' ...

Private Sub button1_Click(sender As Object, e As System.EventArgs)
    ' Create a Print Tool with an assigned report instance.
    Dim printTool As New ReportPrintTool(New XtraReport1())

    ' Access the Print Preview forms.
    Dim printPreviewForm As PrintPreviewFormEx = printTool.PreviewForm
    Dim printPreviewRibbonForm As PrintPreviewRibbonFormEx = printTool.PreviewRibbonForm

    ' Access different Print Preview forms' Print Control.
    Dim printControl As PrintControl = printPreviewForm.PrintControl
    ' Dim printControl As PrintControl = printPreviewRibbonForm.PrintControl

    ' Access the Printing System and the created document.
    Dim printingSystem As PrintingSystemBase = printControl.PrintingSystem

    ' Access the options of supported export formats.
    Dim docxExportOptions As DocxExportOptions = printingSystem.ExportOptions.Docx
    Dim pdfExportOptions As PdfExportOptions = printingSystem.ExportOptions.Pdf

    ' Access the page settings.
    Dim pageSettings As XtraPageSettingsBase = printingSystem.PageSettings

    ' ...
End Sub

When publishing a document, the Printing System transforms each report control into a graphical primitive (brick) corresponding to the control’s type. A brick renders a control’s content and defines its size and location on a document’s page.

In most cases, you do not need to access and manipulate individual bricks because you can manipulate elements in a report instead. See Printing-Exporting for more information about the low-level API the printing library uses to create documents.

Tip

Various user actions in a Print Preview correspond to Printing System commands listed in the PrintingSystemCommand enumeration.

See Use Printing System Commands to learn how to execute these commands and maintain their visibility in Print Preview.