How to change standard options in the print preview UI (XAML)
This tutorial shows how to customize the print options shown in the print preview UI.
By default, the print preview UI shows the following options:
| ColorMode | Copies | Orientation |
In addition to the preceding settings, Windows provides several other common printer options that you can add to the print preview UI. Here are those other common options.
| Binding | Collation | Duplex | HolePunch |
| InputBin | MediaSize | MediaType | NUp |
| PrintQuality | Staple |
These options are defined in the StandardPrintTaskOptions class. You can add to or remove options from the list of options displayed in the print preview UI. You can also change the order in which they appear, and set the default settings that are shown to the user.
However, the modifications that you make by using this method affect only the print preview UI. The user can always access all of the options that the printer supports by tapping More settings in the print preview UI.
Although your app can specify any print options to be displayed, only those that are supported by the selected printer are shown in the print preview UI. The print UI won't show options that the selected printer doesn't support.
Objective: Customize the print options shown 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 change the print options. If you don't have your own app, you can download the PrintSample 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 PrintSample sample app. If you are adding a print button to your own app, open your app in Visual Studio instead of the PrintSample 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.
2. Build and test the app
- 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 click Debug > Stop Debugging.
3. Define the print options to display
When the app's screen is loaded, it registers for the Print contract. Part of that registration includes defining the PrintTaskRequested event handler. The code to customize the options displayed in the print preview UI is added to the PrintTaskRequested event handler.
Modify the PrintTaskRequested event handler to include the printTask.options instructions that configure the print settings that you want to display in the print preview UI.
For the screen in your app for which you want to show a customized list of print options, override the PrintTaskRequested event handler in the base class to include code that specifies the options to display when the screen is printed.
Note This example is taken from ScenarioInput3.xaml.cs of the Print Sample sample app. If you are adding this code to your app, assign the print options that you want to display to the user in the print preview UI.
Important Calling displayedOptions.clear() removes all of the print options from the print preview UI, including the More settings link. Be sure to append the options that you want to show on the print preview UI.
void ScenarioInput3::PrintTaskRequested(PrintManager^ sender, PrintTaskRequestedEventArgs^ e) { auto printTaskRef = std::make_shared<PrintTask^>(nullptr); *printTaskRef = e->Request->CreatePrintTask("C++ Printing SDK Sample", ref new Windows::Graphics::Printing::PrintTaskSourceRequestedHandler([this, printTaskRef](PrintTaskSourceRequestedArgs^ args) { PrintTask^ printTask = *printTaskRef; IVector<String^>^ displayedOptions = printTask->Options->DisplayedOptions; // clear the print options that are displayed beacuse adding the same one multiple times will throw an exception displayedOptions->Clear(); // 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->Append(StandardPrintTaskOptions::Copies); displayedOptions->Append(StandardPrintTaskOptions::Orientation); displayedOptions->Append(StandardPrintTaskOptions::MediaSize); displayedOptions->Append(StandardPrintTaskOptions::Collation); displayedOptions->Append(StandardPrintTaskOptions::Duplex); // Preset the default value of the printer option printTask->Options->MediaSize = PrintMediaSize::NorthAmericaLegal; // Print Task event handler is invoked when the print job is completed. printTask->Completed += ref new TypedEventHandler<PrintTask^, PrintTaskCompletedEventArgs^>( [=](PrintTask^ sender, PrintTaskCompletedEventArgs^ e) { // Notify the user when the print operation fails. if (e->Completion == Windows::Graphics::Printing::PrintTaskCompletion::Failed) { auto callback = ref new Windows::UI::Core::DispatchedHandler( [=]() { RootPage->NotifyUser(ref new String(L"Failed to print."), NotifyType::ErrorMessage); }); Dispatcher->RunAsync(Windows::UI::Core::CoreDispatcherPriority::Normal, callback); } }); args->SetSource(PrintDocumentSource); })); }protected override void PrintTaskRequested(PrintManager sender, PrintTaskRequestedEventArgs e) { PrintTask printTask = null; printTask = e.Request.CreatePrintTask("C# Printing SDK Sample", sourceRequestedArgs => { IList<string> displayedOptions = printTask.Options.DisplayedOptions; // 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.MediaSize); displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.Collation); displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.Duplex); // Preset the default value of the printer option printTask.Options.MediaSize = PrintMediaSize.NorthAmericaLegal; // Print Task event handler is invoked when the print job is completed. printTask.Completed += async (s, args) => { // Notify the user when the print operation fails. if (args.Completion == PrintTaskCompletion.Failed) { await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () => { rootPage.NotifyUser("Failed to print.", NotifyType.ErrorMessage); }); } }; sourceRequestedArgs.SetSource(printDocumentSource); }); }Protected Overrides Sub PrintTaskRequested(sender As PrintManager, e As PrintTaskRequestedEventArgs) Dim printTask As PrintTask = Nothing printTask = e.Request.CreatePrintTask("VB Printing SDK Sample", Sub(sourceRequested) Dim displayedOptions As IList(Of String) = printTask.Options.DisplayedOptions ' 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.MediaSize) displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.Collation) displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.Duplex) ' Preset the default value of the printer option printTask.Options.MediaSize = PrintMediaSize.NorthAmericaLegal ''' <summary> ''' Option change event handler ''' </summary> ''' <param name="s">The print task option details for which an option changed.</param> ''' <param name="args">The event arguments containing the id of the changed option.</param> AddHandler printTask.Completed, Async Sub(s, args) '' Notify the user when the print operation fails. If args.Completion = PrintTaskCompletion.Failed Then Await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, Sub() rootPage.NotifyUser("Failed to print.", NotifyType.ErrorMessage) End Sub) End If End Sub sourceRequested.SetSource(printDocumentSource) End Sub) End SubYou can also set the default values of the options in the print preview UI. The following line of code, taken from the preceding code example, sets the default value of the MediaSize option.
// Preset the default value of the printer option printTask->Options->MediaSize = PrintMediaSize::NorthAmericaLegal;// Preset the default value of the printer option printTask.Options.MediaSize = PrintMediaSize.NorthAmericaLegal;' Preset the default value of the printer option printTask.Options.MediaSize = PrintMediaSize.NorthAmericaLegal
Summary and next steps
For the complete source code for this and other Windows Store app printing scenarios, see the Print Sample sample app.