Skip to content

Commit a6955aa

Browse files
jwmsftjwmsft
authored
Move/update print and scan for WinUI (#4786)
* Rename uwp/devices-sensors/print-from-your-app.md to hub/apps/develop/devices-sensors/print-from-your-app.md * Rename uwp/devices-sensors/customize-the-print-preview-ui.md to hub/apps/develop/devices-sensors/customize-the-print-preview-ui.md * Rename uwp/devices-sensors/scan-from-your-app.md to hub/apps/develop/devices-sensors/scan-from-your-app.md * add image of print ui * update content for WinUI 3 * move printing docs to WinUI * Rename uwp/devices-sensors/printing-and-scanning.md to hub/apps/develop/devices-sensors/printing-and-scanning.md * redirect printing docs * cleanup * remove printing docs * fix links
1 parent 22f849e commit a6955aa

File tree

11 files changed

+625
-628
lines changed

11 files changed

+625
-628
lines changed

‎.openpublishing.redirection.json

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8254,6 +8254,26 @@
82548254
"source_path": "uwp/security/credential-locker.md",
82558255
"redirect_url": "/windows/apps/develop/security/credential-locker",
82568256
"redirect_document_id": false
8257+
},
8258+
{
8259+
"source_path": "uwp/devices-sensors/printing-and-scanning.md",
8260+
"redirect_url": "/windows/apps/develop/devices-sensors/printing-and-scanning",
8261+
"redirect_document_id": false
8262+
},
8263+
{
8264+
"source_path": "uwp/devices-sensors/print-from-your-app.md",
8265+
"redirect_url": "/windows/apps/develop/devices-sensors/print-from-your-app",
8266+
"redirect_document_id": false
8267+
},
8268+
{
8269+
"source_path": "uwp/devices-sensors/customize-the-print-preview-ui.md",
8270+
"redirect_url": "/windows/apps/develop/devices-sensors/customize-the-print-preview-ui",
8271+
"redirect_document_id": false
8272+
},
8273+
{
8274+
"source_path": "uwp/devices-sensors/scan-from-your-app.md",
8275+
"redirect_url": "/windows/apps/develop/devices-sensors/scan-from-your-app",
8276+
"redirect_document_id": false
82578277
}
82588278
]
82598279
}

