diff --git a/Terminal.Gui/View/Adornment/Adornment.cs b/Terminal.Gui/View/Adornment/Adornment.cs index 1dddbe1dd..585929e99 100644 --- a/Terminal.Gui/View/Adornment/Adornment.cs +++ b/Terminal.Gui/View/Adornment/Adornment.cs @@ -8,7 +8,7 @@ /// /// /// Each of , , and has slightly different -/// behavior relative to , , keyboard input, and +/// behavior relative to , , keyboard input, and /// mouse input. Each can be customized by manipulating their Subviews. /// /// diff --git a/Terminal.Gui/View/ViewContent.cs b/Terminal.Gui/View/ViewContent.cs index ff685b2cb..90fa3ab4a 100644 --- a/Terminal.Gui/View/ViewContent.cs +++ b/Terminal.Gui/View/ViewContent.cs @@ -14,91 +14,106 @@ public enum ViewportSettings None = 0, /// - /// If set, .X can be set to negative values enabling scrolling beyond the left of the + /// If set, .X can be set to negative values enabling scrolling beyond the left of + /// the /// content area. /// /// - /// - /// When not set, .X is constrained to positive values. - /// + /// + /// When not set, .X is constrained to positive values. + /// /// AllowNegativeX = 1, /// /// If set, .Y can be set to negative values enabling scrolling beyond the top of the - /// content area. + /// content area. /// /// - /// - /// When not set, .Y is constrained to positive values. - /// + /// + /// When not set, .Y is constrained to positive values. + /// /// AllowNegativeY = 2, /// - /// If set, .Size can be set to negative coordinates enabling scrolling beyond the top-left of the + /// If set, .Size can be set to negative coordinates enabling scrolling beyond the + /// top-left of the /// content area. /// /// - /// - /// When not set, .Size is constrained to positive coordinates. - /// + /// + /// When not set, .Size is constrained to positive coordinates. + /// /// AllowNegativeLocation = AllowNegativeX | AllowNegativeY, /// - /// If set, .X can be set values greater than .Width enabling scrolling beyond the right + /// If set, .X can be set values greater than + /// .Width enabling scrolling beyond the right /// of the content area. /// /// - /// - /// When not set, .X is constrained to .Width - 1. - /// 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. - /// + /// + /// When not set, .X is constrained to + /// .Width - 1. + /// 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. + /// + /// + /// The practical effect of this is that the last column of the content will always be visible. + /// /// AllowXGreaterThanContentWidth = 4, /// - /// If set, .Y can be set values greater than .Height enabling scrolling beyond the right + /// If set, .Y can be set values greater than + /// .Height enabling scrolling beyond the right /// of the content area. /// /// - /// - /// When not set, .Y is constrained to .Height - 1. - /// 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. - /// + /// + /// When not set, .Y is constrained to + /// .Height - 1. + /// 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. + /// + /// + /// The practical effect of this is that the last row of the content will always be visible. + /// /// AllowYGreaterThanContentHeight = 8, /// - /// If set, .Size can be set values greater than enabling scrolling beyond the bottom-right + /// If set, .Size can be set values greater than + /// enabling scrolling beyond the bottom-right /// of the content area. /// /// - /// - /// When not set, is constrained to -1. - /// 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. - /// + /// + /// When not set, is constrained to -1. + /// 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. + /// /// AllowLocationGreaterThanContentSize = AllowXGreaterThanContentWidth | AllowYGreaterThanContentHeight, /// - /// By default, clipping is applied to just the visible content within . In cases where the viewport is - /// larger than the content area (e.g. when is enabled), setting this flag will allow content - /// outside the to be drawn. + /// By default, clipping is applied to the . Setting this flag will cause clipping to be + /// applied to the visible content area. /// - ClipVisibleContentOnly = 16, + ClipContentOnly = 16, /// - /// If set will clear only the portion of the content - /// area that is visible within the . 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 will clear only the portion of the content + /// area that is visible within the . 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. /// /// - /// must be set for this setting to work (clipping beyond the visible area must be disabled). + /// must be set for this setting to work (clipping beyond the visible area must be + /// disabled). /// - ClearVisibleContentOnly = 32, + ClearContentOnly = 32 } public partial class View @@ -108,8 +123,8 @@ public partial class View private Size _contentSize; /// - /// Gets or sets the size of the View's content. If the value is Size.Empty the size of the content is - /// the same as the size of , and Viewport.Location will always be 0, 0. + /// Gets or sets the size of the View's content. If not set, the value will be the same as the size of , + /// and Viewport.Location will always be 0, 0. /// /// /// @@ -159,7 +174,7 @@ public partial class View } /// - /// Event that is raised when the changes. + /// Event raised when the changes. /// public event EventHandler 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 0, 0. /// - /// Column relative to the left side of the Content. - /// Row relative to the top of the Content + /// The Screen-relative location. /// The coordinate relative to this view's Content. public Point ScreenToContent (in Point location) { @@ -246,14 +260,15 @@ public partial class View /// /// /// Positive values for the location indicate the visible area is offset into (down-and-right) the View's virtual - /// . This enables virtual scrolling. + /// . This enables scrolling down and to the right (e.g. in a . /// /// /// Negative values for the location indicate the visible area is offset above (up-and-left) the View's virtual - /// . This enables virtual zoom. + /// . This enables scrolling up and to the left (e.g. in an image viewer that supports zoom + /// where the image stays centered). /// /// - /// The property controls how scrolling is handled. If is + /// The property controls how scrolling is handled. /// /// /// If is 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 } /// - /// Fired when the changes. This event is fired after the has been updated. + /// Fired when the changes. This event is fired after the has been updated. /// [CanBeNull] public event EventHandler ViewportChanged; /// - /// Called when the changes. Invokes the event. + /// Called when the changes. Invokes the event. /// /// - protected virtual void OnViewportChanged (DrawEventArgs e) - { - ViewportChanged?.Invoke (this, e); - } + protected virtual void OnViewportChanged (DrawEventArgs e) { ViewportChanged?.Invoke (this, e); } /// /// Converts a -relative location to a screen-relative location. diff --git a/Terminal.Gui/View/ViewDrawing.cs b/Terminal.Gui/View/ViewDrawing.cs index 26e51e043..ab8518d1d 100644 --- a/Terminal.Gui/View/ViewDrawing.cs +++ b/Terminal.Gui/View/ViewDrawing.cs @@ -84,7 +84,7 @@ public partial class View /// Clears with the normal background. /// /// - /// If has only + /// If has only /// the portion of the content /// area that is visible within the will be cleared. This is useful for views that have a /// content area larger than the Viewport (e.g. when 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 /// Sets the 's clip region to . /// - /// The clip region is set to the intersection of the current clip region and the - /// . This ensures that drawing is constrained to the visible - /// viewport of the view. + /// + /// By default, the clip rectangle is set to the intersection of the current clip region and the + /// . This ensures that drawing is constrained to the viewport, but allows + /// content to be drawn beyond the viewport. + /// + /// + /// If has set, clipping will be + /// applied to just the visible content area. + /// /// /// /// 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)); diff --git a/UICatalog/Scenarios/VirtualContent.cs b/UICatalog/Scenarios/VirtualContent.cs index 2c283c7c2..07ab93719 100644 --- a/UICatalog/Scenarios/VirtualContent.cs +++ b/UICatalog/Scenarios/VirtualContent.cs @@ -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 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 e) { if (e.NewValue == true) { - view.ViewportSettings |= ViewportSettings.ClipVisibleContentOnly; + view.ViewportSettings |= ViewportSettings.ClipContentOnly; } else { - view.ViewportSettings &= ~ViewportSettings.ClipVisibleContentOnly; + view.ViewportSettings &= ~ViewportSettings.ClipContentOnly; } } diff --git a/UnitTests/View/DrawTests.cs b/UnitTests/View/DrawTests.cs index 414f9ec63..694707deb 100644 --- a/UnitTests/View/DrawTests.cs +++ b/UnitTests/View/DrawTests.cs @@ -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 ();