Manipulating print tickets | Java

Introduction to Print Schema

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

The Print Schema is a hierarchical XML-based schema used to organize and describe printer or print job properties. It comprises two main parts: 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 set of XML element types in a hierarchical structure and specifies how these element types can be used together.

The Print Schema technology, known as PrintTicket, is built using the Print Schema Keywords as specified by the Print Schema Framework. The Print Schema Specification allows for schema extensions by third parties, enabling Print Schema users to go beyond the Property, Feature, Option, or ParameterInit instances that are defined by the Print Schema Keywords. Third-party element instances can be added to those 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.

Support for Print Ticket in Aspose.Page for Java

The Aspose.Page API for Java contains a set of classes that encapsulate elements defined by the Print Schema Keywords. Due to the significant number of these classes, in this article, we will only discuss a few most common techniques for manipulating print tickets in an XPS document using the Aspose.Page API. We will start by discussing the instantiation of each feature class we want to include in the print ticket, followed by a demonstration of how to incorporate these features into a print ticket.

Specifying input bin

The JobInputBin feature identifies 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 should include only one of the three features. All of them are derived from the InputBin class and have constructors with the same signature, so we will use JobInputBin for demonstration purposes.

The line of Java code

new JobInputBin(InputBin.InputBinOption.AutoSelect);

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

The InputBin.InputBinOption class defines static fields that serve as a base for various input bin options. Each option can contain additional properties like InputBin.BinType, InputBin.FeedDirection, InputBin.FeedFace, InputBin.FeedType, InputBin.MediaCapacity, InputBin.MediaPath, InputBin.MediaSizeAutoSense, InputBin.MediaTypeAutoSense, and InputBin.MediaSheetCapacity. To specify these properties, you should 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)));

To view the full list of available property values, consult the Print Schema Specification and the relevant section of the Aspose.Page API reference.

Specifying 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 may include the OutputBin.BinType and OutputBin.MediaSheetCapacity properties. Therefore, a JobOutputBin feature can be instantiated as follows:

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

Specifying page orientation

The PageOrientation feature defines the orientation of the physical media sheet. The list of available options can be found in the PageOrientation.PageOrientationOption class section of the API reference. Here is an example of how to produce an instance of this feature:

new PageOrientation(PageOrientation.PageOrientationOption.Landscape);

Specifying duplex mode for the output

The JobDuplexAllDocumentsContiguously feature describes the duplex characteristics of the output. The duplex feature enables printing on both sides of the media, with all documents in the job being duplexed together contiguously. JobDuplexAllDocumentsContiguously and DocumentDuplex are mutually exclusive, and it is up to the driver to determine how constraints are handled between these keywords. The latter keyword means that each document in the job is duplexed separately.

There are three options available 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 indicate 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 prefer one-sided printing, you can include the following feature in the print ticket:

new JobDuplexAllDocumentsContiguously(Duplex.DuplexOption.OneSided);

Specifying color settings for the output

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

If, for example, you want your color printer to print an XPS file in grayscale, you can include the following feature in the print ticket:

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

Working with print tickets of different levels

If you are working with an XPS file that was created by someone else, you might need to adjust its print ticket in case it is present. To retrieve a job-level print ticket, you can simply call the getJobPrintTicket() method of the XpsDocument object:

JobPrintTicket pt = document.getJobPrintTicket();

To retrieve a print ticket for a particular document within 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 retrieve a print ticket for a particular page within 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.

Once you have retrieved a print ticket instance and it is not equal to 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 suitable for the print ticket of the specific 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 prefer not to modify existing print tickets but instead assign an entirely new instance, as is the case with a new XPS file, then for the job-level print ticket, you should use the setJobPrintTicket() method:

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

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

If you want to assign a print ticket for a particular document within the XPS file, use the setDocumentPrintTicket() method:

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

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

Finally, in case you want to assign a print ticket for a particular 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 suitable for the page-level print ticket.

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

// For complete examples and data files, please go to https://github.com/aspose-page/Aspose.Page-for-Java
// The path to the documents directory.
String dataDir = Utils.getDataDir();

// Create new XPS document
final XpsDocument document = new XpsDocument();
try {
    // Set a custom job-level print ticket
    document.setJobPrintTicket(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(dataDir + "output1.xps");
} finally {
  if (document != null)
    document.close();
}