Enhanced PrintPreviewDialog Class with PDF Output

Introduction

This article describes the implementation of an enhanced PrintPreviewDialog class that provides PDF output in addition to the standard print and preview capabilities.

C1PrintPreview

Background

The PrintPreviewDialog is convenient and easy to use. All you need to do is create an instance of the dialog class, assign your PrintDocument object to the Document property, and call the ShowDialog method.

However, PrintPreviewDialog has some shortcomings, including the following:

  • The entire document must be rendered before the preview appears. This is annoying for long documents.
  • There are no options for choosing the printer, adjusting the page layout, or selecting specific pages to print.
  • The dialog looks outdated. It hasn't changed since .NET 1.0, and it wasn't exactly cutting-edge even back then.
  • The dialog allows little or no customization.
  • There is no option to export the document to other formats such as PDF.
  • Page images are cached in the control, which limits the size of the documents that can be previewed.

The CoolPrintPreviewDialog class presented here addresses these shortcomings. It is just as easy to use as the standard PrintPreviewDialog, but has the following enhancements:

  • Pages can be previewed as soon as they are rendered. The first page is shown almost instantly and subsequent pages become available while the user browses the first ones.
  • The "Print" button shows a dialog that allows users to select the printer and page ranges to print. A "Page Layout" button is also available so users can change page size, orientation, and margins.
  • The dialog uses a ToolStrip control instead of the old toolbar.
  • You have the source and can customize everything from appearance to behavior.
  • The control creates a list of images which can be exported to other formats including PDF.

Using the Code

Using the CoolPrintPreviewDialog is as easy as using the traditional PrintPreviewDialog. You instantiate the control, set the Document property to the PrintDocument you want to preview, then call the dialog's Show method.

If you have code that uses the PrintPreviewDialog class, switching to the CoolPrintPreviewDialog only requires changing one line of code. For example:

// using a PrintPreviewDialog  
**using (var dlg = new PrintPreviewDialog())**  
{  
  dlg.Document = this.printDocument1;  
  dlg.ShowDialog(this);  
}  

// using a CoolPrintPreviewDialog  
**using (var dlg = new CoolPrintPreview.CoolPrintPreviewDialog())**  
{  
  dlg.Document = this.printDocument1;  
  dlg.ShowDialog(this);  
}

Generating the Preview Images

The core of the CoolPrintPreviewDialog class is a CoolPreviewControl that generates and shows the page previews.

The PrintDocument object has a PrintController property that specifies an object responsible for creating the Graphics objects where the document is rendered. The default print controller creates Graphics objects for the default printer and is not interesting in this case. But .NET also defines a PreviewPrintController class that creates metafiles instead. These remain available to the caller to be shown in the preview area.

The CoolPreviewControl works by temporarily replacing the document's original print controller with a PreviewPrintController, calling the document's Print method, and getting the page images while the document is rendered. The images represent pages in the document, and are scaled and displayed in the control just like any regular Image object.

The code that creates the page previews looks like this (this code is simplified for clarity, refer to the source for a better version):

// list of page images  
List _imgList = new List();  

// generate page images  
public void GeneratePreview(PrintDocument doc)  
{  
  // save original print controller  
  PrintController savePC = doc.PrintController;  

  // replace it with a preview print controller    
  doc.PrintController = new PreviewPrintController();  

  // hook up event handlers  
  doc.PrintPage  = \_doc\_PrintPage;  
  doc.EndPrint  = \_doc\_EndPrint;  

  // render the document  
  _imgList.Clear();  
  doc.Print();  

  // disconnect event handlers  
  doc.PrintPage -= \_doc\_PrintPage;  
  doc.EndPrint -= \_doc\_EndPrint;  

  // restore original print controller  
  doc.PrintController = savePC;  
}

The code installs the controller and hooks up the event handlers, then calls the Print method to generate the pages, and cleans up when it's done.

When the Print method is invoked, the document starts firing events. The PrintPage and EndPrint event handlers capture the pages as soon as they are rendered and add them to an internal image list.

The event handlers also call the Application.DoEvents method to keep the dialog responsive to user actions while the document renders. This allows users to switch pages, adjust the zoom factor, or cancel the document generation process. Without this call, the dialog would stop operating until the whole document finishes rendering.

This is the code that does all this:

