PrintForm Component

PrintForm Component
Introduction
The PrintForm component for Visual Basic 2005 enables you to print an image of a Windows Form at run time. Its behavior replaces that of the PrintForm method in earlier versions of Visual Basic.

Contents
PrintForm Component Overview How to: Add the PrintForm Component to the Toolbox How to: Print a Form with the PrintForm Component How to: Print the Client Area of a Form How to: Print Client and Non-client Areas of a Form How to: Print a Scrollable Form Properties Methods Events

PrintForm Component Overview

A common scenario for Windows Forms is to create a form that is formatted to resemble a paper form or a report, and then to print an image of the form. Although you can use a PrintDocument component to do this, it would require a lot of code. The PrintForm component enables you to print an image of a form to a printer, to a print preview window, or to a file without using a PrintDocument component. The PrintForm component can be added to the Printing tab of the Toolbox. When it is dragged onto a form it appears in the component tray, the small area under the bottom border of the form. When the component is selected, properties that define its behavior can be set in the Properties window. All of these properties can also be set in code. You can also create an instance of the PrintForm component in code without adding the component at design time. When you print a form, everything in the client area of the form is printed. This includes all controls and any text or graphics drawn on the form by graphics methods. By default, the form's title bar, scroll bars, and border are not printed. Also by default, the PrintForm component prints only the visible part of the form. For example, if the user resizes the form at run time, only the controls and graphics that are currently visible are printed. The default printer used by the PrintForm component is determined by the operating system's Control Panel settings. After printing is initiated, a standard PrintDocument printing dialog box is displayed. This dialog box enables users to cancel the print job.

Key Methods, Properties, and Events

The key method of the PrintForm component is the Print method, which prints an image of the form to a printer, print preview window, or file. There are two versions of the Print method: A basic version without parameters: Print() An overloaded version with parameters that specify printing behavior: Print(printForm As Form,

file:///C|/Program Files/Microsoft Visual Basic 2005 Po...PrintForm Component 1.0/Documentation/PrintFormHelp.htm (1 of 13)08/08/2011 3:45:22 PM

PrintForm Component

printFormOption As PrintOption) The PrintOption parameter of the overloaded method determines the underlying implementation used to print the form, whether the form's title bar, scroll bars, and border are printed, and whether scrollable parts of the form are printed. The PrintAction property is a key property of the PrintForm component. This property determines whether the output is sent to a printer, displayed in a print preview window, or saved as an Encapsulated PostScript file. If the PrintAction property is set to PrintToFile, the PrintFileName property specifies the path and file name. The PrinterSettings property provides access to an underlying PrinterSettings object that enables you to specify such settings as the printer to use and the number of copies to print. You can also query the printer's capabilities, such as color or duplex support. This property does not appear in the Properties window; it can be accessed only from code. The Form property is used to specify the form to print when you invoke the PrintForm component programmatically. If the component is added to a form at design time, that form is the default. Key events for the PrintForm component include the following: BeginPrint event. Occurs when the Print method is called and before the first page of the document prints. EndPrint event. Occurs after the last page is printed. QueryPageSettings event. Occurs immediately before each page is printed.

Remarks
If a form contains text or graphics drawn by System.Drawing.Graphics methods, use the basic Print (Print()) method to print it. Graphics may not render on some operating systems when the overloaded Print method is used. If the width of a form is wider than the width of the paper in the printer, the right side of the form might be cut off. When you design forms for printing, make sure that the form fits on standard-sized paper.

Example
The following example shows a common use of the PrintForm component. ' Visual Basic. Dim pf As New PrintForm pf.Form = Me pf.PrintAction = PrintToPrinter pf.Print()

How to: Add the Component to the Toolbox

The PrintForm component for Visual Basic 2005 must be added to the Toolbox before you can use it for the first time. The following procedure describes how to add the component to the Toolbox. To add the PrintForm component to the Toolbox

file:///C|/Program Files/Microsoft Visual Basic 2005 Po...PrintForm Component 1.0/Documentation/PrintFormHelp.htm (2 of 13)08/08/2011 3:45:22 PM

PrintForm Component

1. 2. 3. 4.

On the File menu, choose New Project. In the New Project dialog box, select Windows Application, and then click OK. In the Toolbox, select the Printing tab. On the Tools menu, choose Choose Toolbox Items.

5. In the Choose Toolbox Items dialog box, select PrintForm from the .NET Framework Components list and check the checkbox next to it. 6. Click OK to add it to the Toolbox.

