Print​Task Print​Task Print​Task Class

Definition

Represents a printing operation including the content to be printed, as well as providing access to information describing how the content is to be printed.

public sealed class PrintTask : IPrintTask, IPrintTask2, IPrintTaskTargetDeviceSupportpublic sealed class PrintTask : IPrintTask, IPrintTask2, IPrintTaskTargetDeviceSupportPublic NotInheritable Class PrintTask Implements IPrintTask, IPrintTask2, IPrintTaskTargetDeviceSupport
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The PrintTask object represents a printing operation for Windows Store app. The app is responsible for creating a PrintTask that is requested via the PrintTaskRequested event on the PrintManager object. To create PrintTask you must provide the name for the task and a PrintTaskSourceRequestedHandler delegate which is called when the user is ready to begin printing.

If the user decides not to print the task, the task may be completed without ever requesting the document source.

PrintTask contains a reference, in the form of a property, to the Print Document Source provided by the app. The PrintTask object must support the IPrintDocumentSource interface and must provide a pointer to this interface via the Source property.

In addition PrintTask contains an Options property which holds a reference to the PrintTaskOptions object. The PrintTaskOptions object provides access to details about the desired format of the printed content. PrintTaskOptions also provides methods which allow aspects of the print user experience to be modified. For example, PrintTaskOptions allows the app to define which of the supported options appear on the initial page of the print experience.

A print task goes through a specific set of states after its creation, and these changes in state can be used by an app to provide feedback to the user. Most of the state transitions are represented in the events that are raised by PrintTask. The print task is created in response to the PrintTaskRequested event on the PrintManager using the CreatePrintTask method on the PrintTaskRequest object. At this point the print task cannot be printed, since the content to print has not yet been provided. Typically a PrintTaskRequested event is raised when the user clicks on the Devices charm or an application initiates printing via the ShowPrintUIAsync method on the PrintManager.

Once the system determines that the task will be printed, the PrintTaskSourceRequestedHandler delegate is called to actually retrieve a reference to the Document Source object. At this point PrintTask is fully initialized. If the user decides not to complete the printing represented by the PrintTask object, the completion event is raised with a completion type of abandoned.

Upon initialization the printing user experience is responsible for helping the user select the different attributes, such as paper size or duplex, for the printed content. When the print window initialization is almost complete, PrintTask raises the Previewing event. This is when the user is now able to manipulate the contents of the PrintTaskOptions object via the print window. The user may change the values of the settings at any time during the Preview stage, and this must be taken into consideration the next time an app paginates the content. The PrintTaskOptions object provides basic functionality for retrieving the values of the print settings. For more advanced control of the print options, see PrintTaskOptionDetails. Again the user may cancel this operation which will result in a completion event being raised with a completion type of cancelled.

When the user chooses to actually initiate printing by pressing Print in the print window, for example, the print task transitions from Previewing to the Submitting state, and the Submitting event is raised. The print document source is then passed a MakeDocument command and the process of submitting pages to the print subsystem begins. While pages are being submitted, the Progressing event is raised. An app may choose to use the information in the progressing event to let the user know how much content remains to be printed. Once the process of submitting the document to the print subsystem is complete, PrintTask raises the Completion event. This event indicates whether the job was submitted successfully, canceled, or failed during the submission process.

Here is a JavaScript code snippet that shows how to indicate the order in which the default print settings should be displayed:

    // Print event handler for printing via the PrintManager API.
    // printEvent contains the print task request object
    function onPrintTaskRequested(printEvent) {    
        var printTask = printEvent.request.createPrintTask("Print Sample", function (args) {
            args.setSource(MSApp.getHtmlPrintDocumentSource(document));
        });

        // Enumerate the printer settings you want to show.
        // They appear in the print window in the same order
        // that you list them here
        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);

        //You may even preset the values on a printer setting
        printTask.options.mediaSize = Windows.Graphics.Printing.PrintMediaSize.northAmericaLegal;
    };

To see the complete listing for this, and other printing scenarios using PrintTask, see Printing.

Properties

Is3DManufacturingTargetEnabled Is3DManufacturingTargetEnabled Is3DManufacturingTargetEnabled

Gets or sets a value that indicates whether the PrintTask supports 3D manufacturing devices, like a 3D printer.

public bool Is3DManufacturingTargetEnabled { get; set; }public bool Is3DManufacturingTargetEnabled { get; set; }Public ReadWrite Property Is3DManufacturingTargetEnabled As bool
Value
bool bool bool

True, if 3D manufacturing devices are supported.

