In this section we will see how we can add printing support in WPF applications. We will start off with printing and XPS and then move on to XPSDocumentWriter and then we will have a look on how to work with print options and customize print dialog.
XPS – XML Paper Specification
The API for printing is the same as the API for creating the XPS document. XPS has two important features.
- It provides native print spool option which is useful for WPF printing. XPS is designed to WPF native graphics model efficiently. In theory XPS can go to the target device and rasterized there to provide maximum fidelity. Although in practice most printers don’t know how to render xps but this was the design while designing XPS.
- XPS acts as the fixed layout document format i.e. like pdf version of the WPF.
We can generate a XPS document by printing something using the Microsoft XPS Document Writer virtual printer. This is available on machines that have .NET 3.0 installed. When we print something using this device it saves a document in XPS format on the disk.
XPS Document Writer
The default viewer for XPS is internet explorer. It’s a file that contains all the pages to be printed. If we zoom in we will see that the text is scaling properly.
The file convention is based on what the office files use. If we change the extension of the file from .xps to .zip and extract the contents of it then we will see that there is a documents folder.
WPF PRint Documents Folder
If we go inside it we will see that there is a pages folder which will contain a file corresponding to each page.
WPF Print Pages Folder
When we open these pages in visual studio we will see WPF elements in it so this is xaml with base as FixedPage. All the shapes are rendered by Path. The text that XPS uses is Glyphs which derives from shape and it helps us define how the text looks like by using shapes. Glyph is a much lower level way of handling text than a text block. You should know that XPS does not use all the elements of xaml but only a limited set as all the systems running xps might not be running .NET
XPS Page in XAML
The font is specified as a file in a relative URI in the resources dictionary. These have scrambled names. The resources folder also has all the bitmaps in use as well. There are generally the Bitmaps of the text for which the licensing is not available for distribution.
WPF XPS Fonts
The directory structure shown below is just for the user’s convenience.
WPF XPS Directory Structure
We should look at the .rels file to see the entry points into the package. It contains a series of relationships which are the links identified by the URI. The document that we have has 3 relationships.
- The namespace
- The entry point called FixedDocumentSequence.fdseq. This contains the links to all the pages. These roots types are all reflecte din the API
- Identifies the metadata i.e. thumbnail
WPF XPS .rels
XpsDocumentWriter
The class used for creating the XPS document is the same as the class for printing in WPF. It is XpsDocumentWriter. The target for the writer (XPS file or Printer) depends on from where we got the writer handle in the first place.
If we get the writer from the PrintQueue then the writer will write to the printer.
XpsDocumentWriter
If the writer from XpSDocumnet’s CreateXpsWriterWriter method then the output will go to xps file on disk.
XpsDocumentWriter
Let’s see this in action. Add the following code to the click handler of a button.
XpsDocumentWriter
Now when we run the application then we ask the PrintQueue to give us a XpsDocumentWriter and to get that we just pass a null printable area. After that we will get an option to choose the printer as we have not already done that.
XpsDocumentWriter
We select the actual printer and click on print. The PrintDocumentImageableArea contains the dimensions of the paper we are printing on. The Media Size height and width tells us the size of the paper. As you might know that we cannot print all the way to the end of the paper as it might put ink to the printer edges. So we have a margin specified via OriginalHeight and OriginalWidth. The units are in DPI i.e. 1/96th of an inch.
XpsDocumentWriter
Then we return back to the application and the code for creating a textblock is executed. This will be the visual tree that we will be printing. As you can see in the code we have assigned the top and left margin the same as to where the paper can print.
Next we need to create the layout. This would have been automatically if our visual tree was hosted inside a window but as there is no window we need to do it. So measure, arrange and update the layout.
Then we print the document.
If we use the Microsoft XPS Document Writer as the printer
XpsDocumentWriter
Then we will have the OriginalHeight and OriginalWidth as 0 in the PrintDocumentImageableArea.
XpsDocumentWriter
Now when we reach the write method we get to choose the save location of the xps document.
XpsDocumentWriter
The XPS file looks something like this. As the virtual printer told us that there is no margin the text is next to the edge.
XpsDocumentWriter
Printing Multiple Pages
We cannot call the Write method twice as it will throw an error. So we need to follow a different technique to print multiple pages. We need to use the SerializerWriteCollater to print multiple pages. We call the BeginBatchWrite to start the print spooling process and then we will call EndBatchWrite after the finishing the print job. We can use the code below to see multiple pages printing works.
WPF Printing Multiple Pages
The XPS document will contain 10 pages.
WPF Printing Multiple Pages
Document Paginator
In the previous section we how we can print Visual Trees. The overloaded write method of the XpsDocumentWriter takes a DocumentPaginator as input. DocumentPaginator is an object that knows how to display content in pages. FlowDocument, FlowDocumentPageViewer, FixedDocument uses this IDocumentPaginatorSource.
WPF Document Paginator
Multi Page – XPS
We can get a detailed control over the print document by handling the XPS object itself. The write method has 3 overloads that accept
- FixedPage – For printing a single page.
- FixedDocument – For printing single document
- FixedDocumentSequence. – For printing Multi document print job
WPF Multi Page XPS
Let’s see this in action. In the code below we can see that we have added a FixedDocument that contains Fixed Pages. The FixedPage has a children collection that will contain as many items as we like and we have positioned them like we position children in a canvas. Then we add the page to the FixedDocument. We need to provide the PageContent that will go in to the PageDocument sequence and this will contain the links to the actual child pages itself. So we build the Page content and then point that at the child FixedPage object itself. IAddChild is how we add children to elements.
WPF Multi Page XPS
And the output looks something like below.
WPF Multi Page XPS
Asynchronous Printing
All the methods offered by the XpsDocumentWriter are also available in the Async form like WriteAsync. These perform the printing process using the User Interface’s thread idle time. The progress change and Progress complted eventes are raised for tracking the progress of the print process. It also provides a CancelAsync method that cancels the printing. For all this to work we need to be running in WPF User Interface thread that’s running a message loop as this requires the idle time.
PrintTicket
The PrintTicket class represents some of the common features like Collation, orientation, resolution, quality, etc. these are the printer properties that are available when will click on printer properties button in the print dialog. It is also extensible so that the printer specific settings can be attached to the PrintTicket.
PrintTickets can have different TicketScopes like document, print job or a page.
We can get the default print settings of the printer from the PrintQueue object of the printer. There are two properties:
- UserPrintTicket – Contains user defaults
- DefaultPrintTicket – Contains system wide defaults
As you might expect that all print cannot do everything so we can make use of PrintCapabilities class to get the Valid PrintTicket options for specific printer and the printer specific custom options.
PrintDialog
In the previous section we saw that the PrintDialog was automatically popped by WPF when the printer selection was required. But we can do this using the code as well. And me will need to do it via code at places where we need to find out the capabilities of the printer, etc. And then can set or get various printing options.
WPF PrintDialog
Queues and Servers
The classes PrintDialog, PrintTicket and PrintQueue (It is specific to a printer) are part of System.Printing namespace introduced by .NET 3.0. We can use this API to configure remote print server or PrintQueue. It also provides configuration options, discovery and monitoring. PrintServer represents a particular class with printers attached and can provide PrintQueue for each of the connected printers.
Any questions, comments and feedback is most welcome.
The Code for this post can be found here.