How to: Print a Form with the PrintForm Component

The PrintForm component allows you to quickly print an image of a form exactly as it appears on screen without the need for a PrintDocument component. The following procedures show how to print a form to a printer, to a print preview window, or to an Encapsulated PostScript file. To print a form to the default printer 7. In the Toolbox, select the Printing tab then select the PrintForm component and drag it onto your form. The PrintForm component will be added to the component tray. 8. In the Properties window, select the PrintAction property and set it to PrintToPrinter. 9. Add the following code in the appropriate event handler (for example, in the Click event handler for a Print Button.) PrintForm1.Print()

To display a form in a Print Preview window 10. In the Toolbox, select the Printing tab then select the PrintForm component and drag it onto your form. The PrintForm component will be added to the component tray. 11. In the Properties window, select the PrintAction property and set it to PrintToPreview. 12. Add the following code in the appropriate event handler (for example, in the Click event handler for a Print Button.) PrintForm1.Print()

To print a form to a file

file:///C|/Program Files/Microsoft Visual Basic 2005 Po...PrintForm Component 1.0/Documentation/PrintFormHelp.htm (3 of 13)08/08/2011 3:45:22 PM

PrintForm Component

13. In the Toolbox, select the Printing tab then select the PrintForm component and drag it onto your form. The PrintForm component will be added to the component tray. 14. In the Properties window, select the PrintAction property and set it to PrintToFile. 15. Optionally, select the PrintFileName property and enter the full path and filename for the destination file. If you skip this step, the user will be prompted for a filename at run time. 16. Add the following code in the appropriate event handler (for example, in the Click event handler for a Print Button.) PrintForm1.Print()

How to: Print the Client Area of a Form

The PrintForm component allows you to quickly print an image of a form without the need for a PrintDocument component. The following procedure shows how to print just the client area of a form without the title bar, borders and scroll bars. To print the client area of a form 17. In the Toolbox, select the Printing tab then select the PrintForm component and drag it onto your form. The PrintForm component will be added to the component tray. 18. In the Properties window, select the PrintAction property and set it to PrintToPrinter. 19. Add the following code in the appropriate event handler (for example, in the Click event handler for a Print Button.) PrintForm1.Print(Me, ClientAreaOnly) Note On some operating systems text or graphics drawn with System.Drawing. Graphics methods may not print correctly. In this case, use the compatible printing method PrintForm1.Print(Me, CompatibleModeClientAreaOnly).

How to: Print Client and Non-client Areas of a Form

The PrintForm component allows you to quickly print an image of a form exactly as it appears on screen without the need for a PrintDocument component. The following procedure shows how to print a form including both the client area and the non-client area including the title bar, borders, and scroll bars. To print both client and non-client areas of a form

file:///C|/Program Files/Microsoft Visual Basic 2005 Po...PrintForm Component 1.0/Documentation/PrintFormHelp.htm (4 of 13)08/08/2011 3:45:22 PM

PrintForm Component

20. In the Toolbox, select the Printing tab then select the PrintForm component and drag it onto your form. The PrintForm component will be added to the component tray. 21. In the Properties window, select the PrintAction property and set it to PrintToPrinter. 22. Add the following code in the appropriate event handler (for example, in the Click event handler for a Print Button.) PrintForm1.Print(Me, FullWindow) Note On some operating systems text or graphics drawn with System.Drawing. Graphics methods may not print correctly. In this case, use the compatible printing method PrintForm1.Print(Me, CompatibleModeFullWindow).

How to: Print a Scrollable Form

The PrintForm component allows you to quickly print an image of a form without the need for a PrintDocument component. By default, only the currently visible part of the form is printed; if a user has resized the form at run time the result may not be as intended. The following procedure shows how to print the entire client area of a scrollable form even if it has been resized. To print the entire client area of a scrollable form 23. In the Toolbox, select the Printing tab then select the PrintForm component and drag it onto your form. The PrintForm component will be added to the component tray. 24. In the Properties window, select the PrintAction property and set it to PrintToPrinter. 25. Add the following code in the appropriate event handler (for example, in the Click event handler for a Print Button.) PrintForm1.Print(Me, Scrollable) Note On some operating systems text or graphics drawn with System.Drawing. Graphics methods may not print correctly. In this case, you will not be able to print using the Scrollable parameter.

PrintForm Properties
PrintForm.Form Property PrintForm.PrintAction Property PrintForm.PrinterSettings Property PrintForm.PrintFileName Property

