Personalizzare l'interfaccia utente dell'anteprima di stampa

Questo argomento descrive come personalizzare le opzioni di stampa e le impostazioni nell'interfaccia utente dell'anteprima di stampa. Per altre info sulla stampa, vedere Stampa dalla tua app.

Personalizzare le opzioni di stampa

Per impostazione predefinita, l'interfaccia utente dell'anteprima di stampa mostra le opzioni di stampa ColorMode, Copie, e Orientamento. Oltre a quelli, sono disponibili diverse altre opzioni comuni per la stampante che è possibile aggiungere all'interfaccia utente dell'anteprima di stampa:

• Binding
• Cingente
• Regole di confronto
• CustomPageRanges
• Duplex
• HolePunch
• InputBin
• MediaSize
• MediaType
• NUp
• PrintQuality
• Elemento base

Queste opzioni sono definite nella classe StandardPrintTaskOptions. È possibile aggiungere o rimuovere opzioni dall'elenco di opzioni visualizzate nell'interfaccia utente dell'anteprima di stampa. È anche possibile modificare l'ordine in cui vengono visualizzati e impostare le impostazioni predefinite visualizzate all'utente.

Tuttavia, le modifiche apportate in questo modo influiscono solo sull'interfaccia utente dell'anteprima di stampa. L'utente può sempre accedere a tutte le opzioni supportate dalla stampante toccando Altre impostazioni nell'interfaccia utente dell'anteprima di stampa.

Definire le opzioni da visualizzare

Quando registri l'app per la stampa (vedi Stampa dall'app), parte di tale registrazione include la definizione del gestore eventi PrintTaskRequested . Il codice per personalizzare le opzioni visualizzate nell'interfaccia utente dell'anteprima di stampa viene aggiunto al gestore eventi PrintTaskRequested.

Dopo aver creato PrintTask nel gestore eventi PrintTaskRequested , è possibile ottenere l'elenco DisplayOptions , che contiene gli elementi di opzione visualizzati nell'interfaccia utente dell'anteprima di stampa. È possibile modificare l'elenco inserendo, aggiungendo, rimuovendo o riordinando le opzioni.

private void PrintTask_Requested(PrintManager sender, PrintTaskRequestedEventArgs args)
{
    // Create the PrintTask.
    // Defines the title and delegate for PrintTaskSourceRequested.
    PrintTask printTask = args.Request.CreatePrintTask("WinUI 3 Printing example", PrintTaskSourceRequested);

    // Handle PrintTask.Completed to catch failed print jobs.
    printTask.Completed += PrintTask_Completed;

    DispatcherQueue.TryEnqueue(DispatcherQueuePriority.Normal, () =>
    {
        InvokePrintingButton.IsEnabled = false;
    });

    // Customize options displayed in print preview UI.
    // Get the list of displayed options.
    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(StandardPrintTaskOptions.Copies);
    displayedOptions.Add(StandardPrintTaskOptions.Orientation);
    displayedOptions.Add(StandardPrintTaskOptions.MediaSize);
    displayedOptions.Add(StandardPrintTaskOptions.Collation);
    displayedOptions.Add(StandardPrintTaskOptions.Duplex);

    // Preset the default value of the print media size option.
    printTask.Options.MediaSize = PrintMediaSize.NorthAmericaLegal;
}

Specificare le opzioni predefinite

È anche possibile impostare i valori predefiniti delle opzioni nell'interfaccia utente dell'anteprima di stampa. La riga di codice seguente, dall'ultimo esempio, imposta il valore predefinito dell'opzione MediaSize .

// Preset the default value of the print media size option.
printTask.Options.MediaSize = PrintMediaSize.NorthAmericaLegal;

Aggiungere opzioni di stampa personalizzate

In questo caso viene illustrato come creare una nuova opzione di stampa personalizzata, definire un elenco di valori supportati dall'opzione e quindi aggiungere l'opzione all'anteprima di stampa. In questo esempio, l'opzione di stampa personalizzata consente all'utente di specificare se stampare solo il testo nella pagina, solo l'immagine o sia il testo che l'immagine. Le opzioni vengono presentate in un elenco a discesa.

Per garantire un'esperienza utente ottimale, il sistema richiede che l'app gestisca l'evento PrintTaskRequested entro il tempo specificato da PrintTaskRequestedEventArgs.Request.Deadline. Pertanto, si usa il gestore PrintTaskRequested solo per creare l'attività di stampa. La personalizzazione delle impostazioni di stampa può essere eseguita quando viene richiesta l'origine del documento di stampa. In questo caso viene usata un'espressione lambda per definire l'inline PrintTaskSourceRequestedHandler, che consente di accedere più facilmente a PrintTask.

Innanzitutto, ottenere un oggetto PrintTaskOptionDetails e il relativo elenco di DisplayOptions. Questa opzione viene usata per aggiungere la nuova opzione di stampa all'interfaccia utente dell'anteprima di stampa.

Successivamente, per presentare le opzioni di stampa personalizzate in un elenco a discesa, chiamare PrintTaskOptionDetails.CreateItemListOption per creare un oggetto PrintCustomItemListOptionDetails . Creare la nuova opzione di stampa e inizializzare l'elenco di valori di opzione. Aggiungere infine la nuova opzione all'elenco DisplayedOptions e assegnare un gestore per l'evento OptionChanged . Poiché si sta semplicemente aggiungendo una nuova opzione di stampa alla fine dell'elenco delle opzioni predefinite, non è necessario cancellare l'elenco DisplayedOptions; basta aggiungere la nuova opzione.

