Fixes #3469, #3473, #3482 - Dim.Auto fixes and Pos/Dim refactor to support TGD

Terminal.Gui/Text/TextFormatter.cs

@@ -50,7 +50,7 @@ public bool AutoSize
         }
     }
 
-    private Size GetAutoSize ()
+    internal Size GetAutoSize ()
     {
         Size size = CalcRect (0, 0, Text, Direction, TabWidth).Size;
         return size with

Terminal.Gui/View/Adornment/Adornment.cs

@@ -242,7 +242,7 @@ public override bool Contains (in Point location)
         return base.OnMouseEnter (mouseEvent);
     }
 
-    /// <inheritdoc/>
+    /// <inheritdoc/>   
     protected internal override bool OnMouseLeave (MouseEvent mouseEvent)
     {
         // Invert Normal

Terminal.Gui/View/Layout/AddOrSubtract.cs

@@ -0,0 +1,20 @@
+using Terminal.Gui.Analyzers.Internal.Attributes;
+
+namespace Terminal.Gui;
+
+/// <summary>
+///     Describes whether an operation should add or subtract values.
+/// </summary>
+[GenerateEnumExtensionMethods]
+public enum AddOrSubtract
+{
+    /// <summary>
+    ///     The operation should use addition.
+    /// </summary>
+    Add = 0,
+
+    /// <summary>
+    ///     The operation should use subtraction.
+    /// </summary>
+    Subtract = 1
+}

Terminal.Gui/View/Layout/Dim.cs

@@ -0,0 +1,273 @@
+#nullable enable
+using System.Diagnostics;
+
+namespace Terminal.Gui;
+
+/// <summary>
+///     <para>
+///         A Dim object describes the dimensions of a <see cref="View"/>. Dim is the type of the
+///         <see cref="View.Width"/> and <see cref="View.Height"/> properties of <see cref="View"/>. Dim objects enable
+///         Computed Layout (see <see cref="LayoutStyle.Computed"/>) to automatically manage the dimensions of a view.
+///     </para>
+///     <para>
+///         Integer values are implicitly convertible to an absolute <see cref="Dim"/>. These objects are created using
+///         the static methods described below. The <see cref="Dim"/> objects can be combined with the addition and
+///         subtraction operators.
+///     </para>
+/// </summary>
+/// <remarks>
+///     <para>
+///         <list type="table">
+///             <listheader>
+///                 <term>Dim Object</term> <description>Description</description>
+///             </listheader>
+///             <item>
+///                 <term>
+///                     <see cref="Dim.Auto"/>
+///                 </term>
+///                 <description>
+///                     Creates a <see cref="Dim"/> object that automatically sizes the view to fit
+///                     the view's Text, SubViews, or ContentArea.
+///                 </description>
+///             </item>
+///             <item>
+///                 <term>
+///                     <see cref="Func"/>
+///                 </term>
+///                 <description>
+///                     Creates a <see cref="Dim"/> object that computes the dimension by executing the provided
+///                     function. The function will be called every time the dimension is needed.
+///                 </description>
+///             </item>
+///             <item>
+///                 <term>
+///                     <see cref="Dim.Percent(int, DimPercentMode)"/>
+///                 </term>
+///                 <description>
+///                     Creates a <see cref="Dim"/> object that is a percentage of the width or height of the
+///                     SuperView.
+///                 </description>
+///             </item>
+///             <item>
+///                 <term>
+///                     <see cref="Dim.Fill(int)"/>
+///                 </term>
+///                 <description>
+///                     Creates a <see cref="Dim"/> object that fills the dimension from the View's X position
+///                     to the end of the super view's width, leaving the specified number of columns for a margin.
+///                 </description>
+///             </item>
+///             <item>
+///                 <term>
+///                     <see cref="Dim.Width(View)"/>
+///                 </term>
+///                 <description>
+///                     Creates a <see cref="Dim"/> object that tracks the Width of the specified
+///                     <see cref="View"/>.
+///                 </description>
+///             </item>
+///             <item>
+///                 <term>
+///                     <see cref="Dim.Height(View)"/>
+///                 </term>
+///                 <description>
+///                     Creates a <see cref="Dim"/> object that tracks the Height of the specified
+///                     <see cref="View"/>.
+///                 </description>
+///             </item>
+///         </list>
+///     </para>
+///     <para></para>
+/// </remarks>
+public abstract class Dim
+{
+    #region static Dim creation methods
+
+    /// <summary>Creates an Absolute <see cref="Dim"/> from the specified integer value.</summary>
+    /// <returns>The Absolute <see cref="Dim"/>.</returns>
+    /// <param name="size">The value to convert to the <see cref="Dim"/>.</param>
+    public static Dim? Absolute (int size) { return new DimAbsolute (size); }
+
+    /// <summary>
+    ///     Creates a <see cref="Dim"/> object that automatically sizes the view to fit all the view's Content, Subviews, and/or Text.
+    /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         See <see cref="DimAutoStyle"/>.
+    ///     </para>
+    /// </remarks>
+    /// <example>
+    ///     This initializes a <see cref="View"/> with two SubViews. The view will be automatically sized to fit the two
+    ///     SubViews.
+    ///     <code>
+    /// var button = new Button () { Text = "Click Me!", X = 1, Y = 1, Width = 10, Height = 1 };
+    /// var textField = new TextField { Text = "Type here", X = 1, Y = 2, Width = 20, Height = 1 };
+    /// var view = new Window () { Title = "MyWindow", X = 0, Y = 0, Width = Dim.Auto (), Height = Dim.Auto () };
+    /// view.Add (button, textField);
+    /// </code>
+    /// </example>
+    /// <returns>The <see cref="Dim"/> object.</returns>
+    /// <param name="style">
+    ///     Specifies how <see cref="Dim.Auto"/> will compute the dimension. The default is <see cref="DimAutoStyle.Auto"/>.
+    /// </param>
+    /// <param name="minimumContentDim">The minimum dimension the View's ContentSize will be constrained to.</param>
+    /// <param name="maximumContentDim">The maximum dimension the View's ContentSize will be fit to. NOT CURRENTLY SUPPORTED.</param>
+    public static Dim? Auto (DimAutoStyle style = DimAutoStyle.Auto, Dim? minimumContentDim = null, Dim? maximumContentDim = null)
+    {
+        if (maximumContentDim is { })
+        {
+            Debug.WriteLine (@"WARNING: maximumContentDim is not fully implemented.");
+        }
+
+        return new DimAuto ()
+        {
+            MinimumContentDim = minimumContentDim,
+            MaximumContentDim = maximumContentDim,
+            Style = style
+        };
+    }
+
+    /// <summary>
+    ///     Creates a <see cref="Dim"/> object that fills the dimension, leaving the specified margin.
+    /// </summary>
+    /// <returns>The Fill dimension.</returns>
+    /// <param name="margin">Margin to use.</param>
+    public static Dim? Fill (int margin = 0) { return new DimFill (margin); }
+
+    /// <summary>
+    ///     Creates a function <see cref="Dim"/> object that computes the dimension by executing the provided function.
+    ///     The function will be called every time the dimension is needed.
+    /// </summary>
+    /// <param name="function">The function to be executed.</param>
+    /// <returns>The <see cref="Dim"/> returned from the function.</returns>
+    public static Dim Func (Func<int> function) { return new DimFunc (function); }
+
+    /// <summary>Creates a <see cref="Dim"/> object that tracks the Height of the specified <see cref="View"/>.</summary>
+    /// <returns>The height <see cref="Dim"/> of the other <see cref="View"/>.</returns>
+    /// <param name="view">The view that will be tracked.</param>
+    public static Dim Height (View view) { return new DimView (view, Dimension.Height); }
+
+    /// <summary>Creates a percentage <see cref="Dim"/> object that is a percentage of the width or height of the SuperView.</summary>
+    /// <returns>The percent <see cref="Dim"/> object.</returns>
+    /// <param name="percent">A value between 0 and 100 representing the percentage.</param>
+    /// <param name="mode"></param>
+    /// <example>
+    ///     This initializes a <see cref="TextField"/> that will be centered horizontally, is 50% of the way down, is 30% the
+    ///     height,
+    ///     and is 80% the width of the SuperView.
+    ///     <code>
+    ///  var textView = new TextField {
+    ///     X = Pos.Center (),
+    ///     Y = Pos.Percent (50),
+    ///     Width = Dim.Percent (80),
+    ///     Height = Dim.Percent (30),
+    ///  };
+    ///  </code>
+    /// </example>
+    public static Dim? Percent (int percent, DimPercentMode mode = DimPercentMode.ContentSize)
+    {
+        if (percent is < 0 /*or > 100*/)
+        {
+            throw new ArgumentException ("Percent value must be positive.");
+        }
+
+        return new DimPercent (percent, mode);
+    }
+
+    /// <summary>Creates a <see cref="Dim"/> object that tracks the Width of the specified <see cref="View"/>.</summary>
+    /// <returns>The width <see cref="Dim"/> of the other <see cref="View"/>.</returns>
+    /// <param name="view">The view that will be tracked.</param>
+    public static Dim Width (View view) { return new DimView (view, Dimension.Width); }
+
+    #endregion static Dim creation methods
+
+    #region virtual methods
+
+    /// <summary>
+    ///     Gets a dimension that is anchored to a certain point in the layout.
+    ///     This method is typically used internally by the layout system to determine the size of a View.
+    /// </summary>
+    /// <param name="size">The width of the area where the View is being sized (Superview.ContentSize).</param>
+    /// <returns>
+    ///     An integer representing the calculated dimension. The way this dimension is calculated depends on the specific
+    ///     subclass of Dim that is used. For example, DimAbsolute returns a fixed dimension, DimFactor returns a
+    ///     dimension that is a certain percentage of the super view's size, and so on.
+    /// </returns>
+    internal virtual int GetAnchor (int size) { return 0; }
+
+    /// <summary>
+    ///     Calculates and returns the dimension of a <see cref="View"/> object. It takes into account the location of the
+    ///     <see cref="View"/>, it's SuperView's ContentSize, and whether it should automatically adjust its size based on its
+    ///     content.
+    /// </summary>
+    /// <param name="location">
+    ///     The starting point from where the size calculation begins. It could be the left edge for width calculation or the
+    ///     top edge for height calculation.
+    /// </param>
+    /// <param name="superviewContentSize">The size of the SuperView's content. It could be width or height.</param>
+    /// <param name="us">The View that holds this Pos object.</param>
+    /// <param name="dimension">Width or Height</param>
+    /// <returns>
+    ///     The calculated size of the View. The way this size is calculated depends on the specific subclass of Dim that
+    ///     is used.
+    /// </returns>
+    internal virtual int Calculate (int location, int superviewContentSize, View us, Dimension dimension)
+    {
+        return Math.Max (GetAnchor (superviewContentSize - location), 0);
+    }
+
+    /// <summary>
+    ///     Diagnostics API to determine if this Dim object references other views.
+    /// </summary>
+    /// <returns></returns>
+    internal virtual bool ReferencesOtherViews () { return false; }
+
+    #endregion virtual methods
+
+    #region operators
+
+    /// <summary>Adds a <see cref="Dim"/> to a <see cref="Dim"/>, yielding a new <see cref="Dim"/>.</summary>
+    /// <param name="left">The first <see cref="Dim"/> to add.</param>
+    /// <param name="right">The second <see cref="Dim"/> to add.</param>
+    /// <returns>The <see cref="Dim"/> that is the sum of the values of <c>left</c> and <c>right</c>.</returns>
+    public static Dim operator + (Dim? left, Dim? right)
+    {
+        if (left is DimAbsolute && right is DimAbsolute)
+        {
+            return new DimAbsolute (left.GetAnchor (0) + right.GetAnchor (0));
+        }
+
+        var newDim = new DimCombine (AddOrSubtract.Add, left, right);
+        (left as DimView)?.Target.SetNeedsLayout ();
+
+        return newDim;
+    }
+
+    /// <summary>Creates an Absolute <see cref="Dim"/> from the specified integer value.</summary>
+    /// <returns>The Absolute <see cref="Dim"/>.</returns>
+    /// <param name="n">The value to convert to the pos.</param>
+    public static implicit operator Dim (int n) { return new DimAbsolute (n); }
+
+    /// <summary>
+    ///     Subtracts a <see cref="Dim"/> from a <see cref="Dim"/>, yielding a new
+    ///     <see cref="Dim"/>.
+    /// </summary>
+    /// <param name="left">The <see cref="Dim"/> to subtract from (the minuend).</param>
+    /// <param name="right">The <see cref="Dim"/> to subtract (the subtrahend).</param>
+    /// <returns>The <see cref="Dim"/> that is the <c>left</c> minus <c>right</c>.</returns>
+    public static Dim operator - (Dim? left, Dim? right)
+    {
+        if (left is DimAbsolute && right is DimAbsolute)
+        {
+            return new DimAbsolute (left.GetAnchor (0) - right.GetAnchor (0));
+        }
+
+        var newDim = new DimCombine (AddOrSubtract.Subtract, left, right);
+        (left as DimView)?.Target.SetNeedsLayout ();
+
+        return newDim;
+    }
+
+    #endregion operators
+
+}

Terminal.Gui/View/Layout/DimAbsolute.cs

@@ -0,0 +1,36 @@
+#nullable enable
+namespace Terminal.Gui;
+
+/// <summary>
+///     Represents a dimension that is a fixed size.
+/// </summary>
+/// <remarks>
+///     <para>
+///         This is a low-level API that is typically used internally by the layout system. Use the various static
+///         methods on the <see cref="Dim"/> class to create <see cref="Dim"/> objects instead.
+///     </para>
+/// </remarks>
+/// <param name="size"></param>
+public class DimAbsolute (int size) : Dim
+{
+    /// <inheritdoc/>
+    public override bool Equals (object? other) { return other is DimAbsolute abs && abs.Size == Size; }
+
+    /// <inheritdoc/>
+    public override int GetHashCode () { return Size.GetHashCode (); }
+
+    /// <summary>
+    ///     Gets the size of the dimension.
+    /// </summary>
+    public int Size { get; } = size;
+
+    /// <inheritdoc/>
+    public override string ToString () { return $"Absolute({Size})"; }
+
+    internal override int GetAnchor (int size) { return Size; }
+
+    internal override int Calculate (int location, int superviewContentSize, View us, Dimension dimension)
+    {
+        return Math.Max (GetAnchor (0), 0);
+    }
+}