namespace Terminal.Gui;
///
/// Indicates the side for operations.
///
public enum Side
{
///
/// The left (X) side of the view.
///
Left = 0,
///
/// The top (Y) side of the view.
///
Top = 1,
///
/// The right (X + Width) side of the view.
///
Right = 2,
///
/// The bottom (Y + Height) side of the view.
///
Bottom = 3
}
///
/// Describes the position of a which can be an absolute value, a percentage, centered, or
/// relative to the ending dimension. Integer values are implicitly convertible to an absolute . These
/// objects are created using the static methods Percent, AnchorEnd, and Center. The objects can be
/// combined with the addition and subtraction operators.
///
///
/// Use the objects on the X or Y properties of a view to control the position.
///
/// These can be used to set the absolute position, when merely assigning an integer value (via the implicit
/// integer to conversion), and they can be combined to produce more useful layouts, like:
/// Pos.Center - 3, which would shift the position of the 3 characters to the left after
/// centering for example.
///
///
/// Reference coordinates of another view by using the methods Left(View), Right(View), Bottom(View), Top(View).
/// The X(View) and Y(View) are aliases to Left(View) and Top(View) respectively.
///
///
///
///
/// Pos Object Description
///
/// -
///
///
///
///
/// Creates a object that computes the position by executing the provided
/// function. The function will be called every time the position is needed.
///
///
/// -
///
///
///
///
/// Creates a object that is a percentage of the width or height of the
/// SuperView.
///
///
/// -
///
///
///
///
/// Creates a object that is anchored to the end (right side or bottom) of
/// the dimension, useful to flush the layout from the right or bottom.
///
///
/// -
///
///
///
/// Creates a object that can be used to center the .
///
/// -
///
///
///
///
/// Creates a object that is an absolute position based on the specified
/// integer value.
///
///
/// -
///
///
///
///
/// Creates a object that tracks the Left (X) position of the specified
/// .
///
///
/// -
///
///
///
///
/// Creates a object that tracks the Left (X) position of the specified
/// .
///
///
/// -
///
///
///
///
/// Creates a object that tracks the Top (Y) position of the specified
/// .
///
///
/// -
///
///
///
///
/// Creates a object that tracks the Top (Y) position of the specified
/// .
///
///
/// -
///
///
///
///
/// Creates a object that tracks the Right (X+Width) coordinate of the
/// specified .
///
///
/// -
///
///
///
///
/// Creates a object that tracks the Bottom (Y+Height) coordinate of the
/// specified
///
///
///
///
///
public class Pos
{
#region static Pos creation methods
/// Creates a object that is an absolute position based on the specified integer value.
/// The Absolute .
/// The value to convert to the .
public static Pos Absolute (int position) { return new PosAbsolute (position); }
///
/// Creates a object that is anchored to the end (right side or
/// bottom) of the SuperView's Content Area, minus the respective size of the View. This is equivalent to using
/// ,
/// with an offset equivalent to the View's respective dimension.
///
/// The object anchored to the end (the bottom or the right side) minus the View's dimension.
///
/// This sample shows how align a to the bottom-right the SuperView.
///
/// anchorButton.X = Pos.AnchorEnd ();
/// anchorButton.Y = Pos.AnchorEnd ();
///
///
public static Pos AnchorEnd () { return new PosAnchorEnd (); }
///
/// Creates a object that is anchored to the end (right side or bottom) of the SuperView's Content
/// Area,
/// useful to flush the layout from the right or bottom. See also , which uses the view
/// dimension to ensure the view is fully visible.
///
/// The object anchored to the end (the bottom or the right side).
/// The view will be shifted left or up by the amount specified.
///
/// This sample shows how align a 10 column wide to the bottom-right the SuperView.
///
/// anchorButton.X = Pos.AnchorEnd (10);
/// anchorButton.Y = 1
///
///
public static Pos AnchorEnd (int offset)
{
if (offset < 0)
{
throw new ArgumentException (@"Must be positive", nameof (offset));
}
return new PosAnchorEnd (offset);
}
/// Creates a object that can be used to center the .
/// The center Pos.
///
/// This creates a centered horizontally, is 50% of the way down, is 30% the height, and
/// is 80% the width of the it added to.
///
/// var textView = new TextView () {
/// X = Pos.Center (),
/// Y = Pos.Percent (50),
/// Width = Dim.Percent (80),
/// Height = Dim.Percent (30),
/// };
///
///
public static Pos Center () { return new PosCenter (); }
///
/// Creates a object that computes the position by executing the provided function. The function
/// will be called every time the position is needed.
///
/// The function to be executed.
/// The returned from the function.
public static Pos Function (Func function) { return new PosFunc (function); }
/// Creates a percentage object
/// The percent object.
/// A value between 0 and 100 representing the percentage.
///
/// This creates a centered horizontally, is 50% of the way down, is 30% the height, and
/// is 80% the width of the it added to.
///
/// var textView = new TextField {
/// X = Pos.Center (),
/// Y = Pos.Percent (50),
/// Width = Dim.Percent (80),
/// Height = Dim.Percent (30),
/// };
///
///
public static Pos Percent (float percent)
{
if (percent is < 0 or > 100)
{
throw new ArgumentException ("Percent value must be between 0 and 100.");
}
return new PosPercent (percent / 100);
}
/// Creates a object that tracks the Top (Y) position of the specified .
/// The that depends on the other view.
/// The that will be tracked.
public static Pos Top (View view) { return new PosView (view, Side.Top); }
/// Creates a object that tracks the Top (Y) position of the specified .
/// The that depends on the other view.
/// The that will be tracked.
public static Pos Y (View view) { return new PosView (view, Side.Top); }
/// Creates a object that tracks the Left (X) position of the specified .
/// The that depends on the other view.
/// The that will be tracked.
public static Pos Left (View view) { return new PosView (view, Side.Left); }
/// Creates a object that tracks the Left (X) position of the specified .
/// The that depends on the other view.
/// The that will be tracked.
public static Pos X (View view) { return new PosView (view, Side.Left); }
///
/// Creates a object that tracks the Bottom (Y+Height) coordinate of the specified
///
///
/// The that depends on the other view.
/// The that will be tracked.
public static Pos Bottom (View view) { return new PosView (view, Side.Bottom); }
///
/// Creates a object that tracks the Right (X+Width) coordinate of the specified
/// .
///
/// The that depends on the other view.
/// The that will be tracked.
public static Pos Right (View view) { return new PosView (view, Side.Right); }
#endregion static Pos creation methods
#region virtual methods
///
/// Calculates and returns the starting point of an element based on the size of the parent element (typically
/// Superview.ContentSize).
/// This method is meant to be overridden by subclasses to provide different ways of calculating the starting point.
/// This method is used
/// internally by the layout system to determine where a View should be positioned.
///
/// The size of the parent element (typically Superview.ContentSize).
///
/// An integer representing the calculated position. The way this position is calculated depends on the specific
/// subclass of Pos that is used. For example, PosAbsolute returns a fixed position, PosAnchorEnd returns a
/// position that is anchored to the end of the layout, and so on.
///
internal virtual int Anchor (int size) { return 0; }
///
/// Calculates and returns the final position of a object. It takes into account the dimension of
/// the
/// superview and the dimension of the view itself.
///
///
///
///
/// The dimension of the superview. This could be the width for x-coordinate calculation or the
/// height for y-coordinate calculation.
///
/// The dimension of the View. It could be the current width or height.
/// The View that holds this Pos object.
/// Width or Height
///
/// The calculated position of the View. The way this position is calculated depends on the specific subclass of Pos
/// that
/// is used.
///
internal virtual int Calculate (int superviewDimension, Dim dim, View us, Dimension dimension) { return Anchor (superviewDimension); }
///
/// Diagnostics API to determine if this Pos object references other views.
///
///
internal virtual bool ReferencesOtherViews () { return false; }
#endregion virtual methods
#region operators
/// Adds a to a , yielding a new .
/// The first to add.
/// The second to add.
/// The that is the sum of the values of left and right.
public static Pos operator + (Pos left, Pos right)
{
if (left is PosAbsolute && right is PosAbsolute)
{
return new PosAbsolute (left.Anchor (0) + right.Anchor (0));
}
var newPos = new PosCombine (true, left, right);
if (left is PosView view)
{
view.Target.SetNeedsLayout ();
}
return newPos;
}
/// Creates an Absolute from the specified integer value.
/// The Absolute .
/// The value to convert to the .
public static implicit operator Pos (int n) { return new PosAbsolute (n); }
///
/// Subtracts a from a , yielding a new
/// .
///
/// The to subtract from (the minuend).
/// The to subtract (the subtrahend).
/// The that is the left minus right.
public static Pos operator - (Pos left, Pos right)
{
if (left is PosAbsolute && right is PosAbsolute)
{
return new PosAbsolute (left.Anchor (0) - right.Anchor (0));
}
var newPos = new PosCombine (false, left, right);
if (left is PosView view)
{
view.Target.SetNeedsLayout ();
}
return newPos;
}
#endregion operators
#region overrides
///
public override bool Equals (object other) { return other is Pos abs && abs == this; }
/// Serves as the default hash function.
/// A hash code for the current object.
public override int GetHashCode () { return Anchor (0).GetHashCode (); }
#endregion overrides
}
///
/// Represents an absolute position in the layout. This is used to specify a fixed position in the layout.
///
///
///
/// This is a low-level API that is typically used internally by the layout system. Use the various static
/// methods on the class to create objects instead.
///
///
///
public class PosAbsolute (int position) : Pos
{
///
/// The position of the in the layout.
///
public int Position { get; } = position;
///
public override bool Equals (object other) { return other is PosAbsolute abs && abs.Position == Position; }
///
public override int GetHashCode () { return Position.GetHashCode (); }
///
public override string ToString () { return $"Absolute({Position})"; }
internal override int Anchor (int size) { return Position; }
}
///
/// Represents a position anchored to the end (right side or bottom).
///
///
///
/// This is a low-level API that is typically used internally by the layout system. Use the various static
/// methods on the class to create objects instead.
///
///
public class PosAnchorEnd : Pos
{
///
/// Gets the offset of the position from the right/bottom.
///
public int Offset { get; }
///
/// Constructs a new position anchored to the end (right side or bottom) of the SuperView,
/// minus the respective dimension of the View. This is equivalent to using ,
/// with an offset equivalent to the View's respective dimension.
///
public PosAnchorEnd () { UseDimForOffset = true; }
///
/// Constructs a new position anchored to the end (right side or bottom) of the SuperView,
///
///
public PosAnchorEnd (int offset) { Offset = offset; }
///
public override bool Equals (object other) { return other is PosAnchorEnd anchorEnd && anchorEnd.Offset == Offset; }
///
public override int GetHashCode () { return Offset.GetHashCode (); }
///
/// If true, the offset is the width of the view, if false, the offset is the offset value.
///
public bool UseDimForOffset { get; }
///
public override string ToString () { return UseDimForOffset ? "AnchorEnd()" : $"AnchorEnd({Offset})"; }
internal override int Anchor (int size)
{
if (UseDimForOffset)
{
return size;
}
return size - Offset;
}
internal override int Calculate (int superviewDimension, Dim dim, View us, Dimension dimension)
{
int newLocation = Anchor (superviewDimension);
if (UseDimForOffset)
{
newLocation -= dim.Anchor (superviewDimension);
}
return newLocation;
}
}
///
/// Represents a position that is centered.
///
public class PosCenter : Pos
{
///
public override string ToString () { return "Center"; }
internal override int Anchor (int size) { return size / 2; }
internal override int Calculate (int superviewDimension, Dim dim, View us, Dimension dimension)
{
int newDimension = Math.Max (dim.Calculate (0, superviewDimension, us, dimension), 0);
return Anchor (superviewDimension - newDimension);
}
}
///
/// Represents a position that is a combination of two other positions.
///
///
///
/// This is a low-level API that is typically used internally by the layout system. Use the various static
/// methods on the class to create objects instead.
///
///
///
/// Indicates whether the two positions are added or subtracted. If , the positions are added,
/// otherwise they are subtracted.
///
/// The left position.
/// The right position.
public class PosCombine (bool add, Pos left, Pos right) : Pos
{
///
/// Gets whether the two positions are added or subtracted. If , the positions are added,
/// otherwise they are subtracted.
///
public bool Add { get; } = add;
///
/// Gets the left position.
///
public new Pos Left { get; } = left;
///
/// Gets the right position.
///
public new Pos Right { get; } = right;
///
public override string ToString () { return $"Combine({Left}{(Add ? '+' : '-')}{Right})"; }
internal override int Anchor (int size)
{
int la = Left.Anchor (size);
int ra = Right.Anchor (size);
if (Add)
{
return la + ra;
}
return la - ra;
}
internal override int Calculate (int superviewDimension, Dim dim, View us, Dimension dimension)
{
int left = Left.Calculate (superviewDimension, dim, us, dimension);
int right = Right.Calculate (superviewDimension, dim, us, dimension);
if (Add)
{
return left + right;
}
return left - right;
}
internal override bool ReferencesOtherViews ()
{
if (Left.ReferencesOtherViews ())
{
return true;
}
if (Right.ReferencesOtherViews ())
{
return true;
}
return false;
}
}
///
/// Represents a position that is a percentage of the width or height of the SuperView.
///
///
///
/// This is a low-level API that is typically used internally by the layout system. Use the various static
/// methods on the class to create objects instead.
///
///
///
public class PosPercent (float percent) : Pos
{
///
/// Gets the factor that represents the percentage of the width or height of the SuperView.
///
public new float Percent { get; } = percent;
///
public override bool Equals (object other) { return other is PosPercent f && f.Percent == Percent; }
///
public override int GetHashCode () { return Percent.GetHashCode (); }
///
public override string ToString () { return $"Percent({Percent})"; }
internal override int Anchor (int size) { return (int)(size * Percent); }
}
///
/// Represents a position that is computed by executing a function that returns an integer position.
///
///
///
/// This is a low-level API that is typically used internally by the layout system. Use the various static
/// methods on the class to create objects instead.
///
///
/// The position.
public class PosFunc (Func pos) : Pos
{
///
/// Gets the function that computes the position.
///
public Func Func { get; } = pos;
///
public override bool Equals (object other) { return other is PosFunc f && f.Func () == Func (); }
///
public override int GetHashCode () { return Func.GetHashCode (); }
///
public override string ToString () { return $"PosFunc({Func ()})"; }
internal override int Anchor (int size) { return Func (); }
}
///
/// Represents a position that is anchored to the side of another view.
///
///
///
/// This is a low-level API that is typically used internally by the layout system. Use the various static
/// methods on the class to create objects instead.
///
///
/// The View the position is anchored to.
/// The side of the View the position is anchored to.
public class PosView (View view, Side side) : Pos
{
///
/// Gets the View the position is anchored to.
///
public View Target { get; } = view;
///
/// Gets the side of the View the position is anchored to.
///
public Side Side { get; } = side;
///
public override bool Equals (object other) { return other is PosView abs && abs.Target == Target; }
///
public override int GetHashCode () { return Target.GetHashCode (); }
///
public override string ToString ()
{
string sideString = Side switch
{
Side.Left => "left",
Side.Top => "top",
Side.Right => "right",
Side.Bottom => "bottom",
_ => "unknown"
};
if (Target == null)
{
throw new NullReferenceException (nameof (Target));
}
return $"View(side={sideString},target={Target})";
}
internal override int Anchor (int size)
{
return Side switch
{
Side.Left => Target.Frame.X,
Side.Top => Target.Frame.Y,
Side.Right => Target.Frame.Right,
Side.Bottom => Target.Frame.Bottom,
_ => 0
};
}
internal override bool ReferencesOtherViews () { return true; }
}