Git_Mirror/Terminal.Gui
1
0
Fork 0
mirror of https://github.com/gui-cs/Terminal.Gui.git synced 2025-12-28 16:58:01 +01:00
Code Issues Packages Projects Releases Wiki Activity

Updated API docs

Browse Source
This commit is contained in:
Tig
2024-04-28 09:11:15 -07:00
parent 9f8f261034
commit b547d6ce67
4 changed files with 68 additions and 374 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Terminal.Gui/Text/TextFormatter.cs
View File

@@ -30,7 +30,7 @@ public class TextFormatter
/// <summary>Gets or sets whether the <see cref="Size"/> should be automatically changed to fit the <see cref="Text"/>.</summary>
/// <remarks>
/// <para>Used by <see cref="View.AutoSize"/> to resize the view's <see cref="View.Viewport"/> to fit <see cref="Size"/>.</para>
/// <para>Used when <see cref="View"/> is using <see cref="Dim.Auto"/> to resize the view's <see cref="View.Viewport"/> to fit <see cref="Size"/>.</para>
/// <para>
/// AutoSize is ignored if <see cref="TextAlignment.Justified"/> and
/// <see cref="VerticalTextAlignment.Justified"/> are used.

161
Terminal.Gui/View/Layout/ViewLayout.cs
View File

@@ -395,140 +395,6 @@ public partial class View
}
}
///// <summary>Determines if the View's <see cref="Height"/> can be set to a new value.</summary>
///// <remarks>TrySetHeight can only be called when AutoSize is true (or being set to true).</remarks>
///// <param name="desiredHeight"></param>
///// <param name="resultHeight">
///// Contains the width that would result if <see cref="Height"/> were set to
///// <paramref name="desiredHeight"/>"/>
///// </param>
///// <returns>
///// <see langword="true"/> if the View's <see cref="Height"/> can be changed to the specified value. False
///// otherwise.
///// </returns>
//internal bool TrySetHeight (int desiredHeight, out int resultHeight)
//{
// int h = desiredHeight;
// bool canSetHeight;
// switch (Height)
// {
// case Dim.DimCombine _:
// case Dim.DimView _:
// case Dim.DimFill _:
// // It's a Dim.DimCombine and so can't be assigned. Let it have it's height anchored.
// h = Height.Anchor (h);
// canSetHeight = !ValidatePosDim;
// break;
// case Dim.DimFactor factor:
// // Tries to get the SuperView height otherwise the view height.
// int sh = SuperView is { } ? SuperView.Frame.Height : h;
// if (factor.IsFromRemaining ())
// {
// sh -= Frame.Y;
// }
// h = Height.Anchor (sh);
// canSetHeight = !ValidatePosDim;
// break;
// default:
// canSetHeight = true;
// break;
// }
// resultHeight = h;
// return canSetHeight;
//}
///// <summary>Determines if the View's <see cref="Width"/> can be set to a new value.</summary>
///// <remarks>TrySetWidth can only be called when AutoSize is true (or being set to true).</remarks>
///// <param name="desiredWidth"></param>
///// <param name="resultWidth">
///// Contains the width that would result if <see cref="Width"/> were set to
///// <paramref name="desiredWidth"/>"/>
///// </param>
///// <returns>
///// <see langword="true"/> if the View's <see cref="Width"/> can be changed to the specified value. False
///// otherwise.
///// </returns>
//internal bool TrySetWidth (int desiredWidth, out int resultWidth)
//{
// int w = desiredWidth;
// bool canSetWidth;
// switch (Width)
// {
// case Dim.DimCombine _:
// case Dim.DimView _:
// case Dim.DimFill _:
// // It's a Dim.DimCombine and so can't be assigned. Let it have it's Width anchored.
// w = Width.Anchor (w);
// canSetWidth = !ValidatePosDim;
// break;
// case Dim.DimFactor factor:
// // Tries to get the SuperView Width otherwise the view Width.
// int sw = SuperView is { } ? SuperView.Frame.Width : w;
// if (factor.IsFromRemaining ())
// {
// sw -= Frame.X;
// }
// w = Width.Anchor (sw);
// canSetWidth = !ValidatePosDim;
// break;
// default:
// canSetWidth = true;
// break;
// }
// resultWidth = w;
// return canSetWidth;
//}
///// <summary>Resizes the View to fit the specified size. Factors in the HotKey.</summary>
///// <remarks>ResizeBoundsToFit can only be called when AutoSize is true (or being set to true).</remarks>
///// <param name="size"></param>
///// <returns>whether the Viewport was changed or not</returns>
//private bool ResizeViewportToFit (Size size)
//{
// //if (AutoSize == false) {
// // throw new InvalidOperationException ("ResizeViewportToFit can only be called when AutoSize is true");
// //}
// var changed = false;
// bool canSizeW = TrySetWidth (size.Width - GetHotKeySpecifierLength (), out int rW);
// bool canSizeH = TrySetHeight (size.Height - GetHotKeySpecifierLength (false), out int rH);
// if (canSizeW)
// {
// changed = true;
// _width = rW;
// }
// if (canSizeH)
// {
// changed = true;
// _height = rH;
// }
// if (changed)
// {
// Viewport = new (Viewport.X, Viewport.Y, canSizeW ? rW : Viewport.Width, canSizeH ? rH : Viewport.Height);
// }
// return changed;
//}
#endregion AutoSize
#region Layout Engine
@@ -1110,33 +976,6 @@ public partial class View
SetNeedsLayout ();
SetNeedsDisplay ();
}
//if (AutoSize)
//{
// if (autoSize.Width == 0 || autoSize.Height == 0)
// {
// // Set the frame. Do NOT use `Frame` as it overwrites X, Y, Width, and Height, making
// // the view LayoutStyle.Absolute.
// SetFrame (_frame with { Size = autoSize });
// if (autoSize.Width == 0)
// {
// _width = 0;
// }
// if (autoSize.Height == 0)
// {
// _height = 0;
// }
// }
// //else if (!SetFrameToFitText ())
// //{
// // SetTextFormatterSize ();
// //}
// SetNeedsLayout ();
// SetNeedsDisplay ();
//}
}
internal void CollectAll (View from, ref HashSet<View> nNodes, ref HashSet<(View, View)> nEdges)

