Print Controllers

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

Figure 8.1. The Printing Dialog Shown by PrintControllerWithStatusDialog

The Printing dialog is provided by a print controller. The print controller, modeled as the PrintController abstract base class (from the System.Drawing.Printing namespace) and exposed via the PrintController property of the PrintDocument object, manages the underlying printing process and fires the events as printing progresses. Because printing is fundamentally the rendering of graphics to a printer, a Graphics object that wraps the printer device is required so that drawing commands make it to the printer.

This is the job of the StandardPrintController (from the System.Drawing.Printing namespace), although the default print controller is actually an instance of the PrintControllerWithStatusDialog class (from the System.Windows.Forms namespace), which is the one that shows the Printing dialog in Figure 8.1 PrintControllerWithStatusDialog doesn't do anything except show the dialog; it relies on StandardPrintController to communicate with the printer. In fact, creating an instance of PrintControllerWithStatusDialog requires an instance of the StandardPrintController class as a constructor argument. So, by default, the print controller provided by the print document acts as if you'd written this code:

void printButton_Click(object sender, EventArgs e) {   PrintController standard = new StandardPrintController();   PrintController status =      new PrintControllerWithStatusDialog(standard, "Print Status");   printDocument.PrintController = status;   printDocument.DocumentName = fileName;   printDocument.Print(); }

If you prefer to print without showing a dialogfor example, when you're printing in the backgroundyou can use StandardPrintController directly:

void printButton_Click(object sender, EventArgs e) {   // Suppress the Printing dialog   PrintController standard = new StandardPrintController();   printDocument.PrintController = standard;   printDocument.DocumentName = fileName;   printDocument.Print(); }

Print Preview

Another print controller that .NET provides is PreviewPrintController (from the System. Drawing.Printing namespace), which is used for previewing a document before it's printed. Figure 8.2 shows a preview print controller being used to prepare a document for preview.

Figure 8.2. PreviewPrintController in Use by PrintPreviewControl

PreviewPrintController is primarily used by PrintPreviewControl (from the System. Windows.Forms namespace), which shows document previews one page at a time by default. 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 8.3.

Figure 8.3. The PrintPreviewControl Hosted in a Custom Form

The client area in Figure 8.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:

namespace System.Windows.Forms {   class PrintPreviewControl : Control {     // Constructors     static PrintPreviewControl();     public PrintPreviewControl();     // Properties     public bool AutoZoom { get; set; }     public int Columns { get; set; }     public PrintDocument Document { get; set; }     public override RightToLeft RightToLeft { get; set; } // New     public int Rows { get; set; }     public int StartPage { get; set; }     public override string Text { get; set; }     public bool UseAntiAlias { get; set; }     public double Zoom { get; set; }     // Methods     public void InvalidatePreview();     public override void ResetBackColor();     public override void ResetForeColor();     // Events     public event EventHandler StartPageChanged;     public event EventHandler TextChanged;   } }

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 8.4 shows a PrintPreviewControl with Rows set to 1 and Columns set to 2.

Figure 8.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 to dictate the page shown in the upper left portion of the control. In addition, PrintPreview Control 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 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 is your friend. Figure 8.5 shows the PrintPreviewDialog component in action.

Figure 8.5. The PrintPreviewDialog Component

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

PrintPreviewDialog printPreviewDialog; void InitializeComponent() {   ...   this.printPreviewDialog = new PrintPreviewDialog();   ... } void printPreviewDialogButton_Click(object sender, EventArgs e) {   this.printPreviewDialog.Document = this.printDocument;   this.printPreviewDialog.ShowDialog(); }

PrintPreviewDialog Control Box Icon

Additionally, PrintPreviewDialog allows you to hide or show a control box icon (shown by default) using the Boolean ShowIcon property. Further, although PrintPreviewDialog exposes an Icon property, it is hidden from the Windows Forms Designer and Properties window.^[1] However, you can still set Icon programmatically:

^[1] The Icon property is "hidden" via attribution with both the Browsable and EditorBrowsable attributes, which are covered in Chapter 11: Design-Time Integration: The Properties Window.

void printPreviewDialogButton_Click(object sender, EventArgs e) {   this.printPreviewDialog.Document = this.printDocument;   // Change icon   this.printPreviewDialog.Icon = Properties.Resources.printpreview;   this.printPreviewDialog.ShowDialog(); }

This yields the icon shown in Figure 8.6

Figure 8.6. PrintPreviewDialog with Updated Control Box Icon

PrintDialog and PageSetupDialog, discussed later, provide no way to specify an icon or influence whether they show an icon.