Do final code-style pass to meet all standards and improve copilot instructions.

Author: KlausLoeffelmann

.github/AI-Prompts/GDI-Refactoring/AIP-cache_pens-and_brushes.md

@@ -215,8 +215,11 @@
 
 - **Use `var` only for complex types when type is apparent from context**
   ```csharp
-  var control = new Button();              // OK - type is obvious
-  var items = GetComplexCollection();      // OK - long type name
+  var control = new Button();              // OK - type is obvious, but better is:
+  Button control = new();                  // Preferred
+  
+  // OK - long type name
+  var items = GetComplexCollectionWithRidiculousLongTypeName();
   int primitiveValue = 42;                 // Required for primitives
   ```
 
@@ -239,6 +242,11 @@
   ```csharp
   private static readonly int s_defaultBorderWidth = 1;
   ```
+An exception to this rule is when the field is attributed with `[ThreadStatic]`, in which case the prefix should be `t_`:
+  ```csharp
+  [ThreadStatic]
+  private static int t_threadLocalValue;
+  ```
 
 - **Prefix private/internal instance fields with `_`** (suggestion level)
   ```csharp
@@ -286,7 +294,7 @@
   private bool IsVisible() => Visible && Parent?.Visible == true;
   ```
 
-- For longer expressions, use line breaks with proper alignment:
+For longer expressions, use line breaks with proper alignment:
   ```csharp
   internal int SomeFooIntegerProperty =>
       _someFooIntegerProperty;
@@ -295,6 +303,19 @@
       size.Width > 0 
       && size.Height > 0;
   ```
+**IMPORTANT**
+
+In C#, `public Foo FooInstance => new Foo();` and `public Foo FooInstance { get; } = new Foo();` are NOT interchangeable.
+
+* The first is an expression-bodied property that returns a new value each time it is accessed.
+* The second is a read-only auto-property with initializer that returns the same value every time, created once.
+
+When editing, generating, or suggesting C# properties, always maintain the original intent:
+
+* Use an expression-bodied property (`=>`) for computed or dynamic values.
+* Use an auto-property with initializer (`{ get; } = ...`) for stored, initialized-once values.
+
+Never "correct" or convert one style to the other unless you are certain the semantic behavior is intended to change because it was wrong with 100% confidence to begin with. If you encounter a case, where you have a expression-bodied property that returns a new instance, and you encounter this in a code review, you should add a comment explaining why this is intended, and that it is not a mistake.
 
 ### 1.5 Error Handling and Argument Validation
 
@@ -345,19 +366,38 @@
 - **Handle platform-specific code appropriately**
   ```csharp
   [SupportedOSPlatform("windows")]
-  private void WindowsSpecificMethod() { ... }
+  private void WindowsSpecificMethod() 
+  { 
+      ... 
+  }
   ```
 
 - **Use proper disposal patterns**
-  ```csharp
-  using var brush = new SolidBrush(Color.Red);  // Simple using for single resources
-  
-  // Traditional using for complex scenarios
-  using (Graphics g = CreateGraphics())
-  {
-      // Drawing operations
-  }
-  ```
+Prefer the modern C# “using declaration” syntax (using var ...) over the traditional using statement block.
+Use:
+
+```csharp
+using var brush = backColor.GetCachedSolidBrushScope();
+```
+
+instead of:
+
+```csharp
+using (SolidBrushCache.Scope brush = backColor.GetCachedSolidBrushScope())
+{
+    // ...
+}
+```
+
+This makes code more concise, reduces nesting, and improves readability. Only use the older style if you need to limit the scope of the variable to a smaller section within a larger method, or when the using var pattern is not supported. **Note**, that if you use `using` with the type name over `var` for new instances that you can omit the type name after the `new` like:
+
+```csharp
+using Pen focusPen = new(focusColor) // Use 'using' with type name and omit type after 'new'
+{
+    Width = 1.0f,
+    DashStyle = DashStyle.Dot
+};
+```
 
 ### 1.8 XML Documentation Standards
 
@@ -402,6 +442,7 @@
 ### 1.10 Magic Numbers
 
 - **Avoid magic numbers**: Use named constants or enums instead of hard-coded values. This improves readability and maintainability.
