Fixes #4368 - cwppropertyhelper (#4369)

* Refactor newinv2.md deep dive doc

Terminal.Gui v2 introduces a transformative redesign, simplifying the library's architecture and improving maintainability. Key changes include:

- Added TrueColor support with 24-bit RGB handling.
- Introduced `Adornment` framework for borders, padding, and margins.
- Enhanced Unicode and wide character support for internationalization.
- Added `LineCanvas` for drawing lines and shapes with box-drawing characters.
- Simplified API by consolidating redundant methods and aligning with modern .NET standards.
- Introduced `ConfigurationManager` for user-customizable themes and text styles.
- Improved scrolling with `Viewport` and integrated `ScrollBar`.
- Added new layout features like `Dim.Auto`, `Pos.AnchorEnd`, and `Pos.Align`.
- Overhauled keyboard and mouse APIs for better input handling.
- Introduced new views (e.g., `DatePicker`, `ColorPicker`, `GraphView`) and enhanced existing ones.
- Added Sixel image support for rendering graphics in compatible terminals.
- Ensured AOT compatibility for improved deployment and performance.

This update lays the foundation for building modern, user-friendly terminal applications.

* Fixes #4368 - Clarify and Fix CWPPropertyHelper Property Change Workflow

Refactor ChangeProperty method for clarity and flexibility

Updated the `<param>` documentation for `currentValue` to clarify its behavior. Changed the `currentValue` parameter to be passed by reference (`ref`) to allow direct updates to the caller's variable. Made the `onChanging` delegate nullable and added a null check to prevent potential exceptions. Moved the `cancelled` variable inside the null-check block for `onChanging` to simplify logic. Explicitly updated `currentValue` to `finalValue` after the `doWork` action to ensure consistency. These changes improve the method's robustness, flexibility, and clarity.

* Refactor ChangeProperty calls to use ref parameters

Updated `CWPPropertyHelper.ChangeProperty` calls in `View.Drawing.Scheme.cs` and `View.Layout.cs` to pass fields as `ref` parameters. This ensures direct modification of fields, improving property update handling.

Affected properties:
- `_schemeName` and `_scheme` in `View.Drawing.Scheme.cs`
- `_height` and `_width` in `View.Layout.cs`

Property change notification logic remains unchanged. This refactor enhances maintainability and correctness without introducing new functionality.

Terminal.Gui/App/CWP/CWPPropertyHelper.cs

@@ -22,7 +22,10 @@ public static class CWPPropertyHelper
     ///     The type of the property value, which may be a nullable reference type (e.g., <see cref="string"/>
     ///     ?).
     /// </typeparam>
-    /// <param name="currentValue">The current property value, which may be null for nullable types.</param>
+    /// <param name="currentValue">
+    ///     Reference to the current property value, which may be null for nullable types. If the change is not cancelled, this
+    ///     will be set to <paramref name="finalValue"/>.
+    /// </param>
     /// <param name="newValue">The proposed new property value, which may be null for nullable types.</param>
     /// <param name="onChanging">The virtual method invoked before the change, returning true to cancel.</param>
     /// <param name="changingEvent">The pre-change event raised to allow modification or cancellation.</param>
@@ -52,9 +55,9 @@ public static class CWPPropertyHelper
     ///     </code>
     /// </example>
     public static bool ChangeProperty<T> (
-        T currentValue,
+        ref T currentValue,
         T newValue,
-        Func<ValueChangingEventArgs<T>, bool> onChanging,
+        Func<ValueChangingEventArgs<T>, bool>? onChanging,
         EventHandler<ValueChangingEventArgs<T>>? changingEvent,
         Action<T> doWork,
         Action<ValueChangedEventArgs<T>>? onChanged,
@@ -70,13 +73,17 @@ public static class CWPPropertyHelper
         }
 
         ValueChangingEventArgs<T> args = new (currentValue, newValue);
-        bool cancelled = onChanging (args) || args.Handled;
 
-        if (cancelled)
+        if (onChanging is { })
         {
-            finalValue = currentValue;
+            bool cancelled = onChanging (args) || args.Handled;
 
-            return false;
+            if (cancelled)
+            {
+                finalValue = currentValue;
+
+                return false;
+            }
         }
 
         changingEvent?.Invoke (null, args);
@@ -100,6 +107,7 @@ public static class CWPPropertyHelper
         doWork (finalValue);
         
         ValueChangedEventArgs<T> changedArgs = new (currentValue, finalValue);
+        currentValue = finalValue;
         onChanged?.Invoke (changedArgs);
         changedEvent?.Invoke (null, changedArgs);
 

Terminal.Gui/ViewBase/View.Drawing.Scheme.cs

@@ -26,7 +26,7 @@ public partial class View
         set
         {
             CWPPropertyHelper.ChangeProperty (
-                                              _schemeName,
+                                              ref _schemeName,
                                               value,
                                               OnSchemeNameChanging,
                                               SchemeNameChanging,
@@ -209,7 +209,7 @@ public partial class View
     public bool SetScheme (Scheme? scheme)
     {
         return CWPPropertyHelper.ChangeProperty (
-                                                 _scheme,
+                                                 ref _scheme,
                                                  scheme,
                                                  OnSettingScheme,
                                                  SchemeChanging,

Terminal.Gui/ViewBase/View.Layout.cs

@@ -328,7 +328,7 @@ public partial class View // Layout APIs
         set
         {
             CWPPropertyHelper.ChangeProperty (
-                                              _height,
+                                              ref _height,
                                               value,
                                               OnHeightChanging,
                                               HeightChanging,
@@ -416,7 +416,7 @@ public partial class View // Layout APIs
         set
         {
             CWPPropertyHelper.ChangeProperty (
-                                              _width,
+                                              ref _width,
                                               value,
                                               OnWidthChanging,
                                               WidthChanging,