void \_doc\_PrintPage(object sender, PrintPageEventArgs e)  
{  
  SyncPageImages();  
  if (_cancel)  
  {  
    e.Cancel = true;  
  }  
}  
void \_doc\_EndPrint(object sender, PrintEventArgs e)  
{  
  SyncPageImages();  
}  
void SyncPageImages()  
{  
  // get page previews from print controller  
  var pv = (PreviewPrintController)_doc.PrintController;  
  var pageInfo = pv.GetPreviewPageInfo();  

  // add whatever images are missing from our internal list  
  for (int i = _img.Count; i < pageInfo.Length; i  )  
  {  
    // add to internal list  
    _img.Add(pageInfo[i].Image);  

    // fire event to indicate we have more pages  
    OnPageCountChanged(EventArgs.Empty);  

    // if the page being previewed changed, refresh to show it  
    if (StartPage < 0) StartPage = 0;  
    if (i == StartPage || i == StartPage   1)  
    {  
      Refresh();  
    }  

    // keep application responsive  
    Application.DoEvents();  
  }  
}

This is the core of the preview code. The rest is concerned with housekeeping tasks such as scaling the preview images, updating the scrollbars, handling navigation buttons, mouse, keyboard, and so on. Please refer to the source code for the implementation details.

Updating the Page Layout

The preview dialog allows users to update the print layout. This is very easy to implement, thanks to the .NET PageSetupDialog class. Here is the code that gets called when users click the "Page Layout" button:

void \_btnPageSetup\_Click(object sender, EventArgs e)  
{  
  using (var dlg = new PageSetupDialog())  
  {  
    dlg.Document = Document;  
    if (dlg.ShowDialog(this) == DialogResult.OK)  
    {  
      // user changed the page layout, refresh preview images  
      _preview.RefreshPreview();  
    }  
  }  
}

The code shows a PageSetupDialog that allows the user to change the paper size, orientation, and margins. Changes made by the user are reflected in the document's DefaultPageSettings property.

If the user clicks OK, then we assume that the page layout has been modified, and call the RefreshPreview method on the preview control. This method regenerates all preview images using the new settings, so the user can see the changes applied to margins, page orientation, and so on.

Printing the Document

When the user clicks the "Print" button, the dialog shows a PrintDialog so the user can select the printer, page range, or change his mind and cancel the printing.

Unfortunately, page range selections are not honored if you simply call the Print method directly on the document. To remedy this, the dialog calls the Print method on the enhanced preview control instead. That implementation uses the page images already stored in the control, and honors page ranges defined in the document's PrinterSettings properties.

This is the code that gets called when the user clicks the "Print" button:

void \_btnPrint\_Click(object sender, EventArgs e)  
{  
  using (var dlg = new PrintDialog())  
  {  
    // configure dialog  
    dlg.AllowSomePages = true;  
    dlg.AllowSelection = true;  
    dlg.Document = Document;  

    // show allowed page range  
    var ps = dlg.PrinterSettings;  
    ps.MinimumPage = ps.FromPage = 1;  
    ps.MaximumPage = ps.ToPage = _preview.PageCount;  

    // show dialog  
    if (dlg.ShowDialog(this) == DialogResult.OK)  
    {  
      // print selected page range  
      _preview.Print();  
    }  
  }  
}

The Print method in the preview control starts by determining the range of pages that should be rendered. This may be the full document, a specific range, or the current selection (page being previewed). Once the page range has been determined, the code creates a DocumentPrinter helper class to perform the actual printing:

public void Print()  
{  
  // select pages to print  
  var ps = _doc.PrinterSettings;  
  int first = ps.MinimumPage - 1;  
  int last = ps.MaximumPage - 1;  
  switch (ps.PrintRange)  
  {  
    case PrintRange.CurrentPage:  
      first = last = StartPage;  
      break;  
    case PrintRange.Selection:  
      first = last = StartPage;  
      if (ZoomMode == ZoomMode.TwoPages)  
        last = Math.Min(first   1, PageCount - 1);  
      break;  
    case PrintRange.SomePages:  
      first = ps.FromPage - 1;  
      last = ps.ToPage - 1;  
      break;  
    }  

    // print using helper class  
    var dp = new DocumentPrinter(this, first, last);  
    dp.Print();  
  }  
}

The DocumentPrinter class is simple. It inherits from PrintDocument and overrides the OnPrintPage method to print only the pages selected by the user:

internal class DocumentPrinter : PrintDocument  
{  
  int \_first, \_last, _index;  
  List _imgList;  

  public DocumentPrinter(CoolPrintPreviewControl preview, int first, int last)  
  {  
    // save page range and image list  
    _first = first;  
    _last = last;  
    _imgList = preview.PageImages;  

    // copy page and printer settings from original document  
    DefaultPageSettings = preview.Document.DefaultPageSettings;  
    PrinterSettings = preview.Document.PrinterSettings;  
  }  