+
   ```csharp
   // Avoid magic numbers
   const int MaxItems = 100;
@@ -451,6 +492,9 @@
   }
   ```
 
+  Note: If a code line for which these empty-line rules apply has a comment on top of it, the empty line should be placed before the comment, if there isn't one. And of course, NEVER comment that an empty lines need to be inserted at a spot, which would defeat the purpose of the empty line.
+  
+
 ### 1.12 Refactoring of existing comments
 
 - **Refactor existing comments**: When refactoring code, also consider updating or removing outdated comments. Comments should accurately reflect the current state of the code and its purpose. Avoid/rephrase inappropriate comments or microaggressions.

.github/copilot-instructions.md

@@ -69,7 +69,8 @@ protected ButtonBase()
                 | ControlStyles.ResizeRedraw
                 | ControlStyles.OptimizedDoubleBuffer
                 // We gain about 2% in painting by avoiding extra GetWindowText calls
-                | ControlStyles.CacheText,
+                | ControlStyles.CacheText
+                | ControlStyles.StandardClick,
             true);
 
         // This class overrides GetPreferredSizeCore, let Control automatically cache the result

src/System.Windows.Forms/System/Windows/Forms/Controls/Buttons/ButtonBase.cs

@@ -29,13 +29,15 @@ internal override void PaintUp(PaintEventArgs e, CheckState state)
     {
         try
         {
-            var smoothingMode = e.Graphics.SmoothingMode;
-            e.Graphics.SmoothingMode = Drawing.Drawing2D.SmoothingMode.AntiAlias;
+            // Use GraphicsInternal for better performance (GDI+ best practice)
+            var g = e.GraphicsInternal;
+            var smoothingMode = g.SmoothingMode;
+            g.SmoothingMode = Drawing.Drawing2D.SmoothingMode.AntiAlias;
 
             LayoutData layout = CommonLayout().Layout();
 
             ButtonDarkModeRenderer.RenderButton(
-                e.Graphics,
+                g,
                 Control.ClientRectangle,
                 Control.FlatStyle,
                 ToPushButtonState(state, Control.Enabled),
@@ -52,7 +54,7 @@ internal override void PaintUp(PaintEventArgs e, CheckState state)
                     drawFocus: false)
             );
 
-            e.Graphics.SmoothingMode = smoothingMode;
+            g.SmoothingMode = smoothingMode;
         }
         catch (Exception)
         {
@@ -65,13 +67,14 @@ internal override void PaintDown(PaintEventArgs e, CheckState state)
     {
         try
         {
-            // Set the smoothing mode to AntiAlias for better rendering quality
-            var smoothingMode = e.Graphics.SmoothingMode;
-            e.Graphics.SmoothingMode = Drawing.Drawing2D.SmoothingMode.AntiAlias;
+            // Use GraphicsInternal for better performance (GDI+ best practice)
+            var g = e.GraphicsInternal;
+            var smoothingMode = g.SmoothingMode;
+            g.SmoothingMode = Drawing.Drawing2D.SmoothingMode.AntiAlias;
 
             LayoutData layout = CommonLayout().Layout();
             ButtonDarkModeRenderer.RenderButton(
-                e.Graphics,
+                g,
                 Control.ClientRectangle,
                 Control.FlatStyle,
                 PushButtonState.Pressed,
@@ -88,8 +91,7 @@ internal override void PaintDown(PaintEventArgs e, CheckState state)
                     drawFocus: false)
             );
 
-            // Restore the original smoothing mode
-            e.Graphics.SmoothingMode = smoothingMode;
+            g.SmoothingMode = smoothingMode;
         }
         catch (Exception)
         {
@@ -102,13 +104,14 @@ internal override void PaintOver(PaintEventArgs e, CheckState state)
     {
         try
         {
-            // Set the smoothing mode to AntiAlias for better rendering quality
-            var smoothingMode = e.Graphics.SmoothingMode;
-            e.Graphics.SmoothingMode = Drawing.Drawing2D.SmoothingMode.AntiAlias;
+            // Use GraphicsInternal for better performance (GDI+ best practice)
+            var g = e.GraphicsInternal;
+            var smoothingMode = g.SmoothingMode;
+            g.SmoothingMode = Drawing.Drawing2D.SmoothingMode.AntiAlias;
 
             LayoutData layout = CommonLayout().Layout();
             ButtonDarkModeRenderer.RenderButton(
-                e.Graphics,
+                g,
                 Control.ClientRectangle,
                 Control.FlatStyle,
                 PushButtonState.Hot,
@@ -125,16 +128,18 @@ internal override void PaintOver(PaintEventArgs e, CheckState state)
                     drawFocus: false)
             );
 
-            // Restore the original smoothing mode
-            e.Graphics.SmoothingMode = smoothingMode;
+            g.SmoothingMode = smoothingMode;
         }
         catch (Exception ex)
         {
             Debug.Assert(false, $"Exception in PaintOver: {ex.Message}");
         }
     }
 
-    protected override LayoutOptions Layout(PaintEventArgs e) => CommonLayout();
+    protected override LayoutOptions Layout(PaintEventArgs e)
+    {
+        return CommonLayout();
+    }
 
     private new LayoutOptions CommonLayout()
     {

src/System.Windows.Forms/System/Windows/Forms/Controls/Buttons/ButtonInternal/DarkMode/ButtonDarkModeAdapter.cs

@@ -20,6 +20,8 @@ internal abstract partial class ButtonDarkModeRendererBase : IButtonRenderer
     /// <param name="graphics">Graphics context to draw on</param>
     private static void ClearBackground(Graphics graphics, Color parentBackgroundColor)
     {
+        ArgumentNullException.ThrowIfNull(graphics);
+
         graphics.Clear(parentBackgroundColor);
     }
 
@@ -57,12 +59,6 @@ public void RenderButton(
         // Draw button background and get content bounds
         Rectangle contentBounds = DrawButtonBackground(graphics, paddedBounds, state, isDefault);
 
-        // Offset content bounds for Popup style when button is pressed
-        // if (flatStyle == FlatStyle.Popup && state == PushButtonState.Pressed)
-        // {
-        //    contentBounds.Offset(1, 1);
-        // }
-
         // Paint image and field using the provided delegates
         paintImage(contentBounds);
 
@@ -72,12 +68,6 @@ public void RenderButton(
             false);
 
         DrawFocusIndicator(graphics, bounds, isDefault);
-
-        // if (focused && showFocusCues)
-        // {
-        //    // Draw focus indicator for other styles
-        //    renderer.DrawFocusIndicator(graphics, contentBounds, isDefault);
-        // }
     }
 
     public abstract Rectangle DrawButtonBackground(Graphics graphics, Rectangle bounds, PushButtonState state, bool isDefault);

src/System.Windows.Forms/System/Windows/Forms/Controls/Buttons/ButtonInternal/DarkMode/ButtonDarkModeRendererBase.cs

@@ -6,6 +6,7 @@ namespace System.Windows.Forms.ButtonInternal;
 internal static class DarkModeAdapterFactory
 {
 #pragma warning disable WFO5001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+
     public static ButtonBaseAdapter CreateFlatAdapter(ButtonBase control)
     {
         return Application.IsDarkModeEnabled
@@ -26,5 +27,6 @@ public static ButtonBaseAdapter CreatePopupAdapter(ButtonBase control)
             ? new ButtonDarkModeAdapter(control)
             : new ButtonPopupAdapter(control);
     }
+
 #pragma warning restore WFO5001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
 }

src/System.Windows.Forms/System/Windows/Forms/Controls/Buttons/ButtonInternal/DarkMode/DarkModeAdapterFactory.cs

@@ -137,7 +137,6 @@ private static void DrawButtonBorder(Graphics graphics, Rectangle bounds, PushBu
         }
 
         // For other states, draw a border with appropriate thickness
-        // For pressed state, draw a darker border
         borderColor = isDefault
             ? IButtonRenderer.DarkModeButtonColors.DefaultSingleBorderColor
             : IButtonRenderer.DarkModeButtonColors.SingleBorderColor;