Printing and Export

• Jan 23, 2019
• 7 minutes to read

The contents of a LayoutControl can be previewed, printed and exported using the DevExpress XtraPrinting Library. This topic demonstrates how to customize the printed version of the Layout Control, lists the ways in which the Layout Control can be printed and exported, and describes the default and old printing modes. The following sections are available within this topic.

• Printing/Export Basics
• Default Print and Export Mode
• Old Printing and Export (WYSIWYG)
• Printing/Export Options
• Printing/Export Appearance

Printing/Export Basics

Although the Layout Control provides direct methods to preview, print and export its contents (see below), it delegates the printing functionality to the XtraPrinting Library. Thus, the printing/export functionality is not available if this library cannot be found. The printing library availability can be checked using the LayoutControl.IsPrintingAvailable property.

To preview and print the Layout Control’s contents, use the following methods.

Member	Description
LayoutControl.ShowPrintPreview	Opens the Print Preview window for the LayoutControl with a Bars UI.
LayoutControl.ShowRibbonPrintPreview	Displays the Print Preview window with a Ribbon UI.
LayoutControl.Print	Prints the LayoutControl.

The LayoutControl.ShowPrintPreview and LayoutControl.ShowRibbonPrintPreview methods open the print Preview window displaying the Layout Control as it will be printed. Using the Preview window, an end-user is able to customize the page settings (the page format, size, orientation, etc.), change a background color, export the Layout Control to various formats (PDF, HTML, etc.) and so on.

The LayoutControl.Print method does not show the Preview window, it prints the Layout Control directly using the default page settings.

The Layout Control provides a set of methods that allow exports to various formats. These methods export data using routines implemented in the XtraPrinting Library.

Member	Description
LayoutControl.ExportToHtml	Exports the control’s data to the specified stream in HTML format using the specified options.
LayoutControl.ExportToMht	Exports the control’s data to the specified stream in MHT format using the specified options.
LayoutControl.ExportToPdf	Exports the controls displayed within the LayoutControl to a stream in PDF format.
LayoutControl.ExportToRtf	Exports the controls displayed within the LayoutControl to a stream in RTF format.
LayoutControl.ExportToText	Exports the control’s data to the specified stream in Text format using the specified options.
LayoutControl.ExportToXls	Exports the control’s data to the specified stream in XLS format using the specified options.
LayoutControl.ExportToXlsx	Exports data to the specified stream in XLSX (MS Excel 2007) format using the specified options.

Note

Custom painting, alpha blending and color gradient features are not supported when the Layout Control is printed/exported.

Example

The following example demonstrates how to print a LayoutControl and show its Print Preivew. The LayoutControl.Print and LayoutControl.ShowPrintPreview methods are called respectively.

C#

using DevExpress.XtraLayout;
// ...

private void ShowLayoutControlPreview(LayoutControl layout) {
    // Check whether the LayoutControl can be previewed.
    if (!layout.IsPrintingAvailable) {
        MessageBox.Show("The 'DevExpress.XtraPrinting' library is not found", "Error");
        return;
    }

    // Open the Preview window.
    layout.ShowPrintPreview();
}

private void PrintLayoutControl(LayoutControl layout) {
    // Check whether the LayoutControl can be printed.
    if (!layout.IsPrintingAvailable) {
        MessageBox.Show("The 'DevExpress.XtraPrinting' library is not found", "Error");
        return;
    }

    // Print.
    layout.Print();
}

VB.NET

Imports DevExpress.XtraLayout
' ...

Sub ShowLayoutControlPreview(ByVal layout As LayoutControl)
   ' Check whether the LayoutControl can be previewed.
   If Not layout.IsPrintingAvailable Then
      MessageBox.Show("The 'DevExpress.XtraPrinting' library is not found", "Error")
      Return
   End If

   ' Opens the Preview window.
   layout.ShowPrintPreview()
End Sub

