Working with print tickets | .NET

Print Schema

XPS documents and the XPS Object Model can use the print ticket objects, which are described in the Print Schema Specification, to specify the printing preferences of a document to printers and viewing applications.

The Print Schema is an XML-based schema that is hierarchically structured and used to organize and describe the properties of a printer or print job. It consists of two main components: the Print Schema Keywords and the Print Schema Framework. The Print Schema Keywords are element instances that describe printer attributes and print job formatting intent, while the Print Schema Framework defines a collection of XML element types in a hierarchical structure and specifies how these element types can be used together.

The Print Schema technology, called PrintTicket, is built using the Print Schema Keywords as specified by the Print Schema Framework. The Print Schema Specification supports schema extensions by third parties, so that Print Schema users are not restricted to the Property, Feature, Option, or ParameterInit instances that are defined by the Print Schema Keywords. Third-party element instances can be added to element instances that are defined by the Print Schema Keywords; however, private, third-party Property instances must belong to a namespace that is clearly associated with the third party that created the namespace.

The Print Ticket support in Aspose.Page for .NET

The Aspose.Page API for .NET includes a set of classes that encapsulate elements defined by the Print Schema Keywords. Since the number of these classes is quite large, this article covers only a few most common techniques for manipulating print tickets in an XPS document using the Aspose.Page API. We will first discuss the instantiation of every feature class that we want to include in the print ticket. Then, we will see how to include these features in a print ticket.

How to specify input bin

The JobInputBin feature describes the installed input bin in a device or the full list of supported bins for a device. It allows specification of input bin on a per job basis. There are also the DocumentInputBin and PageInputBin features that allow specification of input bin on a per document and per page basis, respectively. Any Print Ticket document is supposed to include only one of the three. All of them inherit from the InputBin class and have constructors with the same signature, so we will use JobInputBin for demonstration purposes.

The following code

new JobInputBin(InputBin.InputBinOption.AutoSelect);

creates a feature for a job print ticket that instructs a printing device to automatically choose the best option based on configuration.

The InputBin.InputBinOption class defines static fields, each of which serves as a base for various input bin options. Each option can contain additional properties such as InputBin.BinType, InputBin.FeedDirection, InputBin.FeedFace, InputBin.FeedType, InputBin.MediaCapacity, InputBin.MediaPath, InputBin.MediaSizeAutoSense, InputBin.MediaTypeAutoSense, and InputBin.MediaSheetCapacity. To specify them, you should first clone the base property and then call the Add() method with a list of desired properties:

new JobInputBin(InputBin.InputBinOption.Manual.Clone().Add(
    InputBin.FeedFace.FaceDown, InputBin.FeedDirection.LongEdgeFirst, new InputBin.MediaSheetCapacity(100)));

For the full list of available property values, refer to the Print Schema Specification and the relevant section of the Aspose.Page API reference.

How to specify output bin

The JobOutputBin feature describes the installed output bin in a device or the full list of supported bins for a device. The JobOutputBin, DocumentOutputBin and PageOutputBin keywords are mutually exclusive; only one should be specified in a single print ticket.

Each option can contain the following properties: OutputBin.BinType and OutputBin.MediaSheetCapacity. Thus, a JobOutputBin feature can be constructed as follows:

new JobOutputBin(new OutputBin.OutputBinOption(OutputBin.BinType.Sorter),
    new OutputBin.OutputBinOption(OutputBin.BinType.Stacker, new OutputBin.MediaSheetCapacity(100)));

How to specify page orientation

The PageOrientation feature describes the orientation of the physical media sheet. The available options are listed in the PageOrientation.PageOrientationOption class section of the API reference. Below is an example of how to construct the feature:

new PageOrientation(PageOrientation.PageOrientationOption.Landscape);

How to specify duplex mode for the output

The JobDuplexAllDocumentsContiguously feature describes the duplex characteristics of the output. The duplex feature allows for printing on both sides of the media. All documents in the job are duplexed together contiguously.

JobDuplexAllDocumentsContiguously and DocumentDuplex are mutually exclusive. It is up to the driver to determine constraint handling between these keywords. The latter keyword means that each document in the job is duplexed separately.

There are three options for this feature - OneSided, TwoSidedLongEdge, and TwoSidedShortEdge. The first one has no properties, and the other two are parametrized with the Duplex.DuplexMode.