PrintForm.Form Property
The Form property of the PrintForm component determines the form to be printed. Namespace: Microsoft.VisualBasic.PowerPacks.Printing ' Usage. Dim instance As PrintForm
file:///C|/Program Files/Microsoft Visual Basic 2005 Po...PrintForm Component 1.0/Documentation/PrintFormHelp.htm (5 of 13)08/08/2011 3:45:22 PM

PrintForm Component

Dim value As Form

value = instance.Form

Return Value
Returns a Form object.

Remarks
If the PrintForm component is hosted on a form, the parent form is the default value. If an instance of a PrintForm component is created at run time, the Form property must be set. If it is not, a System. Argument.NullException exception is raised. Note When you use the basic Print method or the overloaded Print method with the PrintOption parameter set to CompatibleModeClientAreaOnly or CompatibleModeFullWindow, the form specified by the Form property must have the focus. If it is not, an exception is raised. To avoid this, call the Focus function for that form before you call Print.

Example Description
The following example demonstrates how to set the Form property.

Code
PrintForm1.Form = My.Forms.Form2

PrintForm.PrintAction Property
The PrintAction property of the PrintForm component determines whether the output is directed to a printer, to a print preview window, or to a file. Namespace: Microsoft.VisualBasic.PowerPacks.Printing ' Usage Dim instance As PrintForm Dim value As System.Drawing.Printing.PrintAction

value = instance.PrintAction

Return Value
Returns a PrintAction enumeration.

Members
Member name Description

file:///C|/Program Files/Microsoft Visual Basic 2005 Po...PrintForm Component 1.0/Documentation/PrintFormHelp.htm (6 of 13)08/08/2011 3:45:22 PM

PrintForm Component

PrintToFile PrintToPreview PrintToPrinter

The print operation is directed to a file. The print operation is directed to a print preview dialog box. The print operation is directed to a printer.

Remarks
When PrintToPrinter is selected, the output is directed to the system default printer. You can override this behavior and explicitly set the printer and printer properties by using the PrinterSettings property. If no default printer is available, the user is prompted to select a printer. When PrintToPreview is selected, the form is displayed in a standard Windows Forms PrintPreviewDialog control. When PrintToFile is selected, an image of the form is saved to an Encapsulated PostScript file (.eps, .ps, or .ai) in the path specified by the PrintFileName property. If no file name is specified, the user is prompted for a file name. Note Files are saved in an 8-bit Greyscale PostScript format. 24-bit RGB PostScript is not supported. Note The user is not prompted for a path or file name extension. To make sure that the file has a valid path and extension, you can implement your own dialog box. To do this, use a SaveFileDialog component and assign the return value to the PrintFileName property before calling the Print method.

Example Description
The following example demonstrates how to set the PrintAction property. It assumes that you have three RadioButton controls that enable the user to select a printing method.

Code
If RadioButton1.Checked = True Then PrintForm1.PrintAction = Printing.PrintAction.PrintToPrinter ElseIf RadioButton2.Checked = True Then PrintForm1.PrintAction = Printing.PrintAction.PrintToPreview Else PrintForm1.PrintFileName = _ My.Computer.FileSystem.SpecialDirectories. CurrentUserApplicationData _ & "Form1.eps" PrintForm1.PrintAction = Printing.PrintAction.PrintToFile End If

PrintForm.PrinterSettings Property
The PrinterSettings property of the PrintForm component exposes a PrinterSettings object that you can use to specify various properties of a printer. These are the same settings that are exposed to a user in the Print dialog box.
file:///C|/Program Files/Microsoft Visual Basic 2005 Po...PrintForm Component 1.0/Documentation/PrintFormHelp.htm (7 of 13)08/08/2011 3:45:22 PM

PrintForm Component

Namespace: Microsoft.VisualBasic.PowerPacks.Printing ' Usage Dim instance As PrintForm Dim value As System.Drawing.Printing.PrinterSettings

value = instance.PrinterSettings

Return Value
Returns a PrinterSettings object.

Remarks
You can specify several printer settings by using the PrinterSettings property. For example, use the PrinterSettings.Copies property to specify the number of copies to print. Use the PrinterSettings. PrinterName property to specify the printer to use, and use the PrinterSettings.PrintRange property to specify the range of pages to print. Tip To enable the user to select the settings, you may want to use a PrintDialog component to display a standard Print dialog box, and then assign the PrintDialog.PrinterSettings property to PrintForm.PrinterSettings.

