#nullable enable
namespace Terminal.Gui;
///
/// 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 aligns a set of views.
///
///
/// -
///
///
///
///
/// 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 abstract record 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 aligns a set of views according to the specified
/// and .
///
/// The alignment. The default includes .
/// The optional alignment modes.
///
/// The optional identifier of a set of views that should be aligned together. When only a single
/// set of views in a SuperView is aligned, this parameter is optional.
///
///
public static Pos Align (Alignment alignment, AlignmentModes modes = AlignmentModes.StartToEnd | AlignmentModes.AddSpaceBetweenItems, int groupId = 0)
{
return new PosAlign
{
Aligner = new ()
{
Alignment = alignment,
AlignmentModes = modes
},
GroupId = groupId
};
}
///
/// 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)
{
ArgumentOutOfRangeException.ThrowIfNegative (offset, 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 Func (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 (int percent)
{
ArgumentOutOfRangeException.ThrowIfNegative (percent, nameof (percent));
return new PosPercent (percent);
}
/// 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
///
/// Gets the starting point of an element based on the size of the parent element (typically
/// Superview.GetContentSize ()).
/// 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.GetContentSize ()).
///
/// 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 GetAnchor (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 GetAnchor (superviewDimension); }
///
/// Diagnostics API to determine if this Pos object references other views.
///
///
internal virtual bool ReferencesOtherViews () { return false; }
///
/// Indicates whether the specified type is in the hierarchy of this Pos object.
///
/// A reference to this instance.
///
public bool Has (out T pos) where T : Pos
{
pos = (this as T)!;
return this switch
{
PosCombine combine => combine.Left.Has (out pos) || combine.Right.Has (out pos),
T => true,
_ => 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.GetAnchor (0) + right.GetAnchor (0));
}
var newPos = new PosCombine (AddOrSubtract.Add, 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.GetAnchor (0) - right.GetAnchor (0));
}
var newPos = new PosCombine (AddOrSubtract.Subtract, left, right);
if (left is PosView view)
{
view.Target?.SetNeedsLayout ();
}
return newPos;
}
#endregion operators
}