-
Notifications
You must be signed in to change notification settings - Fork 182
Rewrite autoscale article to reflect modern .NET DPI handling #2152
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closed
Closed
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,63 +1,126 @@ | ||
| --- | ||
| title: "Automatic form scaling" | ||
| description: "A look into how Windows Forms for .NET handles scaling the UI." | ||
| title: "Automatic scaling in Windows Forms" | ||
| description: "Learn how Windows Forms handles DPI scaling and high-DPI support for modern .NET applications." | ||
| ms.date: 10/26/2020 | ||
| ms.service: dotnet-desktop | ||
| ms.update-cycle: 365-days | ||
| ms.topic: overview | ||
| ai-usage: ai-assisted | ||
| helpviewer_keywords: | ||
| - "scalability [Windows Forms], automatic in Windows Forms" | ||
| - "Windows Forms, automatic scaling" | ||
| # This article needs a rewrite. It really reflects how DPI is working in .NET Framework and not in .NET 9+. | ||
| - "high DPI support" | ||
| - "DPI awareness" | ||
| --- | ||
|
|
||
| # Automatic scaling | ||
| # Automatic scaling in Windows Forms | ||
|
|
||
| Automatic scaling enables a form and its controls, designed on one machine with a certain display resolution or font, to be displayed appropriately on another machine with a different display resolution or font. It assures that the form and its controls will intelligently resize to be consistent with native windows and other applications on both the users' and other developers' machines. Automatic scaling and visual styles enable Windows Forms applications to maintain a consistent look-and-feel when compared to native Windows applications on each user's machine. | ||
| Windows Forms automatically scales your forms and controls to display correctly across different monitors with varying DPI settings. This feature ensures your application maintains a consistent appearance whether it runs on a standard monitor or a high-DPI display. | ||
|
|
||
| For the most part, automatic scaling works as expected in Windows Forms. However, font scheme changes can be problematic. For an example of how to resolve this, see [How to: Respond to Font Scheme Changes in a Windows Forms Application](../how-to-respond-to-font-scheme-changes-in-a-windows-forms-application.md). | ||
| ## How DPI scaling works | ||
|
|
||
| ## Need for automatic scaling | ||
| Modern displays use varying pixel densities, measured in dots per inch (DPI). Standard displays use 96 DPI (100% scaling), but high-resolution displays can use 120 DPI (125%), 144 DPI (150%), 192 DPI (200%), or higher. Without proper DPI scaling, your application might appear too small on high-DPI displays or too large on standard displays. | ||
|
|
||
| Without automatic scaling, an application designed for one display resolution or font will either appear too small or too large when that resolution or font is changed. For example, if the application is designed using Tahoma 9 point as a baseline, without adjustment it will appear too small if run on a machine where the system font is Tahoma 12 point. Text elements, such as titles, menus, text box contents, and so on will render smaller than other applications. Furthermore, the size of user interface (UI) elements that contain text, such as the title bar, menus, and many controls are dependent on the font used. In this example, these elements will also appear relatively smaller. | ||
| Windows Forms handles DPI scaling automatically when you configure DPI awareness for your application. The framework adjusts the size and position of forms and controls based on the DPI of the monitor where they're displayed. | ||
|
|
||
| An analogous situation occurs when an application is designed for a certain display resolution. The most common display resolution is 96 dots per inch (DPI), which equals 100% display scaling, but higher resolution displays supporting 125%, 150%, 200% (which respectively equal 120, 144 and 192 DPI) and above are becoming more common. Without adjustment, an application, especially a graphics-based one, designed for one resolution will appear either too large or too small when run at another resolution. | ||
| ## Configure DPI awareness | ||
|
|
||
| Automatic scaling seeks to address these problems by automatically resizing the form and its child controls according to the relative font size or display resolution. The Windows operating system supports automatic scaling of dialog boxes using a relative unit of measurement called dialog units. A dialog unit is based on the system font and its relationship to pixels can be determined through the Win32 SDK function `GetDialogBaseUnits`. When a user changes the theme used by Windows, all dialog boxes are automatically adjusted accordingly. In addition, Windows Forms supports automatic scaling either according to the default system font or the display resolution. Optionally, automatic scaling can be disabled in an application. | ||
| For modern .NET applications (.NET 6 and later), configure DPI awareness in your project file using the `ApplicationHighDpiMode` property. This is the recommended approach because Visual Studio's designer uses these settings when you design forms. | ||
|
|
||
| > [!CAUTION] | ||
| > Arbitrary mixtures of DPI and font scaling modes are not supported. Although you may scale a user control using one mode (for example, DPI) and place it on a form using another mode (Font) with no issues, but mixing a base form in one mode and a derived form in another can lead to unexpected results. | ||
| Add the following property to your project file: | ||
|
|
||
| ## Automatic scaling in action | ||
| ```xml | ||
| <Project Sdk="Microsoft.NET.Sdk"> | ||
|
|
||
| Windows Forms uses the following logic to automatically scale forms and their contents: | ||
| <PropertyGroup> | ||
| <OutputType>WinExe</OutputType> | ||
| <TargetFramework>net9.0-windows</TargetFramework> | ||
| <UseWindowsForms>true</UseWindowsForms> | ||
|
|
||
| <ApplicationHighDpiMode>PerMonitorV2</ApplicationHighDpiMode> | ||
| </PropertyGroup> | ||
|
|
||
| 01. At design time, each <xref:System.Windows.Forms.ContainerControl> records the scaling mode and it current resolution in the <xref:System.Windows.Forms.ContainerControl.AutoScaleMode%2A> and <xref:System.Windows.Forms.ContainerControl.AutoScaleDimensions%2A>, respectively. | ||
| </Project> | ||
| ``` | ||
|
|
||
| 01. At run time, the actual resolution is stored in the <xref:System.Windows.Forms.ContainerControl.CurrentAutoScaleDimensions%2A> property. The <xref:System.Windows.Forms.ContainerControl.AutoScaleFactor%2A> property dynamically calculates the ratio between the run-time and design-time scaling resolution. | ||
| Alternatively, you can set DPI awareness in code by calling <xref:System.Windows.Forms.Application.SetHighDpiMode%2A> before calling `Application.Run`: | ||
|
|
||
| 01. When the form loads, if the values of <xref:System.Windows.Forms.ContainerControl.CurrentAutoScaleDimensions%2A> and <xref:System.Windows.Forms.ContainerControl.AutoScaleDimensions%2A> are different, then the <xref:System.Windows.Forms.ContainerControl.PerformAutoScale%2A> method is called to scale the control and its children. This method suspends layout and calls the <xref:System.Windows.Forms.Control.Scale%2A> method to perform the actual scaling. Afterwards, the value of <xref:System.Windows.Forms.ContainerControl.AutoScaleDimensions%2A> is updated to avoid progressive scaling. | ||
| ```csharp | ||
| [STAThread] | ||
| static void Main() | ||
| { | ||
| ApplicationConfiguration.Initialize(); | ||
| Application.SetHighDpiMode(HighDpiMode.PerMonitorV2); | ||
| Application.Run(new Form1()); | ||
| } | ||
| ``` | ||
|
|
||
| 01. <xref:System.Windows.Forms.ContainerControl.PerformAutoScale%2A> is also automatically invoked in the following situations: | ||
| > [!TIP] | ||
| > Use the project file approach when possible. This method ensures Visual Studio's designer reflects the DPI settings you've configured. | ||
| - In response to the <xref:System.Windows.Forms.Control.OnFontChanged%2A> event if the scaling mode is <xref:System.Windows.Forms.AutoScaleMode.Font>. | ||
| ## DPI awareness modes | ||
|
|
||
| - When the layout of the container control resumes and a change is detected in the <xref:System.Windows.Forms.ContainerControl.AutoScaleDimensions%2A> or <xref:System.Windows.Forms.ContainerControl.AutoScaleMode%2A> properties. | ||
| The <xref:System.Windows.Forms.HighDpiMode> enumeration defines several DPI awareness modes: | ||
|
|
||
| - As implied above, when a parent <xref:System.Windows.Forms.ContainerControl> is being scaled. Each container control is responsible for scaling its children using its own scaling factors and not the one from its parent container. | ||
| - **PerMonitorV2** (recommended): The application scales dynamically based on the DPI of each monitor. When you move a window between monitors with different DPI settings, Windows Forms automatically rescales the window and its contents. This mode provides the best user experience on systems with multiple monitors. | ||
|
|
||
| 01. Child controls can modify their scaling behavior through several means: | ||
| - **SystemAware**: The application queries the DPI of the primary monitor once at startup and uses that value for all monitors. This mode is simpler but doesn't handle multiple monitors with different DPI settings as well as PerMonitorV2. | ||
|
|
||
| - The <xref:System.Windows.Forms.Control.ScaleChildren%2A> property can be overridden to determine if their child controls should be scaled or not. | ||
| - **PerMonitor**: Similar to PerMonitorV2 but with fewer features. Use PerMonitorV2 instead. | ||
|
|
||
| - The <xref:System.Windows.Forms.Control.GetScaledBounds%2A> method can be overridden to adjust the bounds that the control is scaled to, but not the scaling logic. | ||
| - **DpiUnaware**: The application doesn't scale for DPI and always assumes 100% scaling (96 DPI). Windows might apply bitmap scaling, which can make the application appear blurry. | ||
|
|
||
| - The <xref:System.Windows.Forms.Control.ScaleControl%2A> method can be overridden to change the scaling logic for the current control. | ||
| - **DpiUnawareGdiScaled**: Similar to DpiUnaware but improves the quality of GDI/GDI+ content through enhanced bitmap scaling. | ||
|
|
||
| > [!NOTE] | ||
| > PerMonitorV2 mode is available on Windows 10 Creators Update (version 1703) and later. On earlier Windows versions, the mode falls back to PerMonitor. | ||
| ## Handle DPI changes at runtime | ||
|
|
||
| When your application runs in PerMonitorV2 mode, Windows Forms automatically handles DPI changes when you move windows between monitors. However, you can respond to DPI changes programmatically using these events: | ||
|
|
||
| - <xref:System.Windows.Forms.Form.DpiChanged>: Raised when the DPI of the monitor displaying the form changes. | ||
| - <xref:System.Windows.Forms.Control.DpiChangedBeforeParent>: Raised before a parent control or form handles a DPI change. | ||
| - <xref:System.Windows.Forms.Control.DpiChangedAfterParent>: Raised after a parent control or form handles a DPI change. | ||
|
Comment on lines
+82
to
+84
|
||
|
|
||
| Use these events when you need to perform custom scaling logic or update resources based on the new DPI setting. | ||
|
|
||
| ## Legacy AutoScaleMode | ||
|
|
||
| > [!IMPORTANT] | ||
| > For modern .NET applications, use the `ApplicationHighDpiMode` setting instead of `AutoScaleMode`. The information in this section applies primarily to .NET Framework applications or when maintaining compatibility with legacy code. | ||
| The <xref:System.Windows.Forms.ContainerControl.AutoScaleMode%2A> property provides font-based scaling for .NET Framework applications. This approach is less common in modern .NET applications because DPI-based scaling (using `HighDpiMode`) provides better results. | ||
|
|
||
| When using AutoScaleMode: | ||
|
|
||
| 1. At design time, each <xref:System.Windows.Forms.ContainerControl> records the scaling mode and current resolution in <xref:System.Windows.Forms.ContainerControl.AutoScaleMode%2A> and <xref:System.Windows.Forms.ContainerControl.AutoScaleDimensions%2A>. | ||
|
|
||
| 1. At runtime, the actual resolution is stored in <xref:System.Windows.Forms.ContainerControl.CurrentAutoScaleDimensions%2A>. The <xref:System.Windows.Forms.ContainerControl.AutoScaleFactor%2A> property calculates the ratio between runtime and design-time scaling resolution. | ||
|
|
||
| 1. When the form loads, if <xref:System.Windows.Forms.ContainerControl.CurrentAutoScaleDimensions%2A> and <xref:System.Windows.Forms.ContainerControl.AutoScaleDimensions%2A> differ, <xref:System.Windows.Forms.ContainerControl.PerformAutoScale%2A> scales the control and its children. | ||
|
|
||
| ## Customize scaling behavior | ||
|
|
||
| You can customize how controls scale by overriding these members: | ||
|
|
||
| - <xref:System.Windows.Forms.Control.ScaleChildren%2A>: Determines whether child controls should be scaled. | ||
| - <xref:System.Windows.Forms.Control.GetScaledBounds%2A>: Adjusts the bounds that the control scales to, but not the scaling logic. | ||
| - <xref:System.Windows.Forms.Control.ScaleControl%2A>: Changes the scaling logic for the current control. | ||
|
Comment on lines
+107
to
+109
|
||
|
|
||
| ## Troubleshooting | ||
|
|
||
| If you experience scaling issues: | ||
|
|
||
| - Verify the `ApplicationHighDpiMode` setting in your project file. | ||
| - Ensure you're not mixing DPI awareness modes (for example, setting different modes for base and derived forms). | ||
| - Check that you haven't disabled scaling in application manifests or configuration files. | ||
| - For font-related scaling issues, see [How to: Respond to Font Scheme Changes in a Windows Forms Application](../how-to-respond-to-font-scheme-changes-in-a-windows-forms-application.md). | ||
|
|
||
| ## See also | ||
|
|
||
| - <xref:System.Windows.Forms.ContainerControl.AutoScaleMode%2A> | ||
| - <xref:System.Windows.Forms.Control.Scale%2A> | ||
| - <xref:System.Windows.Forms.ContainerControl.PerformAutoScale%2A> | ||
| - <xref:System.Windows.Forms.ContainerControl.AutoScaleDimensions%2A> | ||
| - <xref:System.Windows.Forms.Application.SetHighDpiMode%2A> | ||
| - <xref:System.Windows.Forms.HighDpiMode> | ||
| - [High DPI support in Windows Forms](../high-dpi-support-in-windows-forms.md) | ||
| - [What's new in Windows Forms for .NET 6](../whats-new/net60.md#project-level-application-settings) | ||
| - [Rendering Controls with Visual Styles](../controls/rendering-controls-with-visual-styles.md) | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The list items in the DPI awareness modes section should end with periods since they exceed three words per the Markdown style guidelines. All five mode descriptions (PerMonitorV2, SystemAware, PerMonitor, DpiUnaware, DpiUnawareGdiScaled) need periods added at the end.