12
Terminal.Gui/View/ViewDrawing.cs
View File

@@ -577,10 +577,7 @@ public partial class View
/// </remarks>
public void SetNeedsDisplay ()
{
//if (IsInitialized)
{
SetNeedsDisplay (Viewport);
}
SetNeedsDisplay (Viewport);
}
/// <summary>Expands the area of this view needing to be redrawn to include <paramref name="region"/>.</summary>
@@ -597,13 +594,6 @@ public partial class View
/// <param name="region">The content-relative region that needs to be redrawn.</param>
public void SetNeedsDisplay (Rectangle region)
{
//if (!IsInitialized)
//{
// _needsDisplayRect = region;
// return;
//}
if (_needsDisplayRect.IsEmpty)
{
_needsDisplayRect = region;

267
Terminal.Gui/View/ViewText.cs
View File

@@ -40,7 +40,8 @@ public partial class View
/// The text will word-wrap to additional lines if it does not fit horizontally. If <see cref="ContentSize"/>'s height
/// is 1, the text will be clipped.
/// </para>
/// <para>If <see cref="AutoSize"/> is <c>true</c>, the <see cref="ContentSize"/> will be adjusted to fit the text.</para>
/// <para>If <see cref="View.Width"/> or <see cref="View.Height"/> are using <see cref="Dim.DimAutoStyle.Text"/>,
/// the <see cref="ContentSize"/> will be adjusted to fit the text.</para>
/// <para>When the text changes, the <see cref="TextChanged"/> is fired.</para>
/// </remarks>
public virtual string Text
@@ -83,7 +84,7 @@ public partial class View
/// redisplay the <see cref="View"/>.
/// </summary>
/// <remarks>
/// <para>If <see cref="AutoSize"/> is <c>true</c>, the <see cref="ContentSize"/> will be adjusted to fit the text.</para>
/// <para> <see cref="View.Width"/> or <see cref="View.Height"/> are using <see cref="Dim.DimAutoStyle.Text"/>, the <see cref="ContentSize"/> will be adjusted to fit the text.</para>
/// </remarks>
/// <value>The text alignment.</value>
public virtual TextAlignment TextAlignment
@@ -102,7 +103,7 @@ public partial class View
/// <see cref="View"/>.
/// </summary>
/// <remarks>
/// <para>If <see cref="AutoSize"/> is <c>true</c>, the <see cref="ContentSize"/> will be adjusted to fit the text.</para>
/// <para> <see cref="View.Width"/> or <see cref="View.Height"/> are using <see cref="Dim.DimAutoStyle.Text"/>, the <see cref="ContentSize"/> will be adjusted to fit the text.</para>
/// </remarks>
/// <value>The text alignment.</value>
public virtual TextDirection TextDirection
@@ -126,7 +127,7 @@ public partial class View
/// the <see cref="View"/>.
/// </summary>
/// <remarks>
/// <para>If <see cref="AutoSize"/> is <c>true</c>, the <see cref="ContentSize"/> will be adjusted to fit the text.</para>
/// <para> <see cref="View.Width"/> or <see cref="View.Height"/> are using <see cref="Dim.DimAutoStyle.Text"/>, the <see cref="ContentSize"/> will be adjusted to fit the text.</para>
/// </remarks>
/// <value>The text alignment.</value>
public virtual VerticalTextAlignment VerticalTextAlignment
@@ -139,64 +140,6 @@ public partial class View
}
}
/// <summary>
/// Gets the width or height of the <see cref="TextFormatter.HotKeySpecifier"/> characters
/// in the <see cref="Text"/> property.
/// </summary>
/// <remarks>
/// Only the first HotKey specifier found in <see cref="Text"/> is supported.
/// </remarks>
/// <param name="isWidth">
/// If <see langword="true"/> (the default) the width required for the HotKey specifier is returned. Otherwise the
/// height
/// is returned.
/// </param>
/// <returns>
/// The number of characters required for the <see cref="TextFormatter.HotKeySpecifier"/>. If the text
/// direction specified
/// by <see cref="TextDirection"/> does not match the <paramref name="isWidth"/> parameter, <c>0</c> is returned.
/// </returns>
public int GetHotKeySpecifierLength (bool isWidth = true)
{
if (isWidth)
{
return TextFormatter.IsHorizontalDirection (TextDirection) && TextFormatter.Text?.Contains ((char)HotKeySpecifier.Value) == true
? Math.Max (HotKeySpecifier.GetColumns (), 0)
: 0;
}
return TextFormatter.IsVerticalDirection (TextDirection) && TextFormatter.Text?.Contains ((char)HotKeySpecifier.Value) == true
? Math.Max (HotKeySpecifier.GetColumns (), 0)
: 0;
}
///// <summary>
///// Gets dimensions required to fit <see cref="Text"/> within <see cref="ContentSize"/> using the text
///// <see cref="NavigationDirection"/> specified by the <see cref="TextFormatter"/> property and accounting for any
///// <see cref="HotKeySpecifier"/> characters.
///// </summary>
///// <remarks>
///// </remarks>
///// <returns>The <see cref="Size"/> of the <see cref="ContentSize"/> required to fit the formatted text.</returns>
//public Size GetTextAutoSize ()
//{
// var x = 0;
// var y = 0;
// if (IsInitialized)
// {
// x = Viewport.X;
// y = Viewport.Y;
// }
// // Get the size of the text without the hot key specifier
// Rectangle rect = TextFormatter.CalcRect (x, y, TextFormatter.Text, TextFormatter.Direction);
// int newWidth = rect.Size.Width - GetHotKeySpecifierLength ();
// int newHeight = rect.Size.Height - GetHotKeySpecifierLength (false);
// return new (newWidth, newHeight);
//}
/// <summary>
/// Can be overridden if the <see cref="Terminal.Gui.TextFormatter.Text"/> has
/// different format than the default.
@@ -216,8 +159,8 @@ public partial class View
internal Size GetSizeNeededForTextWithoutHotKey ()
{
return new Size (
TextFormatter.Size.Width - GetHotKeySpecifierLength (),
TextFormatter.Size.Height - GetHotKeySpecifierLength (false));
TextFormatter.Size.Width - TextFormatter.GetHotKeySpecifierLength (),
TextFormatter.Size.Height - TextFormatter.GetHotKeySpecifierLength (false));
}
/// <summary>
@@ -234,14 +177,6 @@ public partial class View
{
UpdateTextFormatterText ();
//if (!IsInitialized)
//{
// return;
//}
//Dim.DimAuto widthAuto = Width as Dim.DimAuto;
//Dim.DimAuto heightAuto = Height as Dim.DimAuto;
// TODO: This is a hack. Figure out how to move this into DimDimAuto
// Use _width & _height instead of Width & Height to avoid debug spew
if ((_width is Dim.DimAuto widthAuto && widthAuto._style != Dim.DimAutoStyle.Subviews)
@@ -259,148 +194,78 @@ public partial class View
TextFormatter.Size = new Size (ContentSize.Width, ContentSize.Height);
}
////private bool IsValidAutoSize (out Size autoSize)
////{
//// Rectangle rect = TextFormatter.CalcRect (_frame.X, _frame.Y, TextFormatter.Text, TextDirection);
//// autoSize = new Size (
//// rect.Size.Width - GetHotKeySpecifierLength (),
//// rect.Size.Height - GetHotKeySpecifierLength (false));
//// return !((ValidatePosDim && (!(Width is Dim.DimAbsolute) || !(Height is Dim.DimAbsolute)))
//// || _frame.Size.Width != rect.Size.Width - GetHotKeySpecifierLength ()
//// || _frame.Size.Height != rect.Size.Height - GetHotKeySpecifierLength (false));
////}
//private bool IsValidAutoSizeHeight (Dim height)
//{
// Rectangle rect = TextFormatter.CalcRect (_frame.X, _frame.Y, TextFormatter.Text, TextDirection);
// int dimValue = height.Anchor (0);
// return !((ValidatePosDim && !(height is Dim.DimAbsolute)) || dimValue != rect.Size.Height - GetHotKeySpecifierLength (false));
//}
//private bool IsValidAutoSizeWidth (Dim width)
//{
// Rectangle rect = TextFormatter.CalcRect (_frame.X, _frame.Y, TextFormatter.Text, TextDirection);
// int dimValue = width.Anchor (0);
// return !((ValidatePosDim && !(width is Dim.DimAbsolute)) || dimValue != rect.Size.Width - GetHotKeySpecifierLength ());
//}
///// <summary>
///// Sets the size of the View to the minimum width or height required to fit <see cref="Text"/>.
///// </summary>
///// <returns>
///// <see langword="true"/> if the size was changed; <see langword="false"/> if <see cref="AutoSize"/> ==
///// <see langword="true"/> or
///// <see cref="Text"/> will not fit.
///// </returns>
///// <remarks>
///// Always returns <see langword="false"/> if <see cref="AutoSize"/> is <see langword="true"/> or
///// if <see cref="Height"/> (Horizontal) or <see cref="Width"/> (Vertical) are not not set or zero.
///// Does not take into account word wrapping.
///// </remarks>
//private bool SetFrameToFitText ()
//{
// if (AutoSize == false)
// {
// throw new InvalidOperationException ("SetFrameToFitText can only be called when AutoSize is true");
// }
// // BUGBUG: This API is broken - should not assume Frame.Height == ContentSize.Height
// // <summary>
// // Gets the minimum dimensions required to fit the View's <see cref="Text"/>, factoring in <see cref="TextDirection"/>.
// // </summary>
// // <param name="sizeRequired">The minimum dimensions required.</param>
// // <returns><see langword="true"/> if the dimensions fit within the View's <see cref="ContentSize"/>, <see langword="false"/> otherwise.</returns>
// // <remarks>
// // Always returns <see langword="false"/> if <see cref="AutoSize"/> is <see langword="true"/> or
// // if <see cref="Height"/> (Horizontal) or <see cref="Width"/> (Vertical) are not not set or zero.
// // Does not take into account word wrapping.
// // </remarks>
// bool GetMinimumSizeOfText (out Size sizeRequired)
// {
// if (!IsInitialized)
// {
// sizeRequired = Size.Empty;
// return false;
// }
// sizeRequired = ContentSize;
// if (AutoSize || string.IsNullOrEmpty (TextFormatter.Text))
// {
// return false;
// }
// switch (TextFormatter.IsVerticalDirection (TextDirection))
// {
// case true:
// int colWidth = TextFormatter.GetColumnsRequiredForVerticalText (new List<string> { TextFormatter.Text }, 0, 1);
//// // TODO: v2 - This uses frame.Width; it should only use ContentSize
// if (_frame.Width < colWidth
// && (Width is null || (ContentSize.Width >= 0 && Width is Dim.DimAbsolute && Width.Anchor (0) >= 0 && Width.Anchor (0) < colWidth)))
// {
// sizeRequired = new (colWidth, ContentSize.Height);
// return true;
// }
// break;
// default:
// if (_frame.Height < 1 && (Height is null || (Height is Dim.DimAbsolute && Height.Anchor (0) == 0)))
// {
// sizeRequired = new (ContentSize.Width, 1);
// return true;
// }
// break;
// }
// return false;
// }
// if (GetMinimumSizeOfText (out Size size))
// {
// // TODO: This is a hack.
// //_width = size.Width;
// //_height = size.Height;
// SetFrame (new (_frame.Location, size));
// //throw new InvalidOperationException ("This is a hack.");
// return true;
// }
// return false;
//}
private void UpdateTextDirection (TextDirection newDirection)
{
bool directionChanged = TextFormatter.IsHorizontalDirection (TextFormatter.Direction) != TextFormatter.IsHorizontalDirection (newDirection);
TextFormatter.Direction = newDirection;
//bool isValidOldAutoSize = AutoSize && IsValidAutoSize (out Size _);
UpdateTextFormatterText ();
if (directionChanged)
{
OnResizeNeeded ();
}
//if ((!ValidatePosDim && directionChanged && AutoSize) || (ValidatePosDim && directionChanged && AutoSize && isValidOldAutoSize))
//{
// OnResizeNeeded ();
//}
//else if (directionChanged && IsAdded)
//{
// ResizeViewportToFit (Viewport.Size);
//}
SetTextFormatterSize ();
SetNeedsDisplay ();
}
#region AutoSize
/// <summary>
/// Gets or sets a flag that determines whether the View will be automatically resized to fit the <see cref="Text"/>
/// within <see cref="Viewport"/>.
/// <para>
/// The default is <see langword="false"/>. Set to <see langword="true"/> to turn on AutoSize. If
/// <see langword="true"/> then <see cref="Width"/> and <see cref="Height"/> will be used if <see cref="Text"/> can
/// fit; if <see cref="Text"/> won't fit the view will be resized as needed.
/// </para>
/// <para>
/// If <see cref="AutoSize"/> is set to <see langword="true"/> then <see cref="Width"/> and <see cref="Height"/>
/// will be changed to <see cref="Dim.DimAbsolute"/> if they are not already.
/// </para>
/// <para>
/// If <see cref="AutoSize"/> is set to <see langword="false"/> then <see cref="Width"/> and <see cref="Height"/>
/// will left unchanged.
/// </para>
/// </summary>
[ObsoleteAttribute ("Use Dim.Auto instead.", false)]
public virtual bool AutoSize
{
get => _height is Dim.DimAuto && _width is Dim.DimAuto;
set
{
TextFormatter.AutoSize = value;
// BUGBUG: This is all a hack until AutoSize is removed
if (value)
{
UpdateTextFormatterText ();
if (IsInitialized)
{
Height = Dim.Auto (Dim.DimAutoStyle.Text);
Width = Dim.Auto (Dim.DimAutoStyle.Text);
}
else
{
_height = Dim.Auto (Dim.DimAutoStyle.Text);
_width = Dim.Auto (Dim.DimAutoStyle.Text);
OnResizeNeeded ();
}
}
else
{
_height = ContentSize.Height;
_width = ContentSize.Width;
// Force ContentSize to be reset to Viewport
_contentSize = Size.Empty;
OnResizeNeeded ();
}
}
}
#endregion AutoSize
}