Example Description
The following code example demonstrates how to use the PrinterSettings property to set the number of copies to print and to check whether the specified printer is valid.

Code
PrintForm1.PrinterSettings.Copies = 2 If PrintForm1.PrinterSettings.IsValid Then PrintForm1.Print() End If

PrintForm.PrintFileName Property
The PrintFileName property of the PrintForm component determines the file name and of an Encapsulated PostScript file and the path to which the file will be saved when the PrintAction property is set to PrintToFile. Namespace: Microsoft.VisualBasic.PowerPacks.Printing ' Usage. Dim instance As PrintForm Dim value As String

file:///C|/Program Files/Microsoft Visual Basic 2005 Po...PrintForm Component 1.0/Documentation/PrintFormHelp.htm (8 of 13)08/08/2011 3:45:22 PM

PrintForm Component

value = instance.PrintFileName

Return Value
Returns a String that contains a file path and name.

Remarks
When the PrintAction property is set to PrintToFile, an image of a form will be saved to an Encapsulated PostScript file (.eps, .ps, or .ai). The PrintFileName property specifies the path to the file. Note To enable other applications to recognize the file as a PostScript file, you must use a valid PostScript file name extension (.eps, .ps, or .ai) in the PrintFileName property. If no PrintFileName is specified, the user will be prompted for a file name at run time. Tip The user will not be prompted for a path or a file name extension. To make sure that the file has a valid path and extension, you can implement your own dialog box. To do this, use a SaveFileDialog component and assign the return value to the PrintFileName property before calling the Print method.

Example Description
The following example demonstrates how to display a dialog box to prompt a user for a file name and then assign it to the PrintFileName property.

Code
Dim fileDialog As New Windows.Forms.SaveFileDialog Dim filePath As String fileDialog.Title = "Save to PostScript file" fileDialog.AddExtension = True fileDialog.Filter = "Encapsulated PostScript (*.eps)|" fileDialog.InitialDirectory = _ My.Computer.FileSystem.SpecialDirectories. CurrentUserApplicationData fileDialog.ShowDialog() filePath = fileDialog.FileName & ".eps" PrintForm1.PrintFileName = filePath

PrintForm Methods
PrintForm.Print Method PrintForm.Print Method (Form, PrintOption)

PrintForm.Print Method
file:///C|/Program Files/Microsoft Visual Basic 2005 Po...PrintForm Component 1.0/Documentation/PrintFormHelp.htm (9 of 13)08/08/2011 3:45:22 PM

PrintForm Component

The Print method of the PrintForm component sends an image of a Windows Form to the destination specified by the PrintAction property. Namespace: Microsoft.VisualBasic.PowerPacks.Printing ' Usage. Dim instance As PrintForm instance.Print()

Remarks
The Print method prints all visible objects on the form. This includes any text or graphics drawn with System.Drawing.Graphics methods. By default, only the client area of the form is printed. If a user has resized the form at run time, only the currently visible part of the form will be printed. If the form has been moved so that only a part of it is visible on screen, it will still be printed as if all of the form were visible. To change the default behavior, use the overloaded Print method (Print(Form As System.Windows.Forms.Form, printFormOption As PrintOption)). The Print method is backward compatible with the Visual Basic 6.0 PrintForm method. Note Only the top-level form can be printed by using this method. If you have set the Form property to another form before calling this method, an exception is thrown. To avoid this, check the TopLevel property of the form before you call Print.

Example Description
The following example prints the current form to the system default printer, printing only the client area at its currently visible size.

Code
PrintForm1.PrintAction = Printing.PrintAction.PrintToPrinter PrintForm1.Print()

PrintForm.Print Method (Form, PrintOption)

The Print method of the PrintForm component sends an image of a Windows Form to the destination specified by the PrintAction property. Namespace: Microsoft.VisualBasic.PowerPacks.Printing ' Usage. Dim instance As PrintForm Dim printForm As Form Dim option As PrintOption

file:///C|/Program Files/Microsoft Visual Basic 2005 Po...PrintForm Component 1.0/Documentation/PrintFormHelp.htm (10 of 13)08/08/2011 3:45:22 PM

PrintForm Component

