Print Controllers

The name of the print document also shows up in the dialog that the print document displays during printing. The Printing dialog lets the user cancel the print job as it's being spooled to the printer, as shown in Figure 7.1.

Figure 7.1. The Printing Dialog Shown by the PrintControllerWithStatusDialog

The printing status dialog is provided by a print controller. The print controller , modeled as the PrintController abstract (MustInherit) base class and exposed via the PrintController property of the PrintDocument object, actually manages the underlying printing process and fires the events as printing progresses. The core print controller is StandardPrintController, which provides the Graphics object that wraps the printer device, causing the drawing commands to make it to the printer itself. However, the default print controller is an instance of the PrintControllerWithStatusDialog class, which is the one that shows the printing dialog. The PrintControllerWithStatusDialog class doesn't do anything except show the dialog; it relies on StandardPrintController to communicate with the printer. In fact, creating an instance of the PrintControllerWithStatusDialog class requires an instance of the StandardPrintController class as a constructor argument. So, by default, the print control provided by the print document acts as if you'd written this code:

 Sub printButton_Click(sender As Object, e As EventArgs)   Dim standard As PrintController = New StandardPrintController()   ' Can change the title from "Printing" to something else   Dim status As PrintController = _       New PrintControllerWithStatusDialog(standard, "Printing")   printDocument1.PrintController = status   printDocument1.Print() End Sub 

If you'd prefer to print without showing a dialog ”for example, when you're printing in the background ”you can use StandardPrintController directly:

 Sub printButton_Click(sender As Object, e As EventArgs)   ' Suppress the Printing dialog   Dim standard As PrintController = New StandardPrintController()   printDocument1.PrintController = standard   printDocument1.Print() End Sub 

Print Preview

Another print controller that .NET provides is PreviewPrintController, which is used for previewing a document before it's printed. Figure 7.2 shows a PreviewPrintController being used to prepare a document for preview.

Figure 7.2. The PreviewPrintController in use by the PrintPreviewControl

PreviewPrintController is primarily used by PrintPreviewControl, which shows document previews one page at a time. PrintPreviewControl is available on the Toolbox and uses the drawing commands performed in PrintDocument's PrintPage event handler to display the client area for a standard print preview-style dialog, as shown in Figure 7.3.

Figure 7.3. The PrintPreviewControl Hosted in a Custom Form

The client area in Figure 7.3 consists of a PrintPreviewControl set to fill the client area (using DockStyle.Fill). Notice that it draws what looks like a piece of paper in miniature , showing the drawing performed by the PrintPage event handler. The PrintPreviewControl class has all kinds of interesting properties and methods for implementing a print preview-style dialog:

 Class PrintPreviewControl   Inherits Control   Implements IComponent   Implements IDisposable   ' Constructors   Public Sub New()   ' Properties   Property AutoZoom() As Boolean   Property Columns() As Integer   Property Document() As PrintDocument   Property Rows() As Integer   Property StartPage() As Integer   Property UseAntiAlias() As Boolean   Property Zoom() As Single   ' Methods   Sub InvalidatePreview()   MustOverride Sub ResetBackColor()   MustOverride Sub ResetForeColor() End Class 

The only requirement is that the Document property be set to an instance of a PrintDocument so that the preview control can get the contents of each page to be displayed. Displaying multiple pages at once is a matter of setting the Rows and Columns properties. Figure 7.4 shows a PrintPreviewControl with Rows set to 1 and Columns set to 2.

Figure 7.4. Previewing Multiple Pages at Once in PrintPreviewControl

Displaying the next page (or the next set of pages) is a matter of setting the StartPage property, which dictates the page shown in the upper left of the control. In addition, PrintPreviewControl interprets Page Up and Page Down to move between pages.

The Zoom property is a multiplier : A Zoom of 1.0 is 100%, a Zoom of 0.5 is 50%, and a Zoom of 2.0 is 200%. The AutoZoom property is handy when PrintPreviewControl can resize. When AutoZoom is true (the default), PrintPreviewControl sets the Zoom property to scale the page (or pages) to a size as large as possible inside the control.

Finally, the UseAntiAlias property applies antialiasing to the preview image (this defaults to false to let the printer's higher resolution print smoothly without the need to antialias).

Although it's useful to be able to implement a custom print preview-style dialog with zooming, page count, and multipage support, often a "standard" print preview dialog is all that's required. In those cases, the PrintPreviewDialog component from the Toolbox is your friend. Figure 7.5 shows the PrintPreviewDialog component in action.

Figure 7.5. The PrintPreviewDialog Component

The PrintPreviewDialog component uses PrintPreviewControl and your PrintDocument instance to provide a full-featured , preview-style dialog:

 Dim printPreviewDialog1 As PrintPreviewDialog Sub InitializeComponent()   ...   Me.printPreviewDialog1 = New PrintPreviewDialog()   ... End Sub Sub previewButton_Click(sender As Object, e As EventArgs)   printPreviewDialog1.Document = printDocument1   printPreviewDialog1.ShowDialog() End Sub