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:

• Print Preview with a Standard Toolbar
• Print Preview with a Ribbon Toolbar

Accessing Print Preview Elements

Accessing a Print Preview Form

The following Print Preview forms are available:

• PrintPreviewFormEx

  Corresponds to the standard Print Preview form.

  Use the ReportPrintTool‘s PrintTool.PreviewForm property to access this form’s settings.

• PrintPreviewRibbonFormEx

  Corresponds to the ribbon-based Print Preview form.

  Use the ReportPrintTool‘s PrintTool.PreviewRibbonForm property to access this form’s settings.

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#

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;

    // ...
}

VB.NET

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#

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;

    // ...
}

VB.NET

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#

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;

    // ...
}

VB.NET

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

  The PrintBarManager provides functionality to the standard toolbar. You can access it using the PrintPreviewFormEx.PrintBarManager property:

  C#

  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 standard Print Preview form.
      PrintPreviewFormEx printPreviewForm = printTool.PreviewForm;
  
      // Access the standard Print Preview form's Print Bar Manager.
      PrintBarManager printBarManager = printPreviewForm.PrintBarManager;
  
      // ...
  }
  

  VB.NET

  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 standard Print Preview form.
      Dim printPreviewForm As PrintPreviewFormEx = printTool.PreviewForm
  
      ' Access the Print Bar Manager of a standard Print Preview form.
      Dim printBarManager As PrintBarManager = printPreviewForm.PrintBarManager
  
      ' ...
  End Sub
  

  A PrintBarManager instance is automatically created when adding a DocumentViewer to a form and creating a standard toolbar for it.

  

• Ribbon Toolbar

  The RibbonControl provides functionality to the ribbon toolbar. You can access it using a ribbon form’s PrintPreviewRibbonFormEx.RibbonControl property.

  The PrintRibbonController maintains ribbon elements’ image settings. You can access it using the PrintPreviewRibbonFormEx.PrintRibbonController property.

  C#

  using DevExpress.XtraBars.Ribbon;
  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's ribbon form.
      PrintPreviewRibbonFormEx printPreviewRibbonForm = printTool.PreviewRibbonForm;
  
      // Access the Ribbon Control of the Print Preview's ribbon form.
      RibbonControl ribbonControl = printPreviewRibbonForm.RibbonControl;
  
      // Access the Print Ribbon Controller of the Print Preview's ribbon form.
      PrintRibbonController printRibbonController = printPreviewRibbonForm.PrintRibbonController;
  
      // ...
  }
  

  VB.NET

  Imports DevExpress.XtraBars.Ribbon
  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's ribbon form.
      Dim printPreviewRibbonForm As PrintPreviewRibbonFormEx = printTool.PreviewRibbonForm
  
      ' Access the Ribbon Control of the Print Preview's ribbon form.
      Dim ribbonControl As RibbonControl = printPreviewRibbonForm.RibbonControl
  
      ' Access the Print Ribbon Controller of the Print Preview's ribbon form.
      Dim printRibbonController As PrintRibbonController = printPreviewRibbonForm.PrintRibbonController
  
      ' ...
  End Sub
  

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:

• Add Items to a Print Preview’s Standard Toolbar
• Add Items to a Print Preview’s Ribbon Toolbar

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#

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;

    // ...
}

VB.NET

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.