Quick Guide to Print Preview Customization

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:

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;

    // ...
}

Accessing a Print Control

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

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;

    // ...
}

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.

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;

    // ...
}

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:

    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;
    
        // ...
    }
    

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

    document-preview-windows-forms-select-toolbar

  • 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.

    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;
        printRibbonController.AllowDefaultSvgImages = DevExpress.Utils.DefaultBoolean.False;
    
        // ...
    }
    

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

HowTo_CustomRibbonPreview_0a

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:

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

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;

    // ...
}

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.