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 containsGraphics – the graphics object for the pageCancel – get/set a Boolean indicating print

job should be cancelledHasMorePages – set to true if there are more

pages to print. Default is false.

10

PrintPageEventArgs

MarginBounds – rectangle representing area within the marginsThe 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 sizedouble 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

ThisEnsured the documentation would not be lostGave 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

Tag Meaning

code Enclosed text is code

example Contains an example of how to use the code

exception Used on methods which throw exceptions. The cref parameter is set to the fully qualified type of the exception.

para Start of paragraph

param Parameter description. name property indicates which parameter

remarks Supplemental explanation to summary information

24

Documentation Tags

Tag Meaning

returns Describes the return value

see Refers the reader to another member. The cref attribute is set to the member name

seealso Similar to see

summary Description of the object

typeparam Type parameter description. name property indicates which parameter

value Describes 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

<?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 projectsBecomes 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 contentRight click on the setup project and select

view | File System This will display the content that will be

placed intoApplication folderUser’s desktopUsers 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