Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 6bb5e19

Browse files
adegeoadegeo
authored
Clarify print preview usage in winforms (#2051)
* Clarify usage * add .NET instructions * Change from headers to bullets * Adjust section * Change from headers to bullets
1 parent ab266d4 commit 6bb5e19

File tree

1 file changed

+74
-17
lines changed

1 file changed

+74
-17
lines changed

‎dotnet-desktop-guide/framework/winforms/controls/printpreviewdialog-control-overview-windows-forms.md

+74-17
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "PrintPreviewDialog Control Overview"
3-
description: This article provides an overview of the PrintPreviewDialog control in Windows Forms, which is a pre-configured dialog box.
4-
ms.date: "01/08/2018"
3+
description: This article provides an overview of the PrintPreviewDialog control in Windows Forms, which is a preconfigured dialog box.
4+
ms.date: 04/07/2025
55
f1_keywords:
66
- "PrintPreviewDialog"
77
helpviewer_keywords:
@@ -10,43 +10,100 @@ ms.assetid: efd4ee8d-6edd-47ec-88e4-4a4759bd2384
1010
---
1111
# PrintPreviewDialog control overview (Windows Forms)
1212

13-
The Windows Forms <xref:System.Windows.Forms.PrintPreviewDialog> control is a pre-configured dialog box used to display how a [PrintDocument](printdocument-component-windows-forms.md) will appear when printed. Use it within your Windows-based application as a simple solution instead of configuring your own dialog box. The control contains buttons for printing, zooming in, displaying one or multiple pages, and closing the dialog box.
13+
The Windows Forms <xref:System.Windows.Forms.PrintPreviewDialog> control is a preconfigured dialog box used to display how a [PrintDocument](printdocument-component-windows-forms.md) appears when printed. Use it within your Windows-based application as a simple solution instead of configuring your own dialog box. The control contains buttons for printing, zooming in, displaying one or multiple pages, and closing the dialog box.
1414

1515
## Key properties and methods
1616

1717
The control's key property is <xref:System.Windows.Forms.PrintPreviewDialog.Document%2A>, which sets the document to be previewed. The document must be a <xref:System.Drawing.Printing.PrintDocument> object. In order to display the dialog box, you must call its <xref:System.Windows.Forms.Form.ShowDialog%2A> method. Anti-aliasing can make the text appear smoother, but it can also make the display slower; to use it, set the <xref:System.Windows.Forms.PrintPreviewDialog.UseAntiAlias%2A> property to `true`.
1818

19-
Certain properties are available through the <xref:System.Windows.Forms.PrintPreviewControl> that the <xref:System.Windows.Forms.PrintPreviewDialog> contains. (You do not have to add this <xref:System.Windows.Forms.PrintPreviewControl> to the form; it is automatically contained within the <xref:System.Windows.Forms.PrintPreviewDialog> when you add the dialog to your form.) Examples of properties available through the <xref:System.Windows.Forms.PrintPreviewControl> are the <xref:System.Windows.Forms.PrintPreviewControl.Columns%2A> and <xref:System.Windows.Forms.PrintPreviewControl.Rows%2A> properties, which determine the number of pages displayed horizontally and vertically on the control. You can access the <xref:System.Windows.Forms.PrintPreviewControl.Columns%2A> property as `PrintPreviewDialog1.PrintPreviewControl.Columns` in Visual Basic, `printPreviewDialog1.PrintPreviewControl.Columns` in Visual C#, or `printPreviewDialog1->PrintPreviewControl->Columns` in Visual C++.
19+
Certain properties are available through the <xref:System.Windows.Forms.PrintPreviewControl> that the <xref:System.Windows.Forms.PrintPreviewDialog> contains. (You don't have to add <xref:System.Windows.Forms.PrintPreviewControl> to the form; it's automatically contained within the <xref:System.Windows.Forms.PrintPreviewDialog> when you add the dialog to your form.) Examples of properties available through the <xref:System.Windows.Forms.PrintPreviewControl> are the <xref:System.Windows.Forms.PrintPreviewControl.Columns%2A> and <xref:System.Windows.Forms.PrintPreviewControl.Rows%2A> properties, which determine the number of pages displayed horizontally and vertically on the control. You can access the <xref:System.Windows.Forms.PrintPreviewControl.Columns%2A> property as `PrintPreviewDialog1.PrintPreviewControl.Columns` in Visual Basic, `printPreviewDialog1.PrintPreviewControl.Columns` in Visual C#, or `printPreviewDialog1->PrintPreviewControl->Columns` in Visual C++.
2020

2121
## PrintPreviewDialog performance
2222

23-
Under the following conditions, the <xref:System.Windows.Forms.PrintPreviewDialog> control initializes very slowly:
23+
Under the following conditions, the <xref:System.Windows.Forms.PrintPreviewDialog> control initializes slowly:
2424

2525
- A network printer is used.
2626
- User preferences for this printer, such as duplex settings, are modified.
2727

28-
For apps running on the .NET Framework 4.5.2, you can add the following key to the \<appSettings> section of your configuration file to improve the performance of <xref:System.Windows.Forms.PrintPreviewDialog> control initialization:
28+
The optimization isn't applied if you use the <xref:System.Drawing.Printing.PrintDocument.QueryPageSettings> event to modify page settings.
2929

30-
```xml
31-
<appSettings>
32-
<add key="EnablePrintPreviewOptimization" value="true" />
33-
</appSettings>
34-
```
30+
To apply the optimization, set the `Switch.System.Drawing.Printing.OptimizePrintPreview` runtime config option to `true`.
31+
32+
# [.NET](#tab/dotnet)
33+
34+
The option can be set in the _runtimeconfig.json_ configuration file or the project file of an app:
35+
36+
- **Configure a default in project file.**
37+
38+
To apply the setting in the project file, enable runtime config generation by setting `<GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>` to in a `<PropertyGroup>`. Then, add the `<RuntimeHostConfigurationOption>` setting to an `<ItemGroup>`:
39+
40+
```xml
41+
<Project Sdk="Microsoft.NET.Sdk">
42+
43+
<!-- Other project settings ... -->
44+
45+
<PropertyGroup>
46+
<GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
47+
</PropertyGroup>
48+
49+
<ItemGroup>
50+
<RuntimeHostConfigurationOption Include="Switch.System.Drawing.Printing.OptimizePrintPreview" Value="true" />
51+
</ItemGroup>
3552

36-
If the `EnablePrintPreviewOptimization` key is set to any other value, or if the key is not present, the optimization is not applied. This key has no effect if the application is running on .NET Framework 4.6 or later.
53+
</Project>
54+
```
3755

38-
For apps running on the .NET Framework 4.6 or later versions, you can add the following switch to the [\<AppContextSwitchOverrides>](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) element in the [\<runtime>](/dotnet/framework/configure-apps/file-schema/runtime/index) section of your app config file:
56+
- **Configure a default in the _runtimeconfig.template.json_ source file.**
57+
58+
To configure the default setting for your app, apply the setting in the _runtimeconfig.template.json_ source file. When the app is compiled or published, the template file is used to generate a runtime config file.
59+
60+
```json
61+
{
62+
"configProperties": {
63+
"Switch.System.Drawing.Printing.OptimizePrintPreview": true
64+
}
65+
}
66+
```
67+
68+
For more information about runtime config, see [.NET runtime configuration settings](/dotnet/core/runtime-config/).
69+
70+
- **Configure a published app with the _{appname}.runtimeconfig.json_ output file.**
71+
72+
To configure the published app, apply the setting in the _{appname}.runtimeconfig.json_ file's `runtimeOptions/configProperties` section.
73+
74+
```json
75+
{
76+
"runtimeOptions": {
77+
"configProperties": {
78+
"Switch.System.Drawing.Printing.OptimizePrintPreview": true,
79+
}
80+
}
81+
}
82+
```
83+
84+
For more information about runtime config, see [.NET runtime configuration settings](/dotnet/core/runtime-config/).
85+
86+
# [.NET Framework](#tab/dotnetframework)
87+
88+
Add the following switch to the [`<AppContextSwitchOverrides>`](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) element in the [`<runtime>`](/dotnet/framework/configure-apps/file-schema/runtime/index) section of the app config file:
3989

4090
```xml
4191
<runtime >
42-
  <!-- AppContextSwitchOverrides values are in the form of 'key1=true|false;key2=true|false -->
43-
<AppContextSwitchOverrides value = "Switch.System.Drawing.Printing.OptimizePrintPreview=true" />
92+
  <!-- AppContextSwitchOverrides values are in the form of "key1=true|false;key2=true|false" -->
93+
<AppContextSwitchOverrides value="Switch.System.Drawing.Printing.OptimizePrintPreview=true" />
4494
</runtime >
4595
```
4696

47-
If the switch is not present or if it is set to any other value, the optimization is not applied.
97+
> [!TIP]
98+
> If .NET Framework 4.5.2 (no longer supported) is installed, enable the optimization by adding the following key to the `<appSettings>` section of your configuration file to improve the performance of <xref:System.Windows.Forms.PrintPreviewDialog> control initialization:
99+
>
100+
> ```xml
101+
> <appSettings>
102+
> <add key="EnablePrintPreviewOptimization" value="true" />
103+
> </appSettings>
104+
> ```
48105
49-
If you use the <xref:System.Drawing.Printing.PrintDocument.QueryPageSettings> event to modify printer settings, the performance of the <xref:System.Windows.Forms.PrintPreviewDialog> control will not improve even if an optimization configuration switch is set.
106+
---
50107
51108
## See also
52109

0 commit comments

Comments
 (0)