Update Anchor Layout to support high DPI machines.

[dreddy-work]

We have multiple issues reported in WinForms around the anchor layout being problematic on higher DPI scale monitors, irrespective of application DPI mode. This document outlines the changes being made in .NET 8.0 to address these issues along with setting the goal to support all supported application DPI modes in WinForms.

Problem in Scope:
Anchored control’s position with respect to its parent should be able to determine at the design time and would only need to be changed if there were explicit changes in the control’s Bounds or when the control is scaled in response to a DPI changed event. Bounds changes as result of Parent’s bounds change shouldn’t alter control’s relative position in the parent’s rectangle. However, layout in WinForms computes the anchored control’s position every time there are changes to control’s bounds or control’s property change that may impact its position. This is leading to the issues we have been seeing. The following is a source snippet that is being serialized in WinForms designer and added comments show the various events that trigger anchor computations and why they could be wrong or unnecessary.

this.button14.Anchor = (System.Windows.Forms.AnchorStyles.Bottom | System.Windows.Forms.AnchorStyles.Left) // Layout tries to compute anchors with default button14 size and without parent. 
this.button14.Location = new System.Drawing.Point(431, 110); // Layout updates computed anchors for this new bounds, still with default size and no parent.
this.button14.Name = "button14";
this.button14.Size = new System.Drawing.Size(111, 23); // Layout updates computed anchors for this new bounds, still with no parent.
this.Controls.Add(this.button14); // Layout updates computed anchors with parents default size. Which may still be wrong.
this.Size = new System.Drawing.Size(828, 146); // Layout updates computed anchors with parents new size but this size could change based on the Dpi when parent Handle is created.
this.ResumeLayout(false) // Layout updates computed anchors with parents size. Dpi of the screen is still not considered (Handle creations or delayed until control is visible)

The above snippet does not represent the complete set of instances where anchor computations are unnecessary and may hold invalid anchor values. It gets even more complicated when nested UserControls are involved.

Known issues:
We have multiple issues reported here from customers and some of them are direct result of anchor miscalculations. The following are snippets of the category of issues we currently see.

Expected:

Current Behavior:

Proposed solution:

Unnecessary control’s anchors computation is the root cause for many issues reported so far. In this proposal, we are delaying the anchors computation to the specific time in the layout flow - which is when the control’s and its parent’s handles are created. By that time, in the majority of scenarios, the control’s and its parent’s bounds are finalized and the display monitor’s DPI has been applied to them. We also have issues with how we are calculating anchors but, in this proposal, we are simplifying anchor calculations as mentioned in the above pic to help diagnose any future issues.
We may still have cases where developers are forced to create handle explicitly, out of order, but those cases can be handled separately by the application developer for any anchor miscalculations. The following are the events we would be using to compute anchors and replacing the current set of events mentioned in Figure 1 above.

• WmCreate (Create Control)
• OnParentChanged
• SetBounds

Source snippet:

private void WmCreate()
{
   .....
   DefaultLayout.UpdateAnchorInfoV2(this);
}

internal static void UpdateAnchorInfoV2(IArrangedElement element)
 {
     if (!LocalAppContextSwitches.EnableAnchorLayoutV2 || !CommonProperties.GetNeedsAnchorLayout(element))
      {
          return;
      }

      Control control = element as Control;
      Debug.Assert(control != null, "AnchorLayoutV2 and beyond are expected to be used only on Control type");

      if (control is null || control.Parent is null)
       {
          return;
       }

      if (!control.IsHandleCreated || !control.Parent.IsHandleCreated)
       {
          return;
       }

      ComputeAnchorInfo(IArrangedElement element)
  }

Simplifying Anchor calculations:
The current anchor calculation implementation is complicated and appears to have been a result of unnecessary attempts to calculate anchors with invalid bounds. Replacing the current implementation with the one described in Figure 1 above. Following is the source snippet that computes the anchors.

private static void ComputeAnchorInfo(IArrangedElement element)
 {
   AnchorInfo? anchorInfo = GetAnchorInfo(element);
   if (anchorInfo is null)
    {
       anchorInfo = new();
       SetAnchorInfo(element, anchorInfo);
    }

    Rectangle displayRect = element.Container.DisplayRectangle;
    Rectangle elementBounds = element.Bounds;

    int x = elementBounds.X;
    int y = elementBounds.Y;

    anchorInfo.Left = x;
    anchorInfo.Top = y;

    anchorInfo.Right = displayRect.Width - (x + elementBounds.Width);
    anchorInfo.Bottom = displayRect.Height - (y + elementBounds.Height);
 }

Risk mitigation:
Layout in general is complex and could impact every component in the WinForms. In order to reduce the potential risk and provide backward compatibility, This changes are quirked under switch System.Windows.Forms.EnableAnchorLayoutV2. These changes are by default on for new/migrating applications targeting .NET 8.0 but the developers can control this by setting the above mentioned flag to false in the runtimeconfig.template.json for the application.
Snippet for runtimeconfig.template.json:

{
  "configProperties": {
    "System.Windows.Forms.EnableAnchorLayoutV2": true
  }
}

Fixes #8090
Fixes #8088

Microsoft Reviewers: Open in CodeFlow

[JeremyKuhne]

Mostly nits. If you can try to update to interpolated strings wherever you're touching code it helps avoid extra work / allocations. They are significantly better everywhere and Debug statements will completely skip forming the string if conditions aren't met.

[dreddy-work]

Changing name to anchor-layout-changes-in-net80.md when renaming it on doc PR. Intentionally underscored here.

[RussKie]

❗ This link is still incorrect.

addressed.

[RussKie]

diito

[RussKie]

ditto

[RussKie]

A friendly reminder to raise a breaking doc in https://github.com/dotnet/docs/

[dreddy-work]

dotnet/docs#32145