From 9692a802d036910a24a0c433dbd2091948022f1f Mon Sep 17 00:00:00 2001 From: Michael Bucari-Tovo Date: Sat, 14 May 2022 11:11:20 -0600 Subject: [PATCH] Update documentation and add parameters --- .../ProcessQueue/TrackedQueue[T].cs | 12 ++- .../ProcessQueue/VirtualFlowControl.cs | 74 ++++++++++++------- 2 files changed, 54 insertions(+), 32 deletions(-) diff --git a/Source/LibationWinForms/ProcessQueue/TrackedQueue[T].cs b/Source/LibationWinForms/ProcessQueue/TrackedQueue[T].cs index d045f818..a1f7dbe2 100644 --- a/Source/LibationWinForms/ProcessQueue/TrackedQueue[T].cs +++ b/Source/LibationWinForms/ProcessQueue/TrackedQueue[T].cs @@ -14,10 +14,14 @@ namespace LibationWinForms.ProcessQueue /* * This data structure is like lifting a metal chain one link at a time. - * Each time you grab and lift a new link, the remaining chain shortens - * by 1 link and the pile of chain at yuor feet grows by one link. The - * index is the link position from the first link you lifted to the last - * one in the chain. + * Each time you grab and lift a new link (MoveNext call): + * + * 1) you're holding a new link in your hand (Current) + * 2) the remaining chain to be lifted shortens by 1 link (Queued) + * 3) the pile of chain at your feet grows by 1 link (Completed) + * + * The index is the link position from the first link you lifted to the + * last one in the chain. */ public class TrackedQueue where T : class { diff --git a/Source/LibationWinForms/ProcessQueue/VirtualFlowControl.cs b/Source/LibationWinForms/ProcessQueue/VirtualFlowControl.cs index 2e0b34b6..b5e689b8 100644 --- a/Source/LibationWinForms/ProcessQueue/VirtualFlowControl.cs +++ b/Source/LibationWinForms/ProcessQueue/VirtualFlowControl.cs @@ -6,8 +6,8 @@ using System.Windows.Forms; namespace LibationWinForms.ProcessQueue { - internal delegate void RequestDataDelegate(int firstIndex, int numVisible, IReadOnlyList panelsToFill); - internal delegate void ControlButtonClickedDelegate(int itemIndex, string buttonName, ProcessBookControl panelClicked); + internal delegate void RequestDataDelegate(int queueIndex, int numVisible, IReadOnlyList panelsToFill); + internal delegate void ControlButtonClickedDelegate(int queueIndex, string buttonName, ProcessBookControl panelClicked); internal partial class VirtualFlowControl : UserControl { /// @@ -19,6 +19,8 @@ namespace LibationWinForms.ProcessQueue /// public event ControlButtonClickedDelegate ButtonClicked; + #region Dynamic Properties + /// /// The number of virtual s in the /// @@ -39,11 +41,18 @@ namespace LibationWinForms.ProcessQueue private int _virtualControlCount; int ScrollValue => Math.Max(vScrollBar1.Value, 0); - + /// + /// Amount the control moves with a small scroll change + /// + private int SmallScrollChange => VirtualControlHeight * SMALL_SCROLL_CHANGE_MULTIPLE; + /// + /// Amount the control moves with a large scroll change. Equal to the number of whole s in the panel, less 1. + /// + private int LargeScrollChange => Math.Max(DisplayHeight / VirtualControlHeight - 1, SMALL_SCROLL_CHANGE_MULTIPLE) * VirtualControlHeight; /// /// Virtual height of all virtual controls within this /// - private int VirtualHeight => (VirtualControlCount + 1 /*Allow extra blank space after last control*/) * VirtualControlHeight - DisplayHeight + 2 * TopMargin; + private int VirtualHeight => (VirtualControlCount + NUM_BLANK_SPACES_AT_BOTTOM) * VirtualControlHeight - DisplayHeight + 2 * TopMargin; /// /// Index of the first virtual /// @@ -52,20 +61,27 @@ namespace LibationWinForms.ProcessQueue /// The display height of this /// private int DisplayHeight => DisplayRectangle.Height; + + #endregion + + #region Instance variables + /// /// The total height, inclusing margins, of the repeated /// private readonly int VirtualControlHeight; /// - /// Amount the control moves with a small scroll change - /// - private int SmallChangeValue => VirtualControlHeight * SMALL_SCROLL_CHANGE_MULTIPLE; - /// - /// Margin between the top and the top of the Panle and the bottom and the bottom of the panel + /// Margin between the top and the top of the Panel, and the bottom and the bottom of the panel /// private readonly int TopMargin; - private const int WM_MOUSEWHEEL = 522; + private readonly VScrollBar vScrollBar1; + private readonly List BookControls = new(); + + #endregion + + #region Global behavior settings + /// /// Total number of actual controls added to the panel. 23 is sufficient up to a 4k monitor height. /// @@ -74,9 +90,12 @@ namespace LibationWinForms.ProcessQueue /// Multiple of that is moved for each small scroll change /// private const int SMALL_SCROLL_CHANGE_MULTIPLE = 1; + /// + /// Amount of space at the bottom of the , in multiples of + /// + private const int NUM_BLANK_SPACES_AT_BOTTOM = 2; - private readonly VScrollBar vScrollBar1; - private readonly List BookControls = new(); + #endregion public VirtualFlowControl() { @@ -88,17 +107,16 @@ namespace LibationWinForms.ProcessQueue Value = 0, Dock = DockStyle.Right }; - panel1.Width -= vScrollBar1.Width + panel1.Margin.Right; - Controls.Add(vScrollBar1); + vScrollBar1.Scroll += (_, s) => SetScrollPosition(s.NewValue); + panel1.Width -= vScrollBar1.Width + panel1.Margin.Right; panel1.Resize += (_, _) => { AdjustScrollBar(); DoVirtualScroll(); }; - vScrollBar1.Scroll += (_, s) => SetScrollPosition(s.NewValue); var control = InitControl(0); VirtualControlHeight = control.Height + control.Margin.Top + control.Margin.Bottom; @@ -117,9 +135,8 @@ namespace LibationWinForms.ProcessQueue panel1.Controls.Add(control); } - vScrollBar1.SmallChange = SMALL_SCROLL_CHANGE_MULTIPLE * VirtualControlHeight; - - panel1.Height += 2 * VirtualControlHeight; + vScrollBar1.SmallChange = SmallScrollChange; + panel1.Height += NUM_BLANK_SPACES_AT_BOTTOM * VirtualControlHeight; } private ProcessBookControl InitControl(int locationY) @@ -138,7 +155,7 @@ namespace LibationWinForms.ProcessQueue } /// - /// Handles all button clicks from all , detects which one sent the click, and fires + /// Handles all button clicks from all , detects which one sent the click, and fires to notify the model of the click /// private void ControlButton_Click(object sender, EventArgs e) { @@ -169,9 +186,7 @@ namespace LibationWinForms.ProcessQueue else { vScrollBar1.Enabled = true; - - //Large scroll change is almost one full window height - vScrollBar1.LargeChange = Math.Max(DisplayHeight / VirtualControlHeight - 2, SMALL_SCROLL_CHANGE_MULTIPLE) * VirtualControlHeight; + vScrollBar1.LargeChange = LargeScrollChange; //https://stackoverflow.com/a/2882878/3335599 vScrollBar1.Maximum = VirtualHeight + vScrollBar1.LargeChange - 1; @@ -180,7 +195,7 @@ namespace LibationWinForms.ProcessQueue /// /// Calculated the virtual controls that are in view at the currrent scroll position and windows size, - /// positions to simulate scroll activity, then fires for the visible controls + /// positions to simulate scroll activity, then fires to notify the model to update all visible controls /// private void DoVirtualScroll() { @@ -204,19 +219,22 @@ namespace LibationWinForms.ProcessQueue } /// - /// Set scroll value to an integral multiple of VirtualControlHeight + /// Set scroll value to an integral multiple of /// private void SetScrollPosition(int value) { - int newPos = (int)Math.Round((double)value / SmallChangeValue) * SmallChangeValue; + int newPos = (int)Math.Round((double)value / SmallScrollChange) * SmallScrollChange; if (vScrollBar1.Value != newPos) { //https://stackoverflow.com/a/2882878/3335599 - vScrollBar1.Value = Math.Min(newPos, vScrollBar1.Maximum - vScrollBar1.LargeChange +1); + vScrollBar1.Value = Math.Min(newPos, vScrollBar1.Maximum - vScrollBar1.LargeChange + 1); DoVirtualScroll(); } } + + private const int WM_MOUSEWHEEL = 522; + private const int WHEEL_DELTA = 120; protected override void WndProc(ref Message m) { //Capture mouse wheel movement and interpret it as a scroll event @@ -225,9 +243,9 @@ namespace LibationWinForms.ProcessQueue //https://docs.microsoft.com/en-us/windows/win32/inputdev/wm-mousewheel int wheelDelta = -(short)(((ulong)m.WParam) >> 16 & ushort.MaxValue); - int numSmallPositionMoves = Math.Abs(wheelDelta) / 120; + int numSmallPositionMoves = Math.Abs(wheelDelta) / WHEEL_DELTA; - int scrollDelta = Math.Sign(wheelDelta) * numSmallPositionMoves * SmallChangeValue; + int scrollDelta = Math.Sign(wheelDelta) * numSmallPositionMoves * SmallScrollChange; int newScrollPosition;