  protected override void OnBeginPrint(PrintEventArgs e)  
  {  
    // start from the first page  
    \_index = \_first;  
  }  
  protected override void OnPrintPage(PrintPageEventArgs e)  
  {  
    // render the current page and increment the index  
    e.Graphics.PageUnit = GraphicsUnit.Display;  
    e.Graphics.DrawImage(\_imgList[\_index  ], e.PageBounds);  

    // stop when we reach the last page in the range  
    e.HasMorePages = \_index <= \_last;  
  }  
}

This implementation renders the page images assuming all pages have the same size and orientation, which is the case for most documents. If the document contains pages of different sizes, or with different orientation, this simple implementation will not work correctly. To fix this, we would have to check that the current paper size and orientation match the preview image size before printing each page and adjust the printer settings if necessary. That is left as an exercise for the reader.

Exporting to PDF

The PDF format is extremely popular because it is compact and portable. PDF files can be posted on the web, distributed by e-mail, and viewed or printed almost anywhere.

Once a PrintDocument has been rendered into a series of images, we can use the C1PdfDocument component to render the images into a PDF document. Using this approach, any application that uses the PrintDocument class to provide printing and previewing can add a PDF export feature with minimal effort.

To implement the PDF export, we start by implementing the event handler that gets invoked when the user presses the export to PDF button on the PrintPreviewDialog:

void \_btnPdf\_Click(object sender, EventArgs e)  
{  
  using (var dlg = new SaveFileDialog())  
  {  
    dlg.Filter = "Portable Document File (*.pdf)|*.pdf";  
    dlg.DefaultExt = ".pdf";  
    if (dlg.ShowDialog() == DialogResult.OK)  
    {  
      **pdfGenerator = new PrintDocumentPdfExporter(_pdf);**  
      if (pdfGenerator.RenderDocument(Document, true))  
      {  
        _pdf.Save(dlg.FileName);  
      }  
    }  
  }  
}

The code uses a SaveFileDialog to prompt the user for the name of the PDF file to save and a PrintDocumentPdfExporter to generate the PDF file from the preview images.

The PrintDocumentPdfExporter class can be used independently of the C1PrintPreviewDialog class. For example, you may want to provide a PDF export button on the main application, that does not cause a preview dialog to appear at all.

The implementation of the PrintDocumentPdfExporter class is shown below:

class PrintDocumentPdfExporter  
{  
  // ** fields  
  PrintDocument _doc;  
  C1PdfDocument _pdf;  
  PreviewPrintController _previewController;  
  int _pageCount;  
  bool _cancel;  

  // ** ctor  
  public PrintDocumentPdfExporter(C1PdfDocument pdf)  
  {  
    // save reference to pdf component  
    _pdf = pdf;  
  }

The constructor simply saves a reference to the C1PdfDocument that will be used to generate the PDF file.

The main public method in the class is called RenderDocument. This method starts by assigning a PreviewPrintController to the document, which causes pages to be rendered into metafile images. The controller used can be a plain PreviewPrintController or a PrintControllerWithStatusDialog wrapper, depending on the value of the showProgressDialog parameter. Both of these classes are part of the .NET framework.

Once the controller has been installed, the code connects event handlers for the PrintPage and EndPrint events. These event handlers are responsible for rendering the page images into the PDF document. Once the event handlers are installed, the code invokes the Print method to render the document.

The method returns a boolean value that indicates whether the document was fully generated (and should be saved) or whether the user canceled the process by pressing the "Cancel" button on the optional progress dialog.

  // ** object model  
  public bool RenderDocument(PrintDocument doc, bool showProgressDialog)  
  {  
    // save reference to document  
    _doc = doc;  

    // initialize pdf document  
    _pdf.Clear();  
    _pdf.Landscape = false;  

    // prepare to render  
    var savePC = _doc.PrintController;  
    _previewController = new PreviewPrintController();  
    _doc.PrintController = showProgressDialog  
      ? new PrintControllerWithStatusDialog(_previewController)  
      : (PrintController)_previewController;  
    _pageCount = 0;  
    _cancel = false;  

    // render  
    try  
    {  
      \_doc.PrintPage  = \_doc_PrintPage;  
      \_doc.EndPrint  = \_doc_EndPrint;  
      _doc.Print();  
    }  
    finally  
    {  
      \_doc.PrintPage -= \_doc_PrintPage;  
      \_doc.EndPrint -= \_doc_EndPrint;  
      _doc.PrintController = savePC;  
    }  

    // done  
    return !_cancel;  
  }

The document event handlers are listed below. As each page is rendered, the handlers call the DrawPage method to render the page images (metafiles) into the PDF document. This is done using the C1PdfDocument.DrawImage method.

The C1PdfDocument.DrawImage method enumerates the GDI commands in the metafile and converts each one to the corresponding PDF vector command. The metafile is never converted into a raster image, which means the content remains scalable, searchable, and compact.

