PrintTask PrintTask PrintTask PrintTask Class

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.

Syntax

Declaration

public sealed class PrintTaskpublic sealed class PrintTaskPublic NotInheritable Class PrintTask

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(System.String,Windows.Graphics.Printing.PrintTaskSourceRequestedHandler) 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 summary

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

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

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

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

Retrieves a set of properties associated with the PrintTask.

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

Events summary

Raised when the print task is completed.

Raised when the print system initializes print preview mode.

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

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

Properties

  • Is3DManufacturingTargetEnabled
    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

    Property Value

    • bool
      bool
      bool
      bool

      True, if 3D manufacturing devices are supported.

    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.

  • IsPreviewEnabled
    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

    Property Value

    • bool
      bool
      bool
      bool

      True, if print preview is enabled.

    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
    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

    Property Value

    • bool
      bool
      bool
      bool

      True if the PrintTask supports printer targets.

    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
    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

    Property Value

    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
    Properties

    Retrieves a set of properties associated with the PrintTask.

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

    Property Value

    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
    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

    Property Value

Events

  • Completed
    Completed
    Completed
    Completed

    Raised when the print task is completed.

    public event TypedEventHandler Completedpublic event TypedEventHandler CompletedPublic Event Completed
  • Previewing
    Previewing
    Previewing
    Previewing

    Raised when the print system initializes print preview mode.

    public event TypedEventHandler Previewingpublic event TypedEventHandler PreviewingPublic Event Previewing
  • Progressing
    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
  • Submitting
    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

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.MuseAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute

Details

Assembly

Windows.Graphics.Printing.dll