The Print Page Event

The PrintPage event is the main event involved in printing documents. To actually send content to the printer, you must handle this event and provide code to render the content in the PrintPage event handler. All of the objects and information needed to send content to the printer are wrapped in the PrintPageEventsArgs object, which is received by the handler for this event. Table 10-3 describes the properties of the Print-PageEventArgs object.

Table 10-3 Properties of the PrintPageEventArgs Object

Property

Description

Cancel

Indicates whether a print job should be cancelled. You can cancel a pending print job by setting the Cancel property to True.

Graphics

The Graphics object is used to render content to the printed page. Encapsulates the drawing surface represented by the printer.

HasMorePages

Gets or sets a value that indicates whether additional pages should be printed. Set this property to True in the event handler to raise the event again.

MarginBounds

Gets the Rectangle object that represents the portion of the page within the margins.

PageBounds

Gets the Rectangle object that represents the total page area.

PageSettings

Gets or sets the PageSettings object for the current page.

Content is rendered to the printed page by the Graphics object provided in the PrintPageEventArgs object. The printed page behaves just like a form, control, or any other drawing surface that can be represented by a Graphics object. To render content, you use the same methods used to render content to a form. The following code example demonstrates a simple method to print a page:

' This method inscribes an ellipse inside the bounds of the page. This ' method must handle the PrintPage event in order to send content to the printer Public Sub PrintEllipse(ByVal sender As System.Object, ByVal e As _ System.Drawing.Printing.PrintPageEventArgs) e.Graphics.DrawEl lipse(Pens.Black, e.MarginBounds) End Sub

// This method inscribes an ellipse inside the bounds of the page. This // method must handle the PrintPage event in order to send content to the printer public void PrintEllipse(object sender, System.Drawing.Printing.PrintPageEventArgs e) {

e.Graphics.DrawEllipse(Pens.Black, e.MarginBounds);

The MarginBounds and PageBounds properties represent areas of the page surface. You can specify printing to occur inside the margin bounds of the page by calculating printing coordinates based on the MarginBounds rectangle. Printing that is to take place outside of the margin bounds, such as headers or footers, can be specified by calculating the printing coordinates based on the PageBounds rectangle. Print coordinates are in pixels by default.

You can specify that a print job has multiple pages by using the HasMorePages property. By default, this property is set to False. When your application logic determines that multiple pages are required to print a job, you should set this property to True. When the last page is printed, the property should be reset to False. Note that the method handling the PrintPage event must keep track of the number of pages in the job. Failure to do so can cause unexpected results while printing. For example, if you fail to set the HasMorePages property to False after the last page is printed, the application will continue to raise PrintPage events.

You can cancel a pending print job without finishing by setting the Cancel property to True. You might do this, for example, if the user clicked a Cancel button on your form.

You can end create an event handler for the PrintPage event by double-clicking the PrintDocument instance in the Designer to create a default event handler.

Was this article helpful?

0 0

Post a comment