An Introduction to Printing in C# Windows Applications: Models and Implementation

1. Windows Programming Using C# Printing, Documentation, & Deployment

2. Contents • Printing • Documentation • Deployment

3. Printing • Windows supports a sophisticated printing model • Each printer has a device driver which is able to render GDI • Printer manufacturers provide the drivers for popular operating systems • .NET provides full access to the underlying printing system

4. Device Independence • The beauty of the Windows printing model is its device independence • Each printer page has a Graphics object, as does every window • To print a window, simply issue the same drawing commands to the page graphics object as you did to the graphics object for the window • The only change needed might be scaling

5. PrintDocument • The main object is the PrintDocument • This represents • An interface to a printer • A set of PrinterSettings that determine how the printer is configured • Properties • DocumentName – name of the document being printed which is displayed in printing dialogs

6. PrintDocument • Methods • Print – call this when you want to start printing • Events • PrintPage – this is fired when the current page is needed for printing • BeginPrint – just before the first page prints • EndPrint – after the last page has printed

7. Using PrintDocument • You usually create one PrintDocument for your aplication • In Visual Studio, place one on your form and it will be displayed in the tray under the form • When your document is ready to print, call PrintDocument.Print()

8. Using PrintDocument • Of course, PrintDocument has no idea of what to print • It has to ask the application • It does this by raising a PrintPage event • The application must have a handler for this event • This handler will print the content of the page

9. PrintPage Event Handler • This has the signature • PrintPage(object sender, PrintPageEventArgs e) • PrintPageEventArgs contains • Graphics – the graphics object for the page • Cancel – get/set a Boolean indicating print job should be cancelled • HasMorePages – set to true if there are more pages to print. Default is false.

10. PrintPageEventArgs • MarginBounds – rectangle representing area within the margins • The X, Y show the location of the area within the margins and the width and height the size • PageBounds – the size of the physical page • PageSettings – detailed settings of the page

11. PrintPage Event Handler • The event handler must • Extract the graphics object from the arguments • Perform any necessary scaling from the window to the page • Issue the draw commands to the graphics object for the page • Set HasMorePages to tell the printing system whether more pages are to follow

12. Scaling • The size of a figure in a window is not always the size it should be printed • We can do some simple scaling to fix this • First, we assume that screen resolution is approximately printer resolution • The PageSettings in the arguments contains the actual resolution of the printer if more accurate calculations are needed

13. Scaling • The Margins object has the information we need • We will just use the same scale factor for the X and Y axes to preserve the aspect ratio • First, get the size of the print area within the margins int printAreaWd = e.MarginBounds.Width; int printAreaHt = e.MarginBounds.Height;

14. Scaling • Then, compute a scale factor by dividing the print area by the window size double scale = 1.0; if (printAreaWd < printAreaHt){ scale = printAreaWd / this.Width; } else { scale = printAreaHt / this.Height; }

15. Scaling • Now, to draw a line from (x,y) to (x1, y1) Margins m = e.Margins; e.Graphics.DrawLine(pen, (int)(x * scaleFactor + m.X), (int)(y * scaleFactor + m.Y), (int)(x1 * scaleFactor + m.X), (int)(y1 * scaleFactor + m.Y));

16. PrintDialog • So far, we have been printing to the default printer with no options • To change anything, we use the PrintDialog • To create a PrintDialog • drag it to your form • Set the Document property to the PrintDocument you want to print • The dialog will configure the printer settings in the PrintDocument

17. PrintDialog • To show it, check the result, and print DialogResult r = printDialog1.ShowDialog(); if (r == DialogResult.OK){ printDocument1.Print(); }

18. PrintPreviewDialog • To preview the document, use a PrintPreviewDialog • To create one • Drag one to your form and it will appear in the tray underneath the form • Set the Document property to the PrintDocument you want to preview • To show the preview • printPreviewDialog1.ShowDialog();

19. PageSetupDialog • If you want to set the printer settings for the preview or for printing, use the PageSetupDialog • To create one • Drag one to your form and it will appear in the tray underneath the form • Set the Document property to the PrintDocument you want to preview • To show the preview • pageSetupDialog1.ShowDialog(); • * see WinDraw

20. Contents • Printing • Documentation • Deployment

21. Documentation • Donald Knuth had the idea of placing the documentation with the code • This • Ensured the documentation would not be lost • Gave it a chance of being kept up to date • Java was the first language to generate documentation from comments in code

22. C# Documentation • C# continues the trend started by Java • Documentation • Is placed just before the element it describes • Is marked by comments starting with three slashes • Contain well-formed XML /// <summary>My very own class</summary> public class MyClass {…}

23. Documentation Tags

24. Documentation Tags

25. Generating Documentation • The first step is to bring up the project properties • Under the build tab, check XML Documentation File

26. The Output • The output is generated when the project is next built • The output format is XML <?xml version="1.0"?> <doc> <assembly> <name>WinDraw</name> </assembly> <members> <member name="T:WinDraw.Properties.Resources"> <summary> A strongly-typed resource class, for looking up localized strings, etc. </summary> </member>

27. Processing the Output • Visual Studio used to have a command to produce web pages from the XML but it has been discontinued • SourceForge has Ndoc to format documentation but it only supports .NET 1.1 • Write your own XSLT program to process the XML output

28. Contents • Printing • Documentation • Deployment

29. Deployment • .NET projects do not make use of the registry • This means that they are simpler to deploy than Win32 applications • There are several options • Copy the assemblies to a directory • Create a cab file containing the application files • Create a setup project • Create a web setup project

30. Copying • Copying the files is the easiest solution • However • It only works for small projects • Becomes a lot of work to get it right for a large project • It not suitable for novices to use

31. Cab Deployment • A cab file is just a zip file • It is used to package ActiveX components for download to legacy web browsers • Click File | Add New Project • Select cab project

32. Cab Deployment

33. Cab Properties • The new cab project appears in the solution explorer on the right • Right click and select properties • This will let you set the name for the output file

34. Adding Cab Content • Right click on the project and select add • Project output • Standard parts of a project • File • Individual files

35. A Setup Deployment Project • A setup deployment project will create an msi installer which will automatically deploy the application on a target computer • To create • Click File | Add New Project • Select setup project • This adds the project to the solution explorer

36. Setup Properties • To add content • Right click on the setup project and select view | File System • This will display the content that will be placed into • Application folder • User’s desktop • Users start menu

37. Setup Properties • Folders are on the left and their contents are on the right • Right click on a folder and select add • Folder – create a new folder • Project output – to add project output like the assembly • File – add any file • Assembly – an assembly from the GAC or file system

38. Setting Location of Application Directory • Click on the Application Folder • A property sheet is displayed for it in the lower right of Visual Studio • The value for Default Location is • [ProgramFilesFolder]\[Manufacturer]\[Product Name] • Manufacturer & Product name are properties which are set in the project property page • ProgramFilesFolder is the Program Files folder on the target machine • You can also edit the string

39. Creating Shortcuts • Create a shortcut to the primary output by right clicking on it • Drag shortcut to user’s desktop • To add to program menu • Optionally right on program menu and add new folder • Drag shortcut to program menu or new folder

40. Configuring the User Interface • Right click on project and select View | User Interface • This displays all the screens for the install dialog • Clicking on each lets you set properties for it • You can also delete steps if they are not needed