  // ** PrintDocument event handlers  
  void \_doc\_PrintPage(object sender, PrintPageEventArgs e)  
  {  
    var pages = _previewController.GetPreviewPageInfo();  
    while (_pageCount  0)  
    {  
      _pdf.NewPage();  
    }  

    // get preview page info  
    var pi = pages[index];  

    // adjust page size  
    var ps = pi.PhysicalSize;  
    _pdf.PageSize = new SizeF(ps.Width / 100f * 72, ps.Height / 100f * 72);  

    // draw image  
    var img = pi.Image;  
    \_pdf.DrawImage(img, \_pdf.PageRectangle);  
  }  
}

Previewing Really Long Documents

After I posted the first version of this project, I got some great feedback from other CodeProject users. One of them mentioned a problem I also had a while ago. If the document contains several thousand pages, caching all those images may cause problems. Windows has a limit of 10,000 GDI objects, and each page image represents at least one. If you use too many GDI objects, your application may crash, or cause other apps to crash. Not nice...

One easy way to solve this problem is to convert the page images into streams. You can then store the streams and create images on demand, only when they are needed for previewing or printing.

The code below shows a PageImageList class that does the job. You can use it much like a regular List, except when you get or set an image, it is automatically converted to and from a byte array. This way, the images stored in the list are not GDI objects and don't use up the system resources.

// This version of the PageImageList stores images as byte arrays. It is a little  
// more complex and slower than a simple list, but doesn't consume GDI resources.  
// This is important when the list contains lots of images (Windows only supports  
// 10,000 simultaneous GDI objects!)  
class PageImageList  
{  
  // ** fields  
  var _list = new List();  

  // ** object model  
  public void Clear()  
  {  
    _list.Clear();  
  }  
  public int Count  
  {  
    get { return _list.Count; }  
  }  
  public void Add(Image img)  
  {  
    _list.Add(GetBytes(img));  

    // stored image data, now dispose of original  
    img.Dispose();  
  }  
  public Image this[int index]  
  {  
    get { return GetImage(_list[index]); }  
    set { _list[index] = GetBytes(value); }  
  }  

  // implementation  
  byte[] GetBytes(Image img)  
  {  
    // clone image since GetEnhMetaFileBits is destructive  
    var clone = img.Clone() as Metafile;  

    // use interop to get the metafile bits  
    var enhMetafileHandle = clone.GetHenhmetafile().ToInt32();  
    var bufferSize = GetEnhMetaFileBits(enhMetafileHandle, 0, null);  
    var buffer = new byte[bufferSize];  
    GetEnhMetaFileBits(enhMetafileHandle, bufferSize, buffer);  

    // done with clone (already destroyed by call to GetEnhMetaFileBits)  
    clone.Dispose();  

    // return bits  
    return buffer;  
  }  
  Image GetImage(byte[] data)  
  {  
    MemoryStream ms = new MemoryStream(data);  
    return Image.FromStream(ms);  
  }  

  [System.Runtime.InteropServices.DllImport("gdi32")]  
  static extern int GetEnhMetaFileBits(int hemf, int cbBuffer, byte[] lpbBuffer);  
}

Note that the Add method disposes of the image after storing it. Normally we would not do it this way since the caller owns the image and should be responsible for disposing of it. But in this project, this arrangement allows us to swap the PageImageList implementation with a regular List, which is convenient for testing and benchmarking.

Note also that the GetBytes uses the GetHenhMetaFileBits API. This API makes the metafile invalid, so the image cannot be used after this method is called. To avoid destroying the original image, the method creates a clone first, then gets the bits from the clone.

In case you are concerned about performance, the extra conversion work causes a performance hit of about 10% while generating the document. I think this is a small price to pay for the benefit if your documents have a few hundred or a few thousand pages.

And in case you are concerned about memory usage, consider compressing the byte arrays when you store them. It is easy to do using C1Zip, and metafiles tend to compress really well. Of course, there would be a small additional performance penalty involved.

Conclusion

We implemented an enhanced PrintPreviewDialog class that provides PDF output in addition to the standard print and preview capabilities. If you have requests or suggestions for improving this document or the application, please post on our site.

Download the full source code: C1PrintPreview.zip

MESCIUS inc.

comments powered by Disqus