PrintDialog component overview (Windows Forms .NET)

Printing in Windows Forms consists primarily of using the PrintDocument component to enable the user to print. The PrintPreviewDialog control, PrintDialog and PageSetupDialog components provide a familiar graphical interface to Windows operating system users.

The PrintDialog component is a pre-configured dialog box used to select a printer, choose the pages to print, and determine other print-related settings in Windows-based applications. It's a simple solution for printer and print-related settings instead of configuring your own dialog box. You can enable users to print many parts of their documents: print all, print a selected page range, or print a selection. By relying on standard Windows dialog boxes, you create applications whose basic functionality is immediately familiar to users. The PrintDialog component inherits from the CommonDialog class.

Typically, you create a new instance of the PrintDocument component and set the properties that describe what to print using the PrinterSettings and PageSettings classes. Call to the Print method actually prints the document.

Working with the component

Use the PrintDialog.ShowDialog method to display the dialog at run time. This component has properties that relate to either a single print job (PrintDocument class) or the settings of an individual printer (PrinterSettings class). One of the two, in turn, may be shared by multiple printers.

The show dialog box method helps you to add print dialog box to the form. The PrintDialog component appears in the tray at the bottom of the Windows Forms Designer in Visual Studio.

How to capture user input from a PrintDialog at run time

You can set options related to printing at design time. Sometimes you may want to change these options at run time, most likely because of choices made by the user. You can capture user input for printing a document using the PrintDialog and the PrintDocument components. The following steps demonstrate displaying the print dialog for a document:

1. Add a PrintDialog and a PrintDocument component to your form.

2. Set the Document property of the PrintDialog to the PrintDocument added to the form.

   PrintDialog1.Document = PrintDocument1
   

   printDialog1.Document = printDocument1;
   

3. Display the PrintDialog component by using the ShowDialog method.

   If PrintDialog1.ShowDialog() = DialogResult.OK Then
       PrintDocument1.Print()
   End If
   

   // display show dialog and if user selects "Ok" document is printed
   if (printDialog1.ShowDialog() == DialogResult.OK)
       printDocument1.Print();
   

4. The user's printing choices from the dialog will be copied to the PrinterSettings property of the PrintDocument component.

How to create print jobs

The foundation of printing in Windows Forms is the PrintDocument component—more specifically, the PrintPage event. By writing code to handle the PrintPage event, you can specify what to print and how to print it. The following steps demonstrate creating print job:

1. Add a PrintDocument component to your form.

2. Write code to handle the PrintPage event.

   You'll have to code your own printing logic. Additionally, you'll have to specify the material to be printed.

   As a material to print, in the following code example, a sample graphic in the shape of a red rectangle is created in the PrintPage event handler.

   Private Sub PrintDocument1_PrintPage(ByVal sender As Object, ByVal e As System.Drawing.Printing.PrintPageEventArgs) Handles PrintDocument1.PrintPage
       e.Graphics.FillRectangle(Brushes.Red, New Rectangle(100, 100, 100, 100))
   End Sub
   

   private void PrintDocument1_PrintPage(object sender, System.Drawing.Printing.PrintPageEventArgs e) =>
       e.Graphics.FillRectangle(Brushes.Red, new Rectangle(100, 100, 100, 100));
   

You may also want to write code for the BeginPrint and EndPrint events. It will help to include an integer representing the total number of pages to print that is decremented as each page prints.

Note

You can add a PrintDialog component to your form to provide a clean and efficient user interface (UI) to your users. Setting the Document property of the PrintDialog component enables you to set properties related to the print document you're working with on your form.

For more information about the specifics of Windows Forms print jobs, including how to create a print job programmatically, see PrintPageEventArgs.

How to complete print jobs

Frequently, word processors and other applications that involve printing will provide the option to display a message to users that a print job is complete. You can provide this functionality in your Windows Forms by handling the EndPrint event of the PrintDocument component.

The following procedure requires that you've created a Windows-based application with a PrintDocument component on it. The procedure given below is the standard way of enabling printing from a Windows-based application. For more information about printing from Windows Forms using the PrintDocument component, see How to create print jobs.

1. Set the DocumentName property of the PrintDocument component.

   PrintDocument1.DocumentName = "SamplePrintApp"
   

   printDocument1.DocumentName = "SamplePrintApp";
   

2. Write code to handle the EndPrint event.

   In the following code example, a message box is displayed, indicating that the document has finished printing.

   Private Sub PrintDocument1_EndPrint(ByVal sender As Object, ByVal e As System.Drawing.Printing.PrintEventArgs) Handles PrintDocument1.EndPrint
       MessageBox.Show(PrintDocument1.DocumentName + " has finished printing.")
   End Sub
   

   private void PrintDocument1_EndPrint(object sender, System.Drawing.Printing.PrintEventArgs e) =>
       MessageBox.Show(printDocument1.DocumentName + " has finished printing.");