How to: Customize Export Options of the Printing System

• Oct 23, 2023
• 3 minutes to read

In a Windows Forms XAF application, end-users have an ability to export View print previews to various formats. Before exporting, an Export Options dialog is invoked. The format-specific options can be changed using this dialog, for example, the HTML title or XLS sheet name.

Note

To learn how to specify export options for reports, refer to the How to: Customize the Report Export Options topic.

• The PrintingController, supplied with the System module, exposes the PrintingController.PrintingSettingsLoaded event. You can handle this event to access the PrintingSystem object and modify default export options. To do this, implement the following View Controller:

  C#

  using DevExpress.XtraPrinting;
  using DevExpress.ExpressApp.Win.SystemModule;
  // ...
  public class ConfigurePrintingSystemViewController : ViewController {
      private PrintingController printingService;
      protected override void OnActivated() {
          base.OnActivated();
          printingService = Frame.GetController<PrintingController>();
          if (printingService != null)
              printingService.PrintingSettingsLoaded += printingService_PrintingSettingsLoaded;
      }
      private void printingService_PrintingSettingsLoaded(
          object sender, PrintableComponentLinkEventArgs e) {
          ConfigurePrintingSystem(e.PrintableComponentLink.PrintingSystem);
      }
      private void ConfigurePrintingSystem(PrintingSystemBase printingSystem) {
          SetHtmlOptions(printingSystem.ExportOptions.Html);
          SetPdfOptions(printingSystem.ExportOptions.Pdf);
          SetXlsOptions(printingSystem.ExportOptions.Xls);
      }
      private static void SetXlsOptions(XlsExportOptions xlsExportOptions) {
          // XLS-specific options:
          xlsExportOptions.SheetName = "CustomXlsSheetTitle";
          xlsExportOptions.ShowGridLines = true;
      }
      private static void SetPdfOptions(PdfExportOptions pdfExportOptions) {
          // PDF-specific options:
          pdfExportOptions.DocumentOptions.Title = "CustomPdfTitle";
          pdfExportOptions.ImageQuality = PdfJpegImageQuality.Medium;
      }
      private static void SetHtmlOptions(HtmlExportOptions htmlExportOptions) {
          // HTML-specific options:
          htmlExportOptions.Title = "CustomHtmlTitle";
          htmlExportOptions.ExportMode = HtmlExportMode.SingleFilePageByPage;
          htmlExportOptions.PageBorderColor = System.Drawing.Color.Gray;
          htmlExportOptions.EmbedImagesInHTML = true;
      }
      private static void SetGeneralOptions(PrintPreviewOptions printPreviewOptions) {
          // General options:
          printPreviewOptions.DefaultFileName = "CustomFileName";
      }
      protected override void OnDeactivated() {
          if (printingService != null)
              printingService.PrintingSettingsLoaded -= printingService_PrintingSettingsLoaded;
          base.OnDeactivated();
      }
  }
  

  VB.NET

  Imports DevExpress.XtraPrinting
  Imports DevExpress.ExpressApp.Printing.Win
  ' ...
  Public Class ConfigurePrintingSystemViewController
      Inherits ViewController
      Private printingService As PrintingController
      Protected Overrides Sub OnActivated()
          MyBase.OnActivated()
          printingService = Frame.GetController(Of PrintingController)()
          If printingService IsNot Nothing Then
              AddHandler printingService.PrintingSettingsLoaded, _
              AddressOf printingService_PrintingSettingsLoaded
          End If
      End Sub
      Private Sub printingService_PrintingSettingsLoaded( _
      ByVal sender As Object, ByVal e As PrintableComponentLinkEventArgs)
          ConfigurePrintingSystem(e.PrintableComponentLink.PrintingSystem)
      End Sub
      Private Sub ConfigurePrintingSystem(ByVal printingSystem As PrintingSystemBase)
          SetHtmlOptions(printingSystem.ExportOptions.Html)
          SetPdfOptions(printingSystem.ExportOptions.Pdf)
          SetXlsOptions(printingSystem.ExportOptions.Xls)
      End Sub
      Private Shared Sub SetXlsOptions(ByVal xlsExportOptions As XlsExportOptions)
          ' XLS-specific options:
          xlsExportOptions.SheetName = "CustomXlsSheetTitle"
          xlsExportOptions.ShowGridLines = True
      End Sub
      Private Shared Sub SetPdfOptions(ByVal pdfExportOptions As PdfExportOptions)
          ' PDF-specific options:
          pdfExportOptions.DocumentOptions.Title = "CustomPdfTitle"
          pdfExportOptions.ImageQuality = PdfJpegImageQuality.Medium
      End Sub
      Private Shared Sub SetHtmlOptions(ByVal htmlExportOptions As HtmlExportOptions)
          ' HTML-specific options:
          htmlExportOptions.Title = "CustomHtmlTitle"
          htmlExportOptions.ExportMode = HtmlExportMode.SingleFilePageByPage
          htmlExportOptions.PageBorderColor = System.Drawing.Color.Gray
          htmlExportOptions.EmbedImagesInHTML = True
      End Sub
      Private Shared Sub SetGeneralOptions(ByVal printPreviewOptions As PrintPreviewOptions)
          ' General options:
          printPreviewOptions.DefaultFileName = "CustomFileName"
      End Sub
      Protected Overrides Sub OnDeactivated()
          If printingService IsNot Nothing Then
              RemoveHandler printingService.PrintingSettingsLoaded, _
              AddressOf printingService_PrintingSettingsLoaded
          End If
          MyBase.OnDeactivated()
      End Sub
  End Class
  

  Note

  The ShowPreviewDialog method is an extension method implemented in the DevExpress.XtraPrinting.v24.1.dll assembly. A reference to this assembly is required to compile the code above.

  You can access various export options in the ConfigurePrintingSystem, SetXlsOptions, SetPdfOptions, SetHtmlOptions and SetGeneralOptions methods. The following classes provide the available properties:

  • ExportOptions
  • XlsExportOptions
  • PdfExportOptions
  • HtmlExportOptions
  • PrintPreviewOptions

  Note

  You can implement additional methods for other export formats, and call them from the ConfigurePrintingSystem method.

• Run the Windows Forms application. Execute the PrintPreview Action in any View. In the invoked Preview dialog, click File | Export Document… and select the export format. You will see that the default export settings are changed (modified settings are highlighted in the screenshot).

  

  The default file name in the Save As dialog is also changed to “CustomFileName”

• If it is required to disable the Export Options dialog and always use the default options, add the following code to the SetGeneralOptions method:

  C#

  private static void SetGeneralOptions(PrintPreviewOptions printPreviewOptions) {
      // ...
      printPreviewOptions.ShowOptionsBeforeExport = false;
  }
  

  VB.NET

  Private Shared Sub SetGeneralOptions(ByVal printPreviewOptions As PrintPreviewOptions)
      ' ...
      printPreviewOptions.ShowOptionsBeforeExport = False
  End Sub