For example, if you want to specify two-sided printing for your XPS file such that the page is flipped parallel to the MediaSizeHeight, you can do so as follows:

new JobDuplexAllDocumentsContiguously(Duplex.DuplexOption.TwoSidedLongEdge(Duplex.DuplexMode.Automatic));

If you do not want your file to be duplexed, you can add the following feature to the print ticket:

new JobDuplexAllDocumentsContiguously(Duplex.DuplexOption.OneSided);

How to specify color settings for the output

The PageOutputColor feature describes the characteristics of the color settings for the output. There are three options for this feature - Color, Grayscale, and Monochrome, each of which has two integer properties - DeviceBitsPerPixel and DriverBitsPerPixel.

For example, if you want your color printer to print an XPS file in grayscale, you can add the following feature to the print ticket:

new PageOutputColor(PageOutputColor.PageOutputColorOption.Grayscale(0, 8));

How to work with print tickets of different levels

If you are working with an XPS file that was created by someone else, you may want to modify its print ticket in case it is present. To obtain a job-level print ticket, you can simply use the JobPrintTicket property of the XpsDocument object:

JobPrintTicket pt = document.JobPrintTicket;

To obtain a print ticket for a specific document in the XPS file, you should use the GetDocumentPrintTicket() method:

DocumentPrintTicket pt = document.GetDocumentPrintTicket(<n>);

where <n> is the number of the document within the XPS file.

To obtain a print ticket for a specific page in the XPS file, you should use the GetPagePrintTicket() method:

PagePrintTicket pt = document.GetPagePrintTicket(<m>, <n>);

where <m> is the number of the document within the XPS file, and <n> is the number of the page within the m-th document.

After obtaining a print ticket instance, if it is not null, you can add your features constructed as shown in the sections above:

pt.Add(<features>);

where <features> is a variable-length array of features appropriate for the print ticket of the particular level. If the old print ticket already had some of the features that you are trying to add, they will be overwritten by the new instances.

If you don’t want to modify existing print tickets, but rather assign an entirely new instance (which is also the case of a new XPS file), then for the job-level print ticket, you should use the JobPrintTicket property again:

document.JobPrintTicket = new JobPrintTicket(<features>);

where <features> is a variable-length array of features appropriate for the job print ticket.

In case you want to assign a print ticket for a specific document within the XPS file, the SetDocumentPrintTicket() method should be used:

document.SetDocumentPrintTicket(<n>, new DocumentPrintTicket(<features>));

where <n> is the number of the document within the XPS file, and <features> is a variable-length array of features appropriate for the document-level print ticket.

Finally, if you want to assign a print ticket for a specific page within the XPS file, you should use the SetPagePrintTicket() method:

document.SetPagePrintTicket(<m>, <n>, new PagePrintTicket(<features>));

where <m> is the number of the document within the XPS file, <n> is the number of the page within the m-th document, and <features> is a variable-length array of features appropriate for the page-level print ticket.

Below is the complete code example for the job-level print ticket from the Aspose.Page for .NET example project:

// For complete examples and data files, please go to https://github.com/aspose-page/Aspose.Page-for-.NET
// The path to the documents directory.
string dir = RunExamples.GetDataDir_WorkingWithPrintTickets();

// Create new XPS document
using (XpsDocument document = new XpsDocument())
{
    // Set a custom job-level print ticket
    document.JobPrintTicket = new JobPrintTicket(
        // Specify input bin.
        new JobInputBin(InputBin.InputBinOption.Manual.Clone().Add(
            InputBin.FeedFace.FaceDown, InputBin.FeedDirection.LongEdgeFirst, new InputBin.MediaSheetCapacity(100))),
        // Specify output bin.
        new JobOutputBin(new OutputBin.OutputBinOption(OutputBin.BinType.Sorter),
            new OutputBin.OutputBinOption(OutputBin.BinType.Stacker, new OutputBin.MediaSheetCapacity(100))),
        // Specify page orientation.
        new PageOrientation(PageOrientation.PageOrientationOption.Landscape),
        // Specify duplex mode fof the output.
        new JobDuplexAllDocumentsContiguously(Duplex.DuplexOption.TwoSidedLongEdge(Duplex.DuplexMode.Automatic)),
        // Specify the color settings for the output.
        new PageOutputColor(PageOutputColor.PageOutputColorOption.Grayscale(0, 8)));

    // Save the document with the custom job-level print ticket.
    document.Save(dir + "output1.xps");
}