Attributes

Remarks

This property works together with IsPrinterTargetEnabled to determine which devices are enumerated when the user extends the print charm. When IsPrinterTargetEnabled is true, the print charm displays conventional printing devices, like 2D printers. When Is3DManufacturingTargetEnabled is true, the print charm displays 3D devices like 3D printers. When both IsPrinterTargetEnabled and Is3DManufacturingTargetEnabled are true, the print charm displays both 2D printers and 3D printers.

By default, IsPrinterTargetEnabled is true and Is3DManufacturingTargetEnabled is false.

Note

Windows Store app that support 3D printing in Windows 8.1 must set IsPrinterTargetEnabled to false and Is3DManufacturingTargetEnabled to true in order to enumerate only 3D printers in the print charm.

See Also

IsPreviewEnabled IsPreviewEnabled IsPreviewEnabled

Gets or sets a value that indicates whether the PrintTask will show a print preview.

public bool IsPreviewEnabled { get; set; }public bool IsPreviewEnabled { get; set; }Public ReadWrite Property IsPreviewEnabled As bool
Value
bool bool bool

True, if print preview is enabled.

Attributes

Remarks

In some situations, displaying the print preview will take too much time and disrupt the user experience of a Universal Windows app. For this reason, the developer may wish to disable the print preview feature in favor of a smoother control flow.

By default, isPreviewEnabled is true. Windows Store app that are meant to print in the background must set isPreviewEnabled to false.

IsPrinterTargetEnabled IsPrinterTargetEnabled IsPrinterTargetEnabled

Gets or sets a value indicating whether the PrintTask supports printer targets.

public bool IsPrinterTargetEnabled { get; set; }public bool IsPrinterTargetEnabled { get; set; }Public ReadWrite Property IsPrinterTargetEnabled As bool
Value
bool bool bool

True if the PrintTask supports printer targets.

Attributes

Remarks

This property works together with Is3DManufacturingTargetEnabled to determine which devices are enumerated when the user extends the print charm. When IsPrinterTargetEnabled is true, the print charm displays conventional printing devices, like 2D printers. When Is3DManufacturingTargetEnabled is true, the print charm displays 3D devices like 3D printers. When both IsPrinterTargetEnabled and Is3DManufacturingTargetEnabled are true, the print charm displays both 2D printers and 3D printers.

By default, IsPrinterTargetEnabled is true and Is3DManufacturingTargetEnabled is false.

Windows Store app that support 2D printing in Windows 8 are not required to make a change in Windows 8.1 to add this property.

Options Options Options

Retrieves the PrintTaskOptions for the print task that defines how the content is to be formatted for printing.

public PrintTaskOptions Options { get; }public PrintTaskOptions Options { get; }Public ReadOnly Property Options As PrintTaskOptions
Value
PrintTaskOptions PrintTaskOptions PrintTaskOptions

The list of print task options.

Attributes

Remarks

An app can use PrintTaskOptions, for example, to determine the size of media on which the content is to be printed. PrintTaskOptions may also be used to customize the selection of options that are visible by default for the printing user experience.

Properties Properties Properties

Retrieves a set of properties associated with the PrintTask.

public DataPackagePropertySet Properties { get; }public DataPackagePropertySet Properties { get; }Public ReadOnly Property Properties As DataPackagePropertySet
Attributes

Remarks

As an example, the title of the print task that was provided when the print task was created is available as a property.

Source Source Source

Returns a pointer to the app-provided object that represents the content to be printed. This object must support the IPrintDocumentSource interface.

public IPrintDocumentSource Source { get; }public IPrintDocumentSource Source { get; }Public ReadOnly Property Source As IPrintDocumentSource
Attributes

Events

Completed Completed Completed

Raised when the print task is completed.

public event TypedEventHandler Completedpublic event TypedEventHandler CompletedPublic Event Completed
Attributes

Previewing Previewing Previewing

Raised when the print system initializes print preview mode.

public event TypedEventHandler Previewingpublic event TypedEventHandler PreviewingPublic Event Previewing
Attributes

Progressing Progressing Progressing

Raised to provide progress information about how much of the printed content has been submitted to the print subsystem for printing.

public event TypedEventHandler Progressingpublic event TypedEventHandler ProgressingPublic Event Progressing
Attributes

Submitting Submitting Submitting

Raised when a print task begins submitting content to the print subsystem to be printed.

public event TypedEventHandler Submittingpublic event TypedEventHandler SubmittingPublic Event Submitting
Attributes

See Also