Click or drag to resize
CanvasPrintDocument Class
The main object that enables printing of Win2D content. To use, pass a CanvasPrintDocument to PrintTaskSourceRequestedArgs.SetSource.
Inheritance Hierarchy
SystemObject
  Microsoft.Graphics.Canvas.PrintingCanvasPrintDocument

Namespace:  Microsoft.Graphics.Canvas.Printing
Assembly:  Microsoft.Graphics.Canvas (in Microsoft.Graphics.Canvas.dll) Version: 0.0.0.0
Syntax
C#
Copy
public sealed class CanvasPrintDocument : IDisposable, 
	ICanvasResourceCreator, IPrintDocumentSource

The CanvasPrintDocument type exposes the following members.

Constructors
  NameDescription
Public methodCanvasPrintDocument
Initializes a new instance of the CanvasPrintDocument class using the current shared device.
Public methodCanvasPrintDocument(CanvasDevice)
Initializes a new instance of the CanvasPrintDocument class.
Top
Properties
  NameDescription
Public propertyDevice
Gets the CanvasDevice that this CanvasPrintDocument uses for drawing.
Top
Methods
  NameDescription
Public methodDispose
Releases all resources used by the CanvasPrintDocument.
Public methodInvalidatePreview
Tells the print preview dialog that it needs to request the print preview to be regenerated.
Public methodSetIntermediatePageCount
Sets an intermediate page count, as used by the print preview dialog.
Public methodSetPageCount
Sets the final page count, as used by the print preview dialog.
Top
Events
  NameDescription
Public eventPreview
Hook this event to draw print previews.
Public eventPrint
Hook this event to print the document.
Public eventPrintTaskOptionsChanged
Hook this event to be notified when the print options have changed.
Top
Remarks

CanvasPrintDocument enables printing from Win2D by providing an object that can be set as a print document source. The following code example shows how to register events on PrintManager to get to the point where a CanvasPrintDocument can be set as the source:

Copy
CanvasPrintDocument printDocument;

async void OnPrintClicked(object sender, RoutedEventArgs e)
{
    if (printDocument != null)
    {
        // Dispose any previously created CanvasPrintDocument
        // (see the CanvasPrintDocument.Dispose documentation for more information).
        printDocument.Dispose();
    }

    printDocument = new CanvasPrintDocument();

    var printManager = PrintManager.GetForCurrentView();
    printManager.PrintTaskRequested += OnPrintTaskRequested;
    await PrintManager.ShowPrintUIAsync();
    printManager.PrintTaskRequested -= OnPrintTaskRequested;
}

void OnPrintTaskRequested(PrintManager sender, PrintTaskRequestedEventArgs args)
{
    args.Request.CreatePrintTask("Job Name", (a) =>
    {
        a.SetSource(printDocument);
    });
}

void Page_Unloaded(object sender, RoutedEventArgs args)
{
    if (printDocument != null)
    {
        printDocument.Dispose();
        printDocument = null;
    }
}

CanvasPrintDocument must be created on the UI thread. Once the object is created, methods may be called from any thread. This allows any heavy-lifting printing work to be performed on a background thread. Any events raised by CanvasPrintDocument are raised on the same thread it was created on.

CanvasPrintDocument supports print preview and printing via events.

While the print preview dialog is displayed, the PrintTaskOptionsChanged will be called when the user changes an option that may cause the preview to need redrawing. For example, they may pick a different printer or page size. The Preview event is raised to request that a preview image be drawn.

When the user chooses to print the Print event is raised. The application can then draw each page in turn using CreateDrawingSession

The following example shows how to configure a CanvasPrintDocument to preview and print some text:

Copy
CanvasPrintDocument printDocument;

CanvasPrintDocument MakePrintDocument()
{
    if (printDocument != null)
    {
        // Dispose any previously created CanvasPrintDocument
        // (see the CanvasPrintDocument.Dispose documentation for more information).
        printDocument.Dispose();
    }

    printDocument = new CanvasPrintDocument();

    printDocument.Preview += (sender, args) =>
    {
        sender.SetPageCount(1);
        PrintPage(args.DrawingSession, args.PrintTaskOptions.GetPageDescription(1));
    };

    printDocument.Print += (sender, args) =>
    {
        using (var ds = args.CreateDrawingSession())
        {
            PrintPage(ds, args.PrintTaskOptions.GetPageDescription(1));
        }
    }
}

void PrintPage(CanvasDrawingSession ds, PrintPageDescription desc)
{
    var pageSize = desc.PageSize;
    var center = pageSize.ToVector2() / 2;
    ds.DrawText("Win2D", center, Colors.Black, new CanvasTextFormat()
    {
        VerticalAlignment = CanvasVerticalAlignment.Center,
        HorizontalAlignment = CanvasHorizontalAlignment.Center
    });
}

void Page_Unloaded(object sender, RoutedEventArgs args)
{
    if (printDocument != null)
    {
        printDocument.Dispose();
        printDocument = null;
    }
}

Throughout the printing API, page numbers start at 1. So the first page is page 1 (not page 0, as might be expected by C++ and C# developers).

See Also