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

Code and API doc cleanup

Browse Source
This commit is contained in:
Tig
2024-04-14 14:57:35 -06:00
parent 513eb135c6
commit 32e79bdd17
5 changed files with 89 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Terminal.Gui/View/Adornment/Adornment.cs
View File

@@ -8,7 +8,7 @@
/// <remarsk>
/// <para>
/// Each of <see cref="Margin"/>, <see cref="Border"/>, and <see cref="Padding"/> has slightly different
/// behavior relative to <see cref="ColorScheme"/>, <see cref="View.SetFocus"/>, keyboard input, and
/// behavior relative to <see cref="ColorScheme"/>, <see cref="View.SetFocus()"/>, keyboard input, and
/// mouse input. Each can be customized by manipulating their Subviews.
/// </para>
/// </remarsk>

117
Terminal.Gui/View/ViewContent.cs
View File

@@ -14,91 +14,106 @@ public enum ViewportSettings
None = 0,
/// <summary>
/// If set, <see cref="View.Viewport"/><c>.X</c> can be set to negative values enabling scrolling beyond the left of the
/// If set, <see cref="View.Viewport"/><c>.X</c> can be set to negative values enabling scrolling beyond the left of
/// the
/// content area.
/// </summary>
/// <remarks>
/// <para>
/// When not set, <see cref="View.Viewport"/><c>.X</c> is constrained to positive values.
/// </para>
/// <para>
/// When not set, <see cref="View.Viewport"/><c>.X</c> is constrained to positive values.
/// </para>
/// </remarks>
AllowNegativeX = 1,
/// <summary>
/// If set, <see cref="View.Viewport"/><c>.Y</c> can be set to negative values enabling scrolling beyond the top of the
/// content area.
/// content area.
/// </summary>
/// <remarks>
/// <para>
/// When not set, <see cref="View.Viewport"/><c>.Y</c> is constrained to positive values.
/// </para>
/// <para>
/// When not set, <see cref="View.Viewport"/><c>.Y</c> is constrained to positive values.
/// </para>
/// </remarks>
AllowNegativeY = 2,
/// <summary>
/// If set, <see cref="View.Viewport"/><c>.Size</c> can be set to negative coordinates enabling scrolling beyond the top-left of the
/// If set, <see cref="View.Viewport"/><c>.Size</c> can be set to negative coordinates enabling scrolling beyond the
/// top-left of the
/// content area.
/// </summary>
/// <remarks>
/// <para>
/// When not set, <see cref="View.Viewport"/><c>.Size</c> is constrained to positive coordinates.
/// </para>
/// <para>
/// When not set, <see cref="View.Viewport"/><c>.Size</c> is constrained to positive coordinates.
/// </para>
/// </remarks>
AllowNegativeLocation = AllowNegativeX | AllowNegativeY,
/// <summary>
/// If set, <see cref="View.Viewport"/><c>.X</c> can be set values greater than <see cref="View.ContentSize"/><c>.Width</c> enabling scrolling beyond the right
/// If set, <see cref="View.Viewport"/><c>.X</c> can be set values greater than <see cref="View.ContentSize"/>
/// <c>.Width</c> enabling scrolling beyond the right
/// of the content area.
/// </summary>
/// <remarks>
/// <para>
/// When not set, <see cref="View.Viewport"/><c>.X</c> is constrained to <see cref="View.ContentSize"/><c>.Width - 1</c>.
/// This means the last column of the content will remain visible even if there is an attempt to scroll the Viewport past the last column.
/// </para>
/// <para>
/// When not set, <see cref="View.Viewport"/><c>.X</c> is constrained to <see cref="View.ContentSize"/>
/// <c>.Width - 1</c>.
/// This means the last column of the content will remain visible even if there is an attempt to scroll the
/// Viewport past the last column.
/// </para>
/// <para>
/// The practical effect of this is that the last column of the content will always be visible.
/// </para>
/// </remarks>
AllowXGreaterThanContentWidth = 4,
/// <summary>
/// If set, <see cref="View.Viewport"/><c>.Y</c> can be set values greater than <see cref="View.ContentSize"/><c>.Height</c> enabling scrolling beyond the right
/// If set, <see cref="View.Viewport"/><c>.Y</c> can be set values greater than <see cref="View.ContentSize"/>
/// <c>.Height</c> enabling scrolling beyond the right
/// of the content area.
/// </summary>
/// <remarks>
/// <para>
/// When not set, <see cref="View.Viewport"/><c>.Y</c> is constrained to <see cref="View.ContentSize"/><c>.Height - 1</c>.
/// This means the last row of the content will remain visible even if there is an attempt to scroll the Viewport past the last row.
/// </para>
/// <para>
/// When not set, <see cref="View.Viewport"/><c>.Y</c> is constrained to <see cref="View.ContentSize"/>
/// <c>.Height - 1</c>.
/// This means the last row of the content will remain visible even if there is an attempt to scroll the Viewport
/// past the last row.
/// </para>
/// <para>
/// The practical effect of this is that the last row of the content will always be visible.
/// </para>
/// </remarks>
AllowYGreaterThanContentHeight = 8,
/// <summary>
/// If set, <see cref="View.Viewport"/><c>.Size</c> can be set values greater than <see cref="View.ContentSize"/> enabling scrolling beyond the bottom-right
/// If set, <see cref="View.Viewport"/><c>.Size</c> can be set values greater than <see cref="View.ContentSize"/>
/// enabling scrolling beyond the bottom-right
/// of the content area.
/// </summary>
/// <remarks>
/// <para>
/// When not set, <see cref="View.Viewport"/> is constrained to <see cref="View.ContentSize"/><c> -1</c>.
/// This means the last column and row of the content will remain visible even if there is an attempt to
/// scroll the Viewport past the last column or row.
/// </para>
/// <para>
/// When not set, <see cref="View.Viewport"/> is constrained to <see cref="View.ContentSize"/><c> -1</c>.
/// This means the last column and row of the content will remain visible even if there is an attempt to
/// scroll the Viewport past the last column or row.
/// </para>
/// </remarks>
AllowLocationGreaterThanContentSize = AllowXGreaterThanContentWidth | AllowYGreaterThanContentHeight,
/// <summary>
/// By default, clipping is applied to just the visible content within <see cref="View.Viewport"/>. In cases where the viewport is
/// larger than the content area (e.g. when <see cref="AllowNegativeLocation"/> is enabled), setting this flag will allow content
/// outside the <see cref="View.Viewport"/> to be drawn.
/// By default, clipping is applied to the <see cref="View.Viewport"/>. Setting this flag will cause clipping to be
/// applied to the visible content area.
/// </summary>
ClipVisibleContentOnly = 16,
ClipContentOnly = 16,
/// <summary>
/// If set <see cref="View.Clear()"/> will clear only the portion of the content
/// area that is visible within the <see cref="View.Viewport"/>. This is useful for views that have a
/// content area larger than the Viewport and want the area outside the content to be visually distinct.
/// If set <see cref="View.Clear()"/> will clear only the portion of the content
/// area that is visible within the <see cref="View.Viewport"/>. This is useful for views that have a
/// content area larger than the Viewport and want the area outside the content to be visually distinct.
/// </summary>
/// <remarks>
/// <see cref="ClipVisibleContentOnly"/> must be set for this setting to work (clipping beyond the visible area must be disabled).
/// <see cref="ClipContentOnly"/> must be set for this setting to work (clipping beyond the visible area must be
/// disabled).
/// </remarks>
ClearVisibleContentOnly = 32,
ClearContentOnly = 32
}
public partial class View
@@ -108,8 +123,8 @@ public partial class View
private Size _contentSize;
/// <summary>
/// Gets or sets the size of the View's content. If the value is <c>Size.Empty</c> the size of the content is
/// the same as the size of <see cref="Viewport"/>, and <c>Viewport.Location</c> will always be <c>0, 0</c>.
/// Gets or sets the size of the View's content. If not set, the value will be the same as the size of <see cref="Viewport"/>,
/// and <c>Viewport.Location</c> will always be <c>0, 0</c>.
/// </summary>
/// <remarks>
/// <para>
@@ -159,7 +174,7 @@ public partial class View
}
/// <summary>
/// Event that is raised when the <see cref="ContentSize"/> changes.
/// Event raised when the <see cref="ContentSize"/> changes.
/// </summary>
public event EventHandler<SizeChangedEventArgs> ContentSizeChanged;
@@ -186,8 +201,7 @@ public partial class View
/// Content-relative means relative to the top-left corner of the view's Content, which is
/// always at <c>0, 0</c>.
/// </remarks>
/// <param name="x">Column relative to the left side of the Content.</param>
/// <param name="y">Row relative to the top of the Content</param>
/// <param name="location">The Screen-relative location.</param>
/// <returns>The coordinate relative to this view's Content.</returns>
public Point ScreenToContent (in Point location)
{
@@ -246,14 +260,15 @@ public partial class View
/// <remarks>
/// <para>
/// Positive values for the location indicate the visible area is offset into (down-and-right) the View's virtual
/// <see cref="ContentSize"/>. This enables virtual scrolling.
/// <see cref="ContentSize"/>. This enables scrolling down and to the right (e.g. in a <see cref="ListView"/>.
/// </para>
/// <para>
/// Negative values for the location indicate the visible area is offset above (up-and-left) the View's virtual
/// <see cref="ContentSize"/>. This enables virtual zoom.
/// <see cref="ContentSize"/>. This enables scrolling up and to the left (e.g. in an image viewer that supports zoom
/// where the image stays centered).
/// </para>
/// <para>
/// The <see cref="ViewportSettings"/> property controls how scrolling is handled. If <see cref="ViewportSettings"/> is
/// The <see cref="ViewportSettings"/> property controls how scrolling is handled.
/// </para>
/// <para>
/// If <see cref="LayoutStyle"/> is <see cref="LayoutStyle.Computed"/> the value of Viewport is indeterminate until
@@ -322,6 +337,7 @@ public partial class View
}
OnViewportChanged (new (IsInitialized ? Viewport : Rectangle.Empty, oldViewport));
return;
}
@@ -333,7 +349,6 @@ public partial class View
Size = newSize
};
void ApplySettings (ref Rectangle newViewport)
{
if (!ViewportSettings.HasFlag (ViewportSettings.AllowXGreaterThanContentWidth))
@@ -347,7 +362,6 @@ public partial class View
// IMPORTANT: Check for negative location AFTER checking for location greater than content width
if (!ViewportSettings.HasFlag (ViewportSettings.AllowNegativeX))
{
if (newViewport.X < 0)
{
newViewport.X = 0;
@@ -374,19 +388,16 @@ public partial class View
}
/// <summary>
/// Fired when the <see cref="Frame"/> changes. This event is fired after the <see cref="Frame"/> has been updated.
/// Fired when the <see cref="Viewport"/> changes. This event is fired after the <see cref="Viewport"/> has been updated.
/// </summary>
[CanBeNull]
public event EventHandler<DrawEventArgs> ViewportChanged;
/// <summary>
/// Called when the <see cref="Frame"/> changes. Invokes the <see cref="ViewportChanged"/> event.
/// Called when the <see cref="Viewport"/> changes. Invokes the <see cref="ViewportChanged"/> event.
/// </summary>
/// <param name="e"></param>
protected virtual void OnViewportChanged (DrawEventArgs e)
{
ViewportChanged?.Invoke (this, e);
}
protected virtual void OnViewportChanged (DrawEventArgs e) { ViewportChanged?.Invoke (this, e); }
/// <summary>
/// Converts a <see cref="Viewport"/>-relative location to a screen-relative location.

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

@@ -84,7 +84,7 @@ public partial class View
/// <summary>Clears <see cref="Viewport"/> with the normal background.</summary>
/// <remarks>
/// <para>
/// If <see cref="ViewportSettings"/> has <see cref="ViewportSettings.ClearVisibleContentOnly"/> only
/// If <see cref="ViewportSettings"/> has <see cref="Gui.ViewportSettings.ClearContentOnly"/> only
/// the portion of the content
/// area that is visible within the <see cref="View.Viewport"/> will be cleared. This is useful for views that have a
/// content area larger than the Viewport (e.g. when <see cref="ViewportSettings.AllowNegativeLocation"/> is
@@ -104,7 +104,7 @@ public partial class View
Rectangle prevClip = Driver.Clip;
if (ViewportSettings.HasFlag (ViewportSettings.ClearVisibleContentOnly))
if (ViewportSettings.HasFlag (ViewportSettings.ClearContentOnly))
{
Rectangle visibleContent = ViewportToScreen (new (new (-Viewport.X, -Viewport.Y), ContentSize));
toClear = Rectangle.Intersect (toClear, visibleContent);
@@ -143,9 +143,15 @@ public partial class View
/// <summary>Sets the <see cref="ConsoleDriver"/>'s clip region to <see cref="Viewport"/>.</summary>
/// <remarks>
/// The clip region is set to the intersection of the current clip region and the
/// <see cref="Viewport"/>. This ensures that drawing is constrained to the visible
/// viewport of the view.
/// <para>
/// By default, the clip rectangle is set to the intersection of the current clip region and the
/// <see cref="Viewport"/>. This ensures that drawing is constrained to the viewport, but allows
/// content to be drawn beyond the viewport.
/// </para>
/// <para>
/// If <see cref="ViewportSettings"/> has <see cref="Gui.ViewportSettings.ClipContentOnly"/> set, clipping will be
/// applied to just the visible content area.
/// </para>
/// </remarks>
/// <returns>
/// The current screen-relative clip region, which can be then re-applied by setting
@@ -163,7 +169,7 @@ public partial class View
// Clamp the Clip to the entire visible area
Rectangle clip = Rectangle.Intersect (ViewportToScreen (Viewport with { Location = Point.Empty }), previous);
if (ViewportSettings.HasFlag (ViewportSettings.ClipVisibleContentOnly))
if (ViewportSettings.HasFlag (ViewportSettings.ClipContentOnly))
{
// Clamp the Clip to the just content area that is within the viewport
Rectangle visibleContent = ViewportToScreen (new (new (-Viewport.X, -Viewport.Y), ContentSize));

20
UICatalog/Scenarios/VirtualContent.cs
View File

@@ -24,8 +24,8 @@ public class VirtualContent : Scenario
Arrangement = ViewArrangement.Fixed;
ContentSize = new (60, 40);
ViewportSettings |= ViewportSettings.ClearVisibleContentOnly;
ViewportSettings |= ViewportSettings.ClipVisibleContentOnly;
ViewportSettings |= ViewportSettings.ClearContentOnly;
ViewportSettings |= ViewportSettings.ClipContentOnly;
// Things this view knows how to do
AddCommand (Command.ScrollDown, () => ScrollVertical (1));
@@ -242,46 +242,46 @@ public class VirtualContent : Scenario
var cbClearOnlyVisible = new CheckBox
{
Title = "ClearVisibleContentOnly",
Title = "ClearContentOnly",
X = Pos.Right (contentSizeHeight) + 1,
Y = Pos.Top (labelContentSize),
CanFocus = false
};
cbClearOnlyVisible.Checked = view.ViewportSettings.HasFlag (ViewportSettings.ClearVisibleContentOnly);
cbClearOnlyVisible.Checked = view.ViewportSettings.HasFlag (ViewportSettings.ClearContentOnly);
cbClearOnlyVisible.Toggled += ClearVisibleContentOnly_Toggled;
void ClearVisibleContentOnly_Toggled (object sender, StateEventArgs<bool?> e)
{
if (e.NewValue == true)
{
view.ViewportSettings |= ViewportSettings.ClearVisibleContentOnly;
view.ViewportSettings |= ViewportSettings.ClearContentOnly;
}
else
{
view.ViewportSettings &= ~ViewportSettings.ClearVisibleContentOnly;
view.ViewportSettings &= ~ViewportSettings.ClearContentOnly;
}
}
var cbDoNotClipContent = new CheckBox
{
Title = "ClipVisibleContentOnly",
Title = "ClipContentOnly",
X = Pos.Right (cbClearOnlyVisible) + 1,
Y = Pos.Top (labelContentSize),
CanFocus = false
};
cbDoNotClipContent.Checked = view.ViewportSettings.HasFlag (ViewportSettings.ClipVisibleContentOnly);
cbDoNotClipContent.Checked = view.ViewportSettings.HasFlag (ViewportSettings.ClipContentOnly);
cbDoNotClipContent.Toggled += ClipVisibleContentOnly_Toggled;
void ClipVisibleContentOnly_Toggled (object sender, StateEventArgs<bool?> e)
{
if (e.NewValue == true)
{
view.ViewportSettings |= ViewportSettings.ClipVisibleContentOnly;
view.ViewportSettings |= ViewportSettings.ClipContentOnly;
}
else
{
view.ViewportSettings &= ~ViewportSettings.ClipVisibleContentOnly;
view.ViewportSettings &= ~ViewportSettings.ClipContentOnly;
}
}

4
UnitTests/View/DrawTests.cs
View File

@@ -209,7 +209,7 @@ public class DrawTests (ITestOutputHelper output)
X = 1, Y = 1,
Width = 3, Height = 3,
BorderStyle = LineStyle.Single,
ViewportSettings = ViewportSettings.ClearVisibleContentOnly
ViewportSettings = ViewportSettings.ClearContentOnly
};
superView.Add (view);
superView.BeginInit ();
@@ -970,7 +970,7 @@ public class DrawTests (ITestOutputHelper output)
Width = Dim.Fill (),
Height = Dim.Fill (),
ContentSize = new Size (10, 10),
ViewportSettings = ViewportSettings.ClipVisibleContentOnly
ViewportSettings = ViewportSettings.ClipContentOnly
};
view.Border.Thickness = new Thickness (1);
view.BeginInit ();