印刷プレビュー UI のカスタマイズCustomize the print preview UI

重要な APIImportant APIs

このセクションでは、印刷プレビュー UI の印刷オプションや設定をカスタマイズする方法について説明します。This section describes how to customize the print options and settings in the print preview UI. 印刷機能の詳細については、「アプリからの印刷」を参照してください。For more info about printing, see Print from your app.

ヒント:   ほとんどの例では、このトピックでは、印刷のサンプルに基づいています。Tip  Most of the examples in this topic are based on the print sample. 完全なコードを確認するには、GitHub の Windows-universal-samples リポジトリからユニバーサル Windows プラットフォーム (UWP) 印刷サンプルをダウンロードしてください。To see the full code, download the Universal Windows Platform (UWP) print sample from the Windows-universal-samples repo on GitHub.

 

印刷オプションのカスタマイズCustomize print options

既定では、印刷プレビュー UI には ColorModeCopies、および Orientation の印刷オプションが表示されます。By default, the print preview UI shows the ColorMode, Copies, and Orientation print options. これらに加え、印刷プレビュー UI に追加できるその他の一般的なプリンター オプションがいくつか用意されています。In addition to those, there are several other common printer options that you can add to the print preview UI:

これらのオプションは、StandardPrintTaskOptions クラスで定義されます。These options are defined in the StandardPrintTaskOptions class. 印刷プレビュー UI に表示されるオプションの一覧へのオプションの追加や、この一覧からのオプションの削除ができます。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.

ただし、この方法を使って加えた変更は、印刷プレビュー UI にのみ影響します。However, the modifications that you make by using this method affect only the print preview UI. ユーザーは印刷プレビュー UI で [その他の設定] をタップすることで、プリンターでサポートされているすべてのオプションにいつでもアクセスできます。The user can always access all of the options that the printer supports by tapping More settings in the print preview UI.

  アプリは、表示される印刷オプションを指定しますが、印刷プレビュー UI、選択したプリンターでサポートされているものだけに表示されます。Note  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. 印刷 UI には、選んだプリンターでサポートされないオプションは表示されません。The print UI won't show options that the selected printer doesn't support.

 

表示するオプションの定義Define the options to display

アプリの画面が読み込まれると、印刷コントラクトに登録されます。When the app's screen is loaded, it registers for the Print contract. その登録には、PrintTaskRequested イベント ハンドラーの定義が含まれています。Part of that registration includes defining the PrintTaskRequested event handler. 印刷プレビュー UI に表示されるオプションをカスタマイズするコードは、PrintTaskRequested イベント ハンドラーに追加します。The code to customize the options displayed in the print preview UI is added to the PrintTaskRequested event handler.

PrintTaskRequested イベント ハンドラーを変更して、印刷プレビュー UI に表示する印刷設定を構成する printTask.options 命令を含めます。印刷オプションのカスタマイズ リストを表示するアプリの画面の場合は、ヘルパー クラスの PrintTaskRequested イベント ハンドラーを上書きし、この画面が印刷されるときに表示するオプションを指定するコードを含めます。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 helper class to include code that specifies the options to display when the screen is printed.

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 scenarioPage.Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
               {
                     MainPage.Current.NotifyUser("Failed to print.", NotifyType.ErrorMessage);
               });
            }
         };

         sourceRequestedArgs.SetSource(printDocumentSource);
   });
}

重要な  呼び出す displayedOptions.clear() の印刷プレビュー UI からすべての印刷オプションが削除を含む、 より多くの設定リンク。Important  Calling displayedOptions.clear() removes all of the print options from the print preview UI, including the More settings link. 印刷プレビュー UI に表示するオプションを必ず追加してください。Be sure to append the options that you want to show on the print preview UI.

既定のオプションの指定Specify default options

印刷プレビュー UI には、オプションの既定値を設定することもできます。You can also set the default values of the options in the print preview UI. 次のコード行は前の例から抜粋したものであり、MediaSize オプションの既定値を設定しています。The following line of code, from the last example, sets the default value of the MediaSize option.

         // Preset the default value of the printer option
         printTask.Options.MediaSize = PrintMediaSize.NorthAmericaLegal;

新しい印刷オプションの追加Add new print options

このセクションでは、新しい印刷オプションを作成し、オプションがサポートする値の一覧を定義して、印刷プレビューにオプションを追加する方法について説明します。This section shows how to create a new print option, define a list of values that the option supports, and then add the option to the print preview. 前のセクションと同様に、PrintTaskRequested イベント ハンドラーに新しい印刷オプションを追加します。As in the previous section, add the new print option in the PrintTaskRequested event handler.

まず、PrintTaskOptionDetails オブジェクトを取得します。First, get a PrintTaskOptionDetails object. これは、印刷プレビュー UI に新しい印刷オプションを追加するために使用します。This is used to add the new print option to the print preview UI. 次に、印刷プレビュー UI に表示されるオプションの一覧をクリアし、ユーザーがアプリから印刷する場合に表示するオプションを追加します。Then 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. その後、新しい印刷オプションを作成し、オプションの値の一覧を初期化します。After that, create the new print option and initialize the list of option values. 最後に、新しいオプションを追加して OptionChanged イベントのハンドラーを割り当てます。Finally, add the new option and assign a handler for the OptionChanged event.

protected override void PrintTaskRequested(PrintManager sender, PrintTaskRequestedEventArgs e)
{
   PrintTask printTask = null;
   printTask = e.Request.CreatePrintTask("C# Printing SDK Sample", sourceRequestedArgs =>
   {
         PrintTaskOptionDetails printDetailedOptions = PrintTaskOptionDetails.GetFromPrintTaskOptions(printTask.Options);
         IList<string> displayedOptions = printDetailedOptions.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.ColorMode);

         // 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");

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

         printDetailedOptions.OptionChanged += printDetailedOptions_OptionChanged;

         // 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 scenarioPage.Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
               {
                     MainPage.Current.NotifyUser("Failed to print.", NotifyType.ErrorMessage);
               });
            }
         };

         sourceRequestedArgs.SetSource(printDocumentSource);
   });
}

オプションは、追加された順番で印刷プレビュー UI に表示されます。したがって、最初のオプションがウィンドウの最上部に表示されます。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. この例では、カスタム オプションは最後に追加されるため、オプションの一覧の最下部に表示されます。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.

ユーザーがカスタム オプションの選択オプションを変更した場合は、印刷プレビューの画像を更新する必要があります。When the user changes the selected option in your custom option, update the print preview image. 印刷プレビュー UI の画像を再描画するには、次の例のように、InvalidatePreview メソッドを呼び出します。Call the InvalidatePreview method to redraw the image in the print preview UI, as shown below.

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 scenarioPage.Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
         {
            printDocument.InvalidatePreview();
         });
   }
}