How to add custom settings to the print preview UI (XAML)

  • Article

This tutorial shows how to add a custom, app-specific print option to the print preview UI.

In this tutorial, we add to the print preview UI a custom print option called Pictures that has these options.

Option name Action

Pictures and text

Print the text and images from the app's screen.

Pictures only

Print only the pictures from the app's screen.

Text only

Print only the text from the app's screen.

 

Objective: Add new print capability to an application using custom options in the print preview UI.

Prerequisites

  • You must be familiar with C#, C++, or Visual Basic, XAML, events, and event handling.
  • You must have Microsoft Visual Studio installed.
  • You must have a printer installed.
  • You must have a Windows Store app using C++, C#, or Visual Basic to which you want to add a custom print option. 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 you don't have such an app, review Quickstart: Printing from your app to learn how to add basic Windows printing support to your app.

Instructions

1. Open your app in Visual Studio

The procedure described in this tutorial refers to the PrintSample app from the Print Sample sample app. If you are adding a print button to your own app, open your app in Visual Studio instead of the Print Sample sample app.

  1. Open the Windows Store app print sample and download the C# example to your computer.
  2. 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.
  3. Select the PrintSample solution file, and click Open.

2. Build and test the app

  1. 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.
  2. Click Debug > Start Without Debugging.
  3. Verify that, after a few seconds, the screen displays the Print JS Sample app.
  4. If the app runs without error, return to Visual Studio, and then click Debug > Stop Debugging.

3. Add the new option to the print preview UI

This step creates a new print option, defines a list of values that the option supports, and then adds the option to the print preview UI.

  1. Modify the PrintTaskRequested event handler to add the code to get a PrintTaskOptionDetails object.

    PrintTaskOptionDetails^ printDetailedOptions = PrintTaskOptionDetails::GetFromPrintTaskOptions(printTask->Options);

    PrintTaskOptionDetails printDetailedOptions = PrintTaskOptionDetails.GetFromPrintTaskOptions(printTask.Options);

    Dim printDetailedOptions As PrintTaskOptionDetails = PrintTaskOptionDetails.GetFromPrintTaskOptions(printTask.Options)

  2. Create the new print option and initialize the list of option values.

    // Create a new list option

PrintCustomItemListOptionDetails^ pageFormat = printDetailedOptions->CreateItemListOption(L"PageContent", L"Pictures");
pageFormat->AddItem(L"PicturesText", L"Pictures and text");
pageFormat->AddItem(L"PicturesOnly", L"Pictures only");
pageFormat->AddItem(L"TextOnly", L"Text only");

    // Create a new list option

PrintCustomItemListOptionDetails pageFormat = printDetailedOptions.CreateItemListOption("PageContent", "Pictures");
pageFormat.AddItem("PicturesText", "Pictures and text");
pageFormat.AddItem("PicturesOnly", "Pictures only");
pageFormat.AddItem("TextOnly", "Text only");

    ' Create a new list option

Dim pageFormat As PrintCustomItemListOptionDetails = printDetailedOptions.CreateItemListOption("PageContent", "Pictures")
pageFormat.AddItem("PicturesText", "Pictures and text")
pageFormat.AddItem("PicturesOnly", "Pictures only")
pageFormat.AddItem("TextOnly", "Text only")

  3. Clear the list of options that are shown in the print preview UI and add the options that you want to display when the user wants to print from the app.

    Note  The options appear in the print preview UI in the same order they are appended, with the first option shown at the top of the window.

     

    // 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
displayedOptions->Clear();

displayedOptions->Append(StandardPrintTaskOptions::Copies);
displayedOptions->Append(StandardPrintTaskOptions::Orientation);
displayedOptions->Append(StandardPrintTaskOptions::ColorMode);

    // 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
displayedOptions.Clear();

displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.Copies);
displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.Orientation);
displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.ColorMode);

    ' 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
displayedOptions.Clear()

displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.Copies)
displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.Orientation)
displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.ColorMode)

  4. Add your custom print option and assign the event handler.

    In this example, the custom option is appended last so that it appears at the bottom of the list of options. However, you could put it anywhere in the list; custom print options don't need to be added last.

    Windows printing calls this event handler whenever the user changes the value of the custom option.

    // Add the custom option to the option list
displayedOptions->Append(L"PageContent");

printDetailedOptions->OptionChanged += ref new TypedEventHandler<PrintTaskOptionDetails^, PrintTaskOptionChangedEventArgs^>(this, &ScenarioInput4::printDetailedOptions_OptionChanged);

    // Add the custom option to the option list
displayedOptions.Add("PageContent");

printDetailedOptions.OptionChanged += printDetailedOptions_OptionChanged;

    ' Add the custom option to the option list
displayedOptions.Add("PageContent")

AddHandler printDetailedOptions.OptionChanged, AddressOf printDetailedOptions_OptionChanged

4. Add the option change event handler

When the user changes the selected option in your custom option, you'll update the print preview image.

This implementation from Scenario4.htm of the PrintSample sample app calls the invalidatePreview method to redraw the image in the print preview UI.

void ScenarioInput4::printDetailedOptions_OptionChanged(PrintTaskOptionDetails^ sender, PrintTaskOptionChangedEventArgs^ args)
{
    // Listen for PageContent changes
    String^ optionId = safe_cast<String^>(args->OptionId);

    if (optionId != nullptr && optionId == L"PageContent")
    {
        RefreshPreview();
    }
}

async void printDetailedOptions_OptionChanged(PrintTaskOptionDetails sender, PrintTaskOptionChangedEventArgs args)
{
    // Listen for PageContent changes
    string optionId = args.OptionId as string;
    if (string.IsNullOrEmpty(optionId))
        return;

    if (optionId == "PageContent")
    {
        await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal,
                               () =>
                               {
                                   printDocument.InvalidatePreview();
                               });
    }
}

Private Sub printDetailedOptions_OptionChanged(sender As PrintTaskOptionDetails, args As PrintTaskOptionChangedEventArgs)
    ' Listen for PageContent changes
    Dim optionId As String = TryCast(args.OptionId, String)
    If String.IsNullOrEmpty(optionId) Then
        Exit Sub
    End If

    If optionId = "PageContent" Then
        Dim ignored = Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, Sub()
                                                                                             printDocument.InvalidatePreview()
                                                                                         End Sub)
    End If
End Sub

Summary and next steps

For the complete source code for this and other Windows Store app printing scenarios, see the Print Sample sample app.

Printing