PrintDialog

The PrintDialog component displays the dialog box shown in Figure G-17. A program calls the com-ponent’s ShowDialog method to display the dialog.

Figure G-17: The PrintDialog component lets the user specify printing options.

The following table describes the dialog box’s most useful properties.

Open table as spreadsheet

Property	Purpose
AllowPrintToFile	Determines whether the Print to file button is enabled.
AllowSelection	Determines whether the Selection radio button is enabled.
AllowSomePages	Determines whether the Pages radio button, as well as the From and To text boxes, are enabled.
Document	The PrintDocument object that provides the dialog with a Printer?Settings object.
PrinterSettings	The PrinterSettings object that the dialog modifies.
PrintToFile	Determines whether the Print to file box is checked.
ShowHelp	Determines whether the Help button is visible. If this is True, you should catch the component’s HelpRequest event and give the user some help.
ShowNetwork	Determines whether the Network button is visible.

If the user clicks Print, the dialog returns DialogResult.OK. If the user clicks Cancel, the dialog box returns DialogResult.Cancel. The program can use the dialog box’s PrintToFile property to see if the user checked the Print to file box, and it can use the PrinterSettings object to learn about the user’s other selections.

The following table lists the PrinterSettings object’s properties that are most useful for learning about the user’s selections. You can set many of these properties before displaying the dialog box to give it initial values. After the dialog box closes, the properties indicate the user’s selections.

Open table as spreadsheet

Property	Purpose
CanDuplex	Indicates whether the printer can print in duplex.
Collate	Indicates whether the user checked the Collate box.
Copies	The number of copies the user selected.
Duplex	Indicates whether the user asked for duplex printing.
FromPage	The number the user entered in the From text box.
InstalledPrinters	Returns a collection listing the system’s installed printers.
IsDefaultPrinter	True if the printer given by the PrinterName property is the default printer.
IsPlotter	True if the printer is a plotter device.
IsValid	True if the printer given by the PrinterName property is a valid printer.
LandscapeAngle	The angle at which the printout is rotated to produce landscape printing. The valid angles are 90 and 270 degrees, or 0 if the printer doesn’t support landscape printing.
MaximumCopies	The maximum number of copies that the printer will let you print at a time.
MaximumPage	The largest value that the user is allowed to enter in the To and From boxes.
MinimumPage	The smallest value that the user is allowed to enter in the To and From boxes.
PaperSizes	Returns a collection of objects describing the paper sizes supported by the printer. These PaperSize objects have the properties Height, Width, PaperName, and Kind (for example, Letter).
PaperSources	Returns a collection of objects describing the paper trays provided by the printer. These PaperSource objects have the properties SourceName (for example, Default tray) and Kind (for example, Upper).
PrinterName	Gets or sets the name of the printer to use.
PrinterResolutions	Returns a collection of PrinterResolution objects that describe the resolutions supported by the printer. PrinterResolution objects have the properties Kind (High, Medium, Low, Draft, or Custom), X, and Y. The X and Y properties return negative values for standard resolutions and the number of dots per inch (dpi) for custom resolutions.
PrintRange	Indicates the pages that the user wants to print. This can have the value AllPages (print everything), Selection (print the current selection), or SomePages (print the pages between FromPage and ToPage).
PrintToFile	Indicates whether the Print to file check box is selected.
SupportsColor	True if the printer supports color.
ToPage	The number the user entered in the To text box.

The FromPage and ToPage properties must lie between the MinimumPage and MaximumPage values before you display the dialog box or the dialog box raises an error. If the user enters a value outside of the range MinimumPage to MaximumPage and clicks Print, the dialog box displays a message similar to “This value is not within the page range. Enter a number between 10 and 30.” It then refuses to close.

Usually a program associates a PrintDialog with a PrintDocument object and that object provides the PrinterSettings object. You can either create the PrintDialog object at runtime, or you can use the PrintDocument component described in the following section. If you create a PrintDocument component at design time, then you can also set the PrintDialog’s Document property to that component at design time.

The following code shows how a program might print a document. In this example, the pdlgRectangle and pdlgRectangle components were created and pdlgRectangle.Document was set to pdlgRectangle at design time. When the user clicks the Print button, the program displays the PrintDialog. If the user clicks the dialog box’s Print button, then the code calls the PrintDocument object’s Print method. When the PrintDocument object needs to generate a page for printing, it raises its PrintPage event. In this example, the event handler draws a rectangle and indicates that the document has no more pages to draw.

  Imports System.Drawing.Printing Public Class Form1     ' Display the print dialog.     Private Sub btnPrint_Click(ByVal sender As System.Object, _      ByVal e As System.EventArgs) Handles btnPrint.Click         If pdlgRectangle.ShowDialog() = Windows.Forms.DialogResult.OK Then             ' Print the document.             pdocRectangle.Print()         End If     End Sub     ' Print a page of the document.     Private Sub PrintDocument1_PrintPage(ByVal sender As Object, _      ByVal e As System.Drawing.Printing.PrintPageEventArgs) _      Handles pdocRectangle.PrintPage         e.Graphics.DrawRectangle(Pens.Black, 100, 100, 600, 300)         e.HasMorePages = False     End Sub End Class 

For more information on the PrintDocument object, see the following section.