private void PrintTask_Requested(PrintManager sender, PrintTaskRequestedEventArgs args)
{
    // Create the PrintTask.
    PrintTask printTask = null;
    printTask = args.Request.CreatePrintTask("WinUI 3 Printing example", sourceRequestedArgs =>
    {
        PrintTaskSourceRequestedDeferral deferral = 
            sourceRequestedArgs.GetDeferral();
        PrintTaskOptionDetails printDetailedOptions = 
            PrintTaskOptionDetails.GetFromPrintTaskOptions(printTask.Options);
        IList<string> displayedOptions = printDetailedOptions.DisplayedOptions;

        // Create a new list option.
        PrintCustomItemListOptionDetails pageFormat =
            printDetailedOptions.CreateItemListOption("PageContent", "Page content");
        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;
        sourceRequestedArgs.SetSource(printDocumentSource);

        deferral.Complete();
    });

    // Handle PrintTask.Completed to catch failed print jobs.
    printTask.Completed += PrintTask_Completed;

    DispatcherQueue.TryEnqueue(DispatcherQueuePriority.Normal, () =>
    {
        InvokePrintingButton.IsEnabled = false;
    });
}

Le opzioni vengono visualizzate nell'interfaccia utente dell'anteprima di stampa nello stesso ordine in cui vengono aggiunte, con la prima opzione visualizzata nella parte superiore della finestra. In questo esempio, l'opzione personalizzata viene aggiunta per ultima in modo che venga visualizzata nella parte inferiore dell'elenco di opzioni. Tuttavia, è possibile inserirlo ovunque nell'elenco; le opzioni di stampa personalizzate non devono essere aggiunte per ultimo.

Quando l'utente modifica l'opzione selezionata nell'opzione personalizzata, usa l'opzione selezionata per aggiornare l'immagine di anteprima di stampa. Dopo aver aggiornato il layout dell'anteprima di stampa, chiamare il metodo InvalidatePreview per ridisegnare l'immagine nell'interfaccia utente dell'anteprima di stampa, come illustrato di seguito.

void PrintDetailedOptions_OptionChanged(PrintTaskOptionDetails sender, 
                                        PrintTaskOptionChangedEventArgs args)
{
    string optionId = args.OptionId as string;
    if (string.IsNullOrEmpty(optionId))
    {
        return;
    }

    if (optionId == "PageContent")
    {
        PrintCustomItemListOptionDetails pageContentOption =
            (PrintCustomItemListOptionDetails)sender.Options["PageContent"];
        string pageContentValue = pageContentOption.Value.ToString();

        if (pageContentValue == "PicturesOnly")
        {
            pageLayoutOption = PageLayoutOption.Images;
        }
        else if (pageContentValue == "TextOnly")
        {
            pageLayoutOption = PageLayoutOption.Text;
        }
        else
        {
            pageLayoutOption = PageLayoutOption.TextAndImages;
        }

        DispatcherQueue.TryEnqueue(DispatcherQueuePriority.Normal, () =>
        {
            printDocument.InvalidatePreview();
        });
    }
}

Per supportare l'uso delle opzioni personalizzate nella pagina, aggiungere un'enumerazione per le opzioni disponibili e una variabile a livello di pagina per contenere l'opzione selezionata.

internal enum PageLayoutOption : int
{
    Text = 1,
    Images = 2,
    TextAndImages = 3
}

PageLayoutOption pageLayoutOption = PageLayoutOption.TextAndImages;

Usare quindi l'opzione selezionata nel gestore paginate in cui si aggiunge il contenuto per l'anteprima di stampa.

private void PrintDocument_Paginate(object sender, PaginateEventArgs e)
{
    // Clear the cache of preview pages.
    printPreviewPages.Clear();

    // Get the PrintTaskOptions.
    PrintTaskOptions printingOptions = ((PrintTaskOptions)e.PrintTaskOptions);
    // Get the page description to determine the size of the print page.
    PrintPageDescription pageDescription = printingOptions.GetPageDescription(0);

    // Create the print layout.
    StackPanel printLayout = new StackPanel();
    printLayout.Width = pageDescription.PageSize.Width;
    printLayout.Height = pageDescription.PageSize.Height;
    printLayout.BorderBrush = new Microsoft.UI.Xaml.Media.SolidColorBrush(Microsoft.UI.Colors.DimGray);
    printLayout.BorderThickness = new Thickness(48);

    // Use the custom print layout options to determine
    // which elements to add to the print page. 
    if (pageLayoutOption == PageLayoutOption.Images ||
        pageLayoutOption == PageLayoutOption.TextAndImages)
    {
        Image printImage = new Image();
        printImage.Source = printContent.Source;

        printImage.Width = pageDescription.PageSize.Width / 2;
        printImage.Height = pageDescription.PageSize.Height / 2;
        printLayout.Children.Add(printImage);
    }

    if (pageLayoutOption == PageLayoutOption.Text ||
        pageLayoutOption == PageLayoutOption.TextAndImages)
    {
        TextBlock imageDescriptionText = new TextBlock();
        imageDescriptionText.Text = imageDescription.Text;
        imageDescriptionText.FontSize = 24;
        imageDescriptionText.HorizontalAlignment = HorizontalAlignment.Center;
        imageDescriptionText.Width = pageDescription.PageSize.Width / 2;
        imageDescriptionText.TextWrapping = TextWrapping.WrapWholeWords;

        printLayout.Children.Add(imageDescriptionText);
    }

    // Add the print layout to the list of preview pages.
    printPreviewPages.Add(printLayout);

    // Report the number of preview pages created.
    PrintDocument printDocument = (PrintDocument)sender;
    printDocument.SetPreviewPageCount(printPreviewPages.Count,
                                          PreviewPageCountType.Intermediate);
}

Vedi anche

• Stampa e digitalizzazione
• Stampare dall'app