‎hub/apps/develop/devices-sensors/customize-the-print-preview-ui.md

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
---
2+
3+
title: Customize the print preview UI
4+
description: This topic describes how to customize the print options and settings in the print preview UI.
5+
ms.date: 09/10/2024
6+
ms.topic: article
7+
author: jwmsft
8+
ms.author: jimwalk
9+
ms.localizationpriority: medium
10+
---
11+
12+
# Customize the print preview UI
13+
14+
This topic describes how to customize the print options and settings in the print preview UI. For more info about printing, see [Print from your app](print-from-your-app.md).
15+
16+
> [!div class="checklist"]
17+
>
18+
> - **Important APIs**: [Windows.Graphics.Printing namespace](/uwp/api/windows.graphics.printing), [PrintTask](/uwp/api/windows.graphics.printing.printtask), [StandardPrintTaskOptions class](/uwp/api/Windows.Graphics.Printing.StandardPrintTaskOptions), [Microsoft.UI.Xaml.Printing namespace](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.printing), [PrintDocument class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.printing.PrintDocument)
19+
20+
## Customize print options
21+
22+
By default, the print preview UI shows the [**ColorMode**](/uwp/api/windows.graphics.printing.standardprinttaskoptions.colormode), [**Copies**](/uwp/api/windows.graphics.printing.standardprinttaskoptions.copies), and [**Orientation**](/uwp/api/windows.graphics.printing.standardprinttaskoptions.orientation) print options. In addition to those, there are several other common printer options that you can add to the print preview UI:
23+
24+
- [**Binding**](/uwp/api/windows.graphics.printing.standardprinttaskoptions.binding)
25+
- [**Bordering**](/uwp/api/windows.graphics.printing.standardprinttaskoptions.bordering)
26+
- [**Collation**](/uwp/api/windows.graphics.printing.standardprinttaskoptions.collation)
27+
- [**CustomPageRanges**](/uwp/api/windows.graphics.printing.standardprinttaskoptions.custompageranges)
28+
- [**Duplex**](/uwp/api/windows.graphics.printing.standardprinttaskoptions.duplex)
29+
- [**HolePunch**](/uwp/api/windows.graphics.printing.standardprinttaskoptions.holepunch)
30+
- [**InputBin**](/uwp/api/windows.graphics.printing.standardprinttaskoptions.inputbin)
31+
- [**MediaSize**](/uwp/api/windows.graphics.printing.standardprinttaskoptions.mediasize)
32+
- [**MediaType**](/uwp/api/windows.graphics.printing.standardprinttaskoptions.mediatype)
33+
- [**NUp**](/uwp/api/windows.graphics.printing.standardprinttaskoptions.nup)
34+
- [**PrintQuality**](/uwp/api/windows.graphics.printing.standardprinttaskoptions.printquality)
35+
- [**Staple**](/uwp/api/windows.graphics.printing.standardprinttaskoptions.staple)
36+
37+
These options are defined in the [StandardPrintTaskOptions](/uwp/api/windows.graphics.printing.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.
38+
39+
However, the modifications that you make in this way 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.
40+
41+
### Define the options to display
42+
43+
When you register your app for printing (see [Print from your app](print-from-your-app.md)), part of that registration includes defining the [PrintTaskRequested](/uwp/api/windows.graphics.printing.printmanager.printtaskrequested) event handler. The code to customize the options displayed in the print preview UI is added to the PrintTaskRequested event handler.
44+
45+
After you create the [PrintTask](/uwp/api/windows.graphics.printing.printtask) in the [PrintTaskRequested](/uwp/api/windows.graphics.printing.printmanager.printtaskrequested) event handler , you can get the [DisplayedOptions](/uwp/api/windows.graphics.printing.printtaskoptions.displayedoptions) list, which contains the option items shown in the print preview UI. You can modify this list by inserting, appending, removing, or re-ordering options.
46+
47+
> [!NOTE]
48+
> 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.
49+
50+
``` csharp
51+
private void PrintTask_Requested(PrintManager sender, PrintTaskRequestedEventArgs args)
52+
{
53+
// Create the PrintTask.
54+
// Defines the title and delegate for PrintTaskSourceRequested.
55+
PrintTask printTask = args.Request.CreatePrintTask("WinUI 3 Printing example", PrintTaskSourceRequested);
56+
57+
// Handle PrintTask.Completed to catch failed print jobs.
58+
printTask.Completed += PrintTask_Completed;
59+
60+
DispatcherQueue.TryEnqueue(DispatcherQueuePriority.Normal, () =>
61+
{
62+
InvokePrintingButton.IsEnabled = false;
63+
});
64+
65+
// Customize options displayed in print preview UI.
66+
// Get the list of displayed options.
67+
IList<string> displayedOptions = printTask.Options.DisplayedOptions;
68+
69+
// Choose the printer options to be shown.
70+
// The order in which the options are appended determines
71+
// the order in which they appear in the UI.
72+
displayedOptions.Clear();
73+
displayedOptions.Add(StandardPrintTaskOptions.Copies);
74+
displayedOptions.Add(StandardPrintTaskOptions.Orientation);
75+
displayedOptions.Add(StandardPrintTaskOptions.MediaSize);
76+
displayedOptions.Add(StandardPrintTaskOptions.Collation);
77+
displayedOptions.Add(StandardPrintTaskOptions.Duplex);
78+
79+
// Preset the default value of the print media size option.
80+
printTask.Options.MediaSize = PrintMediaSize.NorthAmericaLegal;
81+
}
82+
```
83+
84+
### Specify default options
85+
86+
You can also set the default values of the options in the print preview UI. The following line of code, from the last example, sets the default value of the [MediaSize](/uwp/api/windows.graphics.printing.printtaskoptions.mediasize) option.
87+
88+
``` csharp
89+
// Preset the default value of the print media size option.
90+
printTask.Options.MediaSize = PrintMediaSize.NorthAmericaLegal;
91+
```
92+
93+
> [!NOTE]
94+
> When you set the values in the DisplayedOptions list, you use the name you get from [StandardPrintTaskOptions](/uwp/api/windows.graphics.printing.standardprinttaskoptions) (for example, [StandardPrintTaskOptions.MediaSize](/uwp/api/windows.graphics.printing.standardprinttaskoptions.mediasize)).
95+
>
96+
> When you set the default value of an option, you use [PrintTaskOptions](/uwp/api/windows.graphics.printing.printtaskoptions) (for example, [PrintTaskOptions.MediaSize](/uwp/api/windows.graphics.printing.printtaskoptions.mediasize)).
97+
98+
## Add custom print options
99+
100+
Here, we demonstrate how to create a new custom print option, define a list of values that the option supports, and then add the option to the print preview. In this example, the custom print option lets the user specify whether to print only the text on the page, only the image, or both the text and image. The options are presented in a drop-down list.
101+
102+
In order to ensure a good user experience, the system requires that the app handle the [PrintTaskRequested](/uwp/api/windows.graphics.printing.printmanager.printtaskrequested) event within the time specified by [PrintTaskRequestedEventArgs.Request.Deadline](/uwp/api/windows.graphics.printing.printtasksourcerequestedargs.deadline). Therefore, we use the PrintTaskRequested handler only to create the print task. The print settings customization can be done when the print document source is requested. Here, we use a [lambda expression](/dotnet/csharp/language-reference/operators/lambda-expressions) to define the PrintTaskSourceRequestedHandler inline, which provides easier access to the PrintTask.
103+
104+
First, get a [PrintTaskOptionDetails](/uwp/api/windows.graphics.printing.optiondetails.printtaskoptiondetails) object and its list of [DisplayedOptions](/uwp/api/windows.graphics.printing.optiondetails.printtaskoptiondetails.displayedoptions). You use this to add the new print option to the print preview UI.
105+
106+
Next, to present the custom print options in a drop-down list, call [PrintTaskOptionDetails.CreateItemListOption](/uwp/api/windows.graphics.printing.optiondetails.printtaskoptiondetails.createitemlistoption) to create a [PrintCustomItemListOptionDetails](/uwp/api/windows.graphics.printing.optiondetails.printcustomitemlistoptiondetails) object. Create the new print option and initialize the list of option values. Finally, add the new option to the [DisplayedOptions](/uwp/api/windows.graphics.printing.optiondetails.printtaskoptiondetails.displayedoptions) list and assign a handler for the [OptionChanged](/uwp/api/windows.graphics.printing.optiondetails.printtaskoptiondetails.optionchanged) event. Because you are just adding a new print option at the end of the list of default options, you don't need to clear the DisplayedOptions list; just add the new option.
107+
108+
``` csharp
109+
private void PrintTask_Requested(PrintManager sender, PrintTaskRequestedEventArgs args)
110+
{
111+
// Create the PrintTask.
112+
PrintTask printTask = null;
113+
printTask = args.Request.CreatePrintTask("WinUI 3 Printing example", sourceRequestedArgs =>
114+
{
115+
PrintTaskSourceRequestedDeferral deferral =
116+
sourceRequestedArgs.GetDeferral();
117+
PrintTaskOptionDetails printDetailedOptions =
118+
PrintTaskOptionDetails.GetFromPrintTaskOptions(printTask.Options);
119+
IList<string> displayedOptions = printDetailedOptions.DisplayedOptions;
120+
121+
// Create a new list option.
122+
PrintCustomItemListOptionDetails pageFormat =
123+
printDetailedOptions.CreateItemListOption("PageContent", "Page content");
124+
pageFormat.AddItem("PicturesText", "Pictures and text");
125+
pageFormat.AddItem("PicturesOnly", "Pictures only");
126+
pageFormat.AddItem("TextOnly", "Text only");
127+
128+
// Add the custom option to the option list
129+
displayedOptions.Add("PageContent");
130+
131+
printDetailedOptions.OptionChanged += PrintDetailedOptions_OptionChanged;
132+
sourceRequestedArgs.SetSource(printDocumentSource);
133+
134+
deferral.Complete();
135+
});
136+
137+
// Handle PrintTask.Completed to catch failed print jobs.
138+
printTask.Completed += PrintTask_Completed;
139+
140+
DispatcherQueue.TryEnqueue(DispatcherQueuePriority.Normal, () =>
141+
{
142+
InvokePrintingButton.IsEnabled = false;
143+
});
144+
}
145+
```
146+
147+
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.
148+
149+
When the user changes the selected option in your custom option, use the selected option to update the print preview image. After the print preview layout in updated, call the [InvalidatePreview](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.printing.printdocument.invalidatepreview) method to redraw the image in the print preview UI, as shown here.
150+
151+
``` csharp
152+
void PrintDetailedOptions_OptionChanged(PrintTaskOptionDetails sender,
153+
PrintTaskOptionChangedEventArgs args)
154+
{
155+
string optionId = args.OptionId as string;
156+
if (string.IsNullOrEmpty(optionId))
157+
{
158+
return;
159+
}
160+
161+
if (optionId == "PageContent")
162+
{
163+
PrintCustomItemListOptionDetails pageContentOption =
164+
(PrintCustomItemListOptionDetails)sender.Options["PageContent"];
165+
string pageContentValue = pageContentOption.Value.ToString();
166+
167+
if (pageContentValue == "PicturesOnly")
168+
{
169+
pageLayoutOption = PageLayoutOption.Images;
170+
}
171+
else if (pageContentValue == "TextOnly")
172+
{
173+
pageLayoutOption = PageLayoutOption.Text;
174+
}
175+
else
176+
{
177+
pageLayoutOption = PageLayoutOption.TextAndImages;
178+
}
179+
180+
DispatcherQueue.TryEnqueue(DispatcherQueuePriority.Normal, () =>
181+
{
182+
printDocument.InvalidatePreview();
183+
});
184+
}
185+
}
186+
```
187+
188+
To support use of the custom options in your page, add an enum for the available options and a page-level variable to hold the selected option.
189+
190+
```csharp
191+
internal enum PageLayoutOption : int
192+
{
193+
Text = 1,
194+
Images = 2,
195+
TextAndImages = 3
196+
}
197+
198+
PageLayoutOption pageLayoutOption = PageLayoutOption.TextAndImages;
199+
```
200+
201+
Then, use the selected option in your Paginate handler where you add the content for the print preview.
202+
203+
```csharp
204+
private void PrintDocument_Paginate(object sender, PaginateEventArgs e)
205+
{
206+
// Clear the cache of preview pages.
207+
printPreviewPages.Clear();
208+
209+
// Get the PrintTaskOptions.
210+
PrintTaskOptions printingOptions = ((PrintTaskOptions)e.PrintTaskOptions);
211+
// Get the page description to determine the size of the print page.
212+
PrintPageDescription pageDescription = printingOptions.GetPageDescription(0);
213+
214+
// Create the print layout.
215+
StackPanel printLayout = new StackPanel();
216+
printLayout.Width = pageDescription.PageSize.Width;
217+
printLayout.Height = pageDescription.PageSize.Height;
218+
printLayout.BorderBrush = new Microsoft.UI.Xaml.Media.SolidColorBrush(Microsoft.UI.Colors.DimGray);
219+
printLayout.BorderThickness = new Thickness(48);
220+
221+
// Use the custom print layout options to determine
222+
// which elements to add to the print page.
223+
if (pageLayoutOption == PageLayoutOption.Images ||
224+
pageLayoutOption == PageLayoutOption.TextAndImages)
225+
{
226+
Image printImage = new Image();
227+
printImage.Source = printContent.Source;
228+
229+
printImage.Width = pageDescription.PageSize.Width / 2;
230+
printImage.Height = pageDescription.PageSize.Height / 2;
231+
printLayout.Children.Add(printImage);
232+
}
233+
234+
if (pageLayoutOption == PageLayoutOption.Text ||
235+
pageLayoutOption == PageLayoutOption.TextAndImages)
236+
{
237+
TextBlock imageDescriptionText = new TextBlock();
238+
imageDescriptionText.Text = imageDescription.Text;
239+
imageDescriptionText.FontSize = 24;
240+
imageDescriptionText.HorizontalAlignment = HorizontalAlignment.Center;
241+
imageDescriptionText.Width = pageDescription.PageSize.Width / 2;
242+
imageDescriptionText.TextWrapping = TextWrapping.WrapWholeWords;
243+
244+
printLayout.Children.Add(imageDescriptionText);
245+
}
246+
247+
// Add the print layout to the list of preview pages.
248+
printPreviewPages.Add(printLayout);
249+
250+
// Report the number of preview pages created.
251+
PrintDocument printDocument = (PrintDocument)sender;
252+
printDocument.SetPreviewPageCount(printPreviewPages.Count,
253+
PreviewPageCountType.Intermediate);
254+
}
255+
256+
```
257+
258+
## See also
259+
260+
- [Printing and scanning](printing-and-scanning.md)
261+
- [Print from your app](print-from-your-app.md)

‎hub/apps/develop/devices-sensors/images/print-demo-basic.png

92.8 KB
Loading

0 commit comments

Comments
 (0)