How to add custom settings to the print preview UI (XAML)
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.
Pictures and text
Print the text and images from the app's screen.
Print only the pictures from the app's screen.
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.
- 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.
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.
- Open the Windows Store app print sample and download the C# 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 PrintSample solution file, and click Open.
- 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 then click Debug > Stop Debugging.
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.
Create the new print option and initialize the list of option values.
' 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")
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.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.Copies) displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.Orientation) displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.ColorMode)
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.
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.
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
For the complete source code for this and other Windows Store app printing scenarios, see the Print Sample sample app.