instance.Print(printForm, option) Parameters printForm Form. The name of the form to be printed. Required. option PrintOption. Specifies a PrintOption enumeration that determines how the form will be printed. Required. The following table describes the possible PrintOption values. PrintOption values CompatibleModeClientAreaOnly CompatibleModeFullWindow ClientAreaOnly FullWindow Scrollable Description Uses the compatible printing implementation to print the currently visible client area. Uses the compatible printing implementation to print the currently visible form. This includes the title bar, scroll bars, and border. Uses a different implementation to print the currently visible client area. Uses a different implementation to print the currently visible form. This includes the title bar, scroll bars, and border. Uses a different implementation to print the full client area, even if part of it is scrolled out of view.

Remarks
The Print method prints all visible objects on a form. This includes any text or graphics drawn with System.Drawing.Graphics methods. If the form specified in the printForm parameter does not have focus, and the PrintOption parameter is set to either CompatibleModeClientAreaOnly or CompatibleModeFullWindow, an exception is raised. If PrintOption is set to ClientAreaOnly, FullWindow, or Scrollable, any form in your application may be specified, even if it does not have focus. Note When the PrintOption parameter is set to either CompatibleModeClientAreaOnly or CompatibleModeFullWindow, the form specified by the Form property must have focus. If it is not, an exception is raised. To avoid this, call the Focus function for the form before you call Print. By default, only the client area of the form is printed. If you want to include the title bar, scroll bars, and border in the printed image, set the PrintOption parameter to either CompatibleModeFullWindow or FullWindow. By default, only the currently visible part of the client area or form is printed. If a user has resized the form at run time, it will be printed as currently visible on screen. If, however, part of the form has been moved off the edge of the screen, the form will still be printed as if it were completely visible. If you want to print the form at its designed size, set the PrintOption parameter to Scrollable. The Print method uses one of two underlying implementations for printing. The implementation is determined by the PrintOption parameter. When this parameter is set to

file:///C|/Program Files/Microsoft Visual Basic 2005 Po...PrintForm Component 1.0/Documentation/PrintFormHelp.htm (11 of 13)08/08/2011 3:45:22 PM

PrintForm Component

CompatibleModeClientAreaOnly or CompatibleModeFullWindow, an implementation that is backward compatible with the Visual Basic 6.0 PrintForm method is used. When this parameter is set to ClientAreaOnly, FullWindow or Scrollable, a different implementation that doesn't require the form to have focus is used. Note On some operating systems, text or graphics drawn with System.Drawing.Graphics methods may not display correctly. In addition, if you set the PrintOption parameter to ClientAreaOnly, FullWindow or Scrollable, you may have to call the Refresh method of the form immediately after you call Print. If you do not call this method, artifacts might appear on the form.

Example Description
The following example prints the current form to the system default printer, printing only the client area at its currently displayed size and using the non-compatible method of printing.

Code
PrintForm1.PrintAction = Printing.PrintAction.PrintToPrinter PrintForm1.Print(Me, ClientAreaOnly) Me.Refresh

PrintForm Events
PrintForm.BeginPrint Event PrintForm.EndPrint Event PrintForm.QueryPageSettings Event

PrintForm.BeginPrint Event
Occurs when the Print method is called, before the first page of the form prints. Namespace: Microsoft.VisualBasic.PowerPacks.Printing ' Usage. Dim instance As PrintDocument Dim handler As PrintEventHandler

AddHandler instance.BeginPrint, handler

Remarks
The BeginPrint event handler is typically used to perform any tasks that need to be accomplished before printing.

PrintForm.EndPrint Event
file:///C|/Program Files/Microsoft Visual Basic 2005 Po...PrintForm Component 1.0/Documentation/PrintFormHelp.htm (12 of 13)08/08/2011 3:45:22 PM

PrintForm Component

Occurs when the last page of the document has printed. Namespace: Microsoft.VisualBasic.PowerPacks.Printing ' Usage Dim instance As PrintDocument Dim handler As PrintEventHandler

AddHandler instance.EndPrint, handler

Remarks
The EndPrint event handler is typically used to perform any tasks that have to be accomplished after printing. For example, it can be used to display a dialog box to notify the user that the print job is finished.

PrintForm.QueryPageSettings Event
Occurs immediately before each page is printed. Namespace: Microsoft.VisualBasic.PowerPacks.Printing ' Usage. Dim instance As PrintDocument Dim handler As QueryPageSettingsEventHandler

AddHandler instance.QueryPageSettings, handler

Remarks
The QueryPageSettings event handler is typically used to change settings for a single page in a multipage form. For example, it can be used to change the page width.

file:///C|/Program Files/Microsoft Visual Basic 2005 Po...PrintForm Component 1.0/Documentation/PrintFormHelp.htm (13 of 13)08/08/2011 3:45:22 PM