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 /// My very own class public class MyClass {…}

23 Documentation Tags TagMeaning codeEnclosed text is code exampleContains an example of how to use the code exceptionUsed on methods which throw exceptions. The cref parameter is set to the fully qualified type of the exception. paraStart of paragraph paramParameter description. name property indicates which parameter remarksSupplemental explanation to summary information

24 Documentation Tags TagMeaning returnsDescribes the return value seeRefers the reader to another member. The cref attribute is set to the member name seealsoSimilar to see summaryDescription of the object typeparamType parameter description. name property indicates which parameter valueDescribes the value of a property

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 WinDraw A strongly-typed resource class, for looking up localized strings, etc.

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