How to change standard options in the print preview UI (HTML)

Article
08/31/2015

This tutorial shows how to customize the print options shown in the print preview UI.

By default, the print preview UI shows the following options:

In addition to the preceding settings, Windows provides several other common printer options that you can add to the print preview UI. Here are those other common options.

binding	collation	duplex	holePunch
inputBin	mediaSize	mediaType	nUp
printQuality	staple

These options are defined in the standardPrintTaskOptions class. You can add to or remove options from the list of options displayed in the print preview UI. You can also change the order in which they appear, and set the default settings that are shown to the user.

However, the modifications that you make by using this method affect only the print preview UI. The user can always access all of the options that the printer supports by clicking More settings in the print preview UI.

Although your app can specify any print options to be displayed, only those that are supported by the selected printer are shown in the print preview UI. The print preview UI won't show options that the selected printer doesn't support.

Roadmap: How does this topic relate to others? See:

Roadmap for Windows Store apps using JavaScript

What you need to know

Technologies

Windows Runtime

Prerequisites

You must be familiar with HTML, JavaScript, Windows events, and event handling.
You must have Microsoft Visual Studio installed.
You must have a printer installed.
You must have a Windows Store app to which you want to add a print button. If you don't have your own app, you can download the Print Sample sample app and use that.
Your app must already support basic Windows printing. If it doesn't, review Quickstart: Printing from your app to learn how to add basic Windows printing support to your app.

Instructions

Step 1: Open your app in Visual Studio

The procedure described in this tutorial refers to the PrintSampleJS app from the Print Sample sample app. If you are customizing the print preview UI of your own app, open your app in Visual Studio instead of the Print Sample sample app.

Open the Print Sample sample app and download the JavaScript example to your computer.
In Visual Studio, click File > Open Project and go to the folder that contains the solution file of the sample app that you downloaded in the previous step.
Select the PrintSampleJS solution file and click Open.

Step 2: Build and test the app

Click Build > Build Solution to build the app you are working on. Make sure that there are no error messages in the Output pane at the bottom of the screen.
Click Debug > Start Without Debugging.
Verify that, after a few seconds, the screen displays the Print JS Sample app.
If the app runs without error, return to Visual Studio and click Debug > Stop Debugging.

Step 3: Define the print options to display

When the app's screen is loaded, it registers for the Print contract. Part of that registration includes defining the PrintTaskRequested event handler. The code to customize the options displayed in the print preview UI is added to the PrintTaskRequested event handler.

Modify the PrintTaskRequested event handler to include the printTask.options instructions that configure the print settings that you want to display in the print preview UI.

Find the PrintTaskRequested event handler in the app. In the Print Sample sample app, the basic PrintTaskRequested event handler looks like this example.

function onPrintTaskRequested(printEvent) {
    var printTask = printEvent.request.createPrintTask("Print Sample", function (args) {
        args.setSource(MSApp.getHtmlPrintDocumentSource(document));

        // Register the handler for print task completion event
        printTask.oncompleted = onPrintTaskCompleted;
    });
}

function onPrintTaskCompleted(printTaskCompletionEvent) {
    // Notify the user about the failure
    if (printTaskCompletionEvent.completion === Windows.Graphics.Printing.PrintTaskCompletion.failed) {
        WinJS.log && WinJS.log("Failed to print.", "sample", "error");
    }
}

Add the print options that you want to display in the print preview UI. The options will appear vertically in the print preview UI in the order that you add them. The first option that you add will be at the top and the rest will follow below in sequence.

Note This code is taken from scenario3.js of the Print Sample sample app. If you are adding this code to your app, assign the print options that you want to display to the user in the print preview UI.

Important Calling printTask.options.displayedOptions.clear() removes all of the print options from the print preview UI, leaving only the More settings link. Be sure to use the append method to specify the options that you want to show on the print preview UI.

function onPrintTaskRequested(printEvent) {
    var printTask = printEvent.request.createPrintTask("Print Sample", function (args) {
        args.setSource(MSApp.getHtmlPrintDocumentSource(document));

        // Choose the printer options to be shown.
        // The order in which the options are appended determines the order in which they appear in the UI
        printTask.options.displayedOptions.clear();
        printTask.options.displayedOptions.append(Windows.Graphics.Printing.StandardPrintTaskOptions.copies);
        printTask.options.displayedOptions.append(Windows.Graphics.Printing.StandardPrintTaskOptions.mediaSize);
        printTask.options.displayedOptions.append(Windows.Graphics.Printing.StandardPrintTaskOptions.orientation);
        printTask.options.displayedOptions.append(Windows.Graphics.Printing.StandardPrintTaskOptions.duplex);

        // Preset the default value of the printer option
        printTask.options.mediaSize = Windows.Graphics.Printing.PrintMediaSize.northAmericaLegal;

        // Register the handler for print task completion event
        printTask.oncompleted = onPrintTaskCompleted;
    });
}