Sub PrintLayoutControl(ByVal layout As LayoutControl
   ' Check whether the LayoutControl can be printed.
   If Not layout.IsPrintingAvailable Then
      MessageBox.Show("The 'DevExpress.XtraPrinting' library is not found", "Error")
      Return
   End If

   ' Print.
   layout.Print()
End Sub

Default Print and Export Mode

By default, the Layout Control follows the “Flow layout” approach when arranging items in the print/export document, not the WYSIWYG approach.

According to the “Flow layout” principle, layout items are arranged back-to-back, filling the page area in the optimal way. The flow of items wraps at the page’s right edge. So, if there is insufficient space in a row to accommodate an item, this item is carried over to the following row.

Items in the print/export document can occupy less space compared to their original size. For instance, a layout item with a text editor is shrunk to display the editor’s text in its entirety.

Specific compound controls (e.g., GridControl, ChartControl, SpreadsheetControl, TreeList, etc.) implement the IPrintable interface, which maintains high-quality printing/export using the DevExpress XtraPrinting Library.

When you print or export a Layout Control that contains any of these controls, the Layout Control invokes high-quality printing/export for these controls using the DevExpress Printing Library (in the old print/export mode, these controls are printed/exported as images). The IPrintable controls are printed starting from the left edge of a page, occupying the entire page width. Even if a control’s contents are partially visible on the form and vertical scrollbars are enabled, the height of the control is increased in the print/export document to print the control’s contents in their entirety.

Multiple print options provided by IPrintable controls are taken into account when the Layout Control is printed/exported.

The image below shows a print preview for a Layout Control containing several text editors and a Grid Control.

Old Printing and Export (WYSIWYG)

To enable the legacy print and export mode, which follows the WYSIWYG approach, set the OptionsPrintControl.OldPrinting property to true.

In this mode, the Layout Control is printed/exported as is, keeping the arrangement of items. By default, the Layout Control is scaled to the page width. This functionality can be disabled with the OptionsPrintControl.AllowFitToPage property.

The following image demonstrates a print preview of a Layout Control containing several text editors and a Data Grid.

• Controls that are not derived from the BaseEdit class are printed as images. Their printed versions are graphical copies of display versions. For instance, if a Grid Control displays scrollbars on the form, the scrollbars will be included in the print/export output as well.
• Text editors that are derived from the BaseEdit class are represented by their values. No border is painted when printed. Values of editors are printed as text.
• Graphical editors that are derived from the BaseEdit class are printed as images.

Printing/Export Options

The Layout Control and layout items provide a set of options that specify how the Layout Control’s contents are printed/exported. These options are available using the LayoutControl.OptionsPrint, LayoutControlItem.OptionsPrint and LayoutGroup.OptionsPrint properties. You can specify the appearance of item and group captions, the distance between a layout item’s text and its control, etc.

The following image demonstrates print options of the Layout Control.

Note

The LayoutControlItem.OptionsPrint, LayoutGroup.OptionsPrint and OptionsPrintControl.TextToControlDistance properties are not supported in old printing mode.

Printing/Export Appearance

By default, a printed Layout Control uses the same appearance options as when it is displayed on the screen.

However, in the default print/export mode, you can customize the appearances that are only used when the control is printed and exported, using dedicated options. These options are: OptionsPrintBase.AppearanceItemCaption, OptionsPrintGroup.AppearanceGroupCaption, OptionsPrintControl.AppearanceItemCaption, OptionsPrintControl.AppearanceGroupCaption.

The Layout Control supports hierarchical appearances. For instance, you can customize default print appearances for all items and groups in a centralized way, using the Layout Control’s OptionsPrintControl.AppearanceItemCaption, OptionsPrintControl.AppearanceGroupCaption properties. You can customize print appearances for all items in a group, using the group’s OptionsPrintBase.AppearanceItemCaption.

Print appearances set for a specific group or item will override the parent print appearances.

Note

Print appearance settings are not supported if the OptionsPrintControl.OldPrinting property is set to true.