Updates IListDataSource.Render to rename the start parameter to viewportXOffset (#4392)

* Add comprehensive unit tests for WindowsKeyConverter

- Implement 118 parallelizable unit tests for WindowsKeyConverter

- Cover ToKey and ToKeyInfo methods with full bidirectional testing

- Test basic characters, modifiers, special keys, function keys

- Test VK_PACKET Unicode/IME input

- Test OEM keys, NumPad keys, and lock states

- Include round-trip conversion tests

- All tests passing successfully

Fixes #4389

* Rename `start` parameter to `viewportXOffset` for clarity

The `start` parameter in several methods and interfaces has been
renamed to `viewportXOffset` to better reflect its purpose as the
horizontal offset of the viewport during string rendering.

- Updated method signatures in `ListViewWithSelection` to use
  `viewportXOffset` instead of `start`, including default values.
- Modified the `RenderUstr` method in `ListViewWithSelection` to
  use `viewportXOffset` for calculating the starting index.
- Renamed the `start` parameter to `viewportXOffset` in the
  `IListDataSource` interface and updated its documentation.
- Replaced all occurrences of `start` with `viewportXOffset` in
  the `ListWrapper<T>` class, including method calls and logic.
- Updated the `RenderUstr` method in `ListWrapper<T>` to use
  `viewportXOffset` for substring calculations.
- Adjusted the test method in `ListViewTests.cs` to reflect the
  parameter name change.

These changes improve code readability and make the parameter's
role in rendering logic more explicit.

* Remove WindowsKeyConverterTests class that was added by mistake

* Modernized ListView and IListDataSource - Tons of new unit tests

Refactored `ListView` and `IListDataSource` to improve readability, maintainability, and functionality. Introduced `ListWrapper<T>` as a default implementation of `IListDataSource` for easier integration with standard collections.

Enhanced `ListView` with better handling of marking, selection, and scrolling. Replaced `viewportXOffset` with `viewportX` for horizontal scrolling. Added `EnsureSelectedItemVisible` to maintain visibility of the selected item.

Updated `IListDataSource` with detailed XML documentation and added `SuspendCollectionChangedEvent` for bulk updates. Improved null safety with nullable reference types.

Added comprehensive unit tests for `ListWrapper<T>` and `IListDataSource` to ensure robustness. Modernized the codebase with C# features like expression-bodied members and pattern matching. Fixed bugs related to `SelectedItem` validation and rendering artifacts.

* Improve index validation in ComboBox and ListView

Enhance robustness by adding stricter checks for valid indices
in ComboBox and ListView. Updated conditions in the
`_listview.SelectedItemChanged` event handler to ensure `e.Item`
is non-negative before accessing `_searchSet`. Modified the
`SetValue` method to use `e.Item` instead of `_listview.SelectedItem`.

In ListView, updated the `OnSelectedChanged` method to validate
that `SelectedItem` is non-negative (`>= 0`) before accessing
the `Source` list. These changes prevent potential out-of-range
errors and improve code safety.

* Refactor and enhance test coverage across modules

Refactored and added new tests to improve coverage, readability, and consistency across multiple test files. Key changes include:

- **ShortcutTests.cs**: Added tests for `BindKeyToApplication` and removed redundant tests.
- **SourcesManagerTests.cs**: Renamed `Update_*` tests to `Load_*` for clarity.
- **ArrangementTests.cs**: Reintroduced `MouseGrabHandler` tests, added `ViewArrangement` flag tests, and improved structure.
- **NeedsDrawTests.cs**: Replaced `Application.Screen.Size` with fixed dimensions for better isolation.
- **DimAutoTests.cs**: Updated layout tests to use fixed dimensions.
- **FrameTests.cs**: Standardized object initialization and validated frame behavior.
- **SubViewTests.cs**: Improved formatting and modernized event handling.
- **NumericUpDownTests.cs**: Decoupled layout tests from screen size.

General improvements:
- Enhanced formatting and removed redundant tests.
- Added comments for clarity.
- Introduced `ITestOutputHelper` for better debugging in `ArrangementTests`.

* Refactor to use nullable types for better null safety

Enabled nullable reference types across the codebase to improve null safety and prevent potential null reference issues. Refactored `SelectedItem` and related properties from `int` to `int?` to represent no selection with `null` instead of `-1`. Updated logic, event arguments, and method signatures to handle nullable values consistently.

Simplified object initialization using modern C# syntax and improved code readability with interpolated strings. Added null checks and early returns to prevent runtime errors. Enhanced error handling by throwing `ArgumentOutOfRangeException` for invalid values.

Updated tests to reflect the changes, replacing assertions for `-1` with `null` and ensuring proper handling of nullable values. Cleaned up redundant code and improved formatting for better maintainability.

* on` functionality has been deprecated, refactored, or removed from the `Shortcut` class.

* Refactor: Transition to instance-based architecture

Updated `Run-LocalCoverage.ps1` to increase `--blame-hang-timeout` from 10s to 60s. Improved null safety in `GuiTestContext` by adding null-conditional operators. Commented out problematic code in `SetupFakeApplicationAttribute.cs` to prevent test hangs.

Excluded `ViewBase` files from `UnitTests.Parallelizable.csproj` and removed redundant folder declarations. Simplified event handling in `IListDataSourceTests.cs` and updated `ListViewTests.cs` to use nullable reference types.

Enhanced documentation to emphasize the transition to an instance-based application architecture. Updated examples in `application.md`, `multitasking.md`, and `navigation.md` to reflect the use of `Application.Create()` and `View.App`. Clarified the obsolescence of the static `Application` class.

Revised table of contents in `toc.yml` to include new sections like "Application Deep Dive" and "Scheme Deep Dive." Added `dotnet-tools.json` for tool configuration.

These changes improve maintainability, testability, and alignment with modern C# practices.

* Refactor ListViewTests to use Terminal.Gui framework

The `ListViewTests` class has been refactored to replace the `AutoInitShutdown` attribute with explicit application lifecycle management using `IApplication` and `app.Init()` from the `Terminal.Gui` framework.

Key changes include:
- Rewriting tests to use `Terminal.Gui`'s application lifecycle.
- Adding a private `_output` field for logging test output via `ITestOutputHelper`.
- Updating `DriverAssert.AssertDriverContentsWithFrameAre` to include `app.Driver` for UI verification.
- Rewriting tests like `Clicking_On_Border_Is_Ignored`, `EnsureSelectedItemVisible_SelectedItem`, and others to align with the new framework.
- Adding explicit calls to `app.Shutdown()` for proper cleanup.
- Enabling nullable reference types with `#nullable enable`.
- Updating `using` directives and `namespace` to reflect the new structure.

These changes improve test maintainability, compatibility, and diagnostics.

* Update Terminal.Gui/Views/CollectionNavigation/CollectionNavigatorBase.cs

Co-authored-by: Copilot <[email protected]>

* Update Terminal.Gui/Views/CollectionNavigation/CollectionNavigatorBase.cs

Co-authored-by: Copilot <[email protected]>

* Update Examples/UICatalog/UICatalogTop.cs

Co-authored-by: Copilot <[email protected]>

* Update Terminal.Gui/Views/ListWrapper.cs

Co-authored-by: Copilot <[email protected]>

* Update Terminal.Gui/Views/ListWrapper.cs

Co-authored-by: Copilot <[email protected]>

* Updated the `SetMark` method to return `Source.IsMarked(SelectedItem.Value)` for consistency and removed an outdated comment questioning its correctness.

Enhanced the exception message in the `SelectedItem` property setter to provide clearer guidance when the value is out of range.

* Add comprehensive ListView behavior test coverage

Added multiple test methods to validate `ListView` behavior:
- `Vertical_ScrollBar_Hides_And_Shows_As_Needed`: Ensures the vertical scrollbar auto-hides/shows based on content height.
- `Mouse_Wheel_Scrolls`: Verifies vertical scrolling with the mouse wheel updates `TopItem`.
- `SelectedItem_With_Source_Null_Does_Nothing`: Confirms no exceptions occur when setting `SelectedItem` with a `null` source.
- `Horizontal_Scroll`: Tests horizontal scrolling, including programmatic and mouse wheel interactions, ensuring `LeftItem` updates correctly.
- `SetSourceAsync_SetsSource`: Validates the asynchronous `SetSourceAsync` method updates the source and item count.
- `AllowsMultipleSelection_Set_To_False_Unmarks_All_But_Selected`: Ensures disabling multiple selection unmarks all but the selected item.
- `Source_CollectionChanged_Remove`: Confirms `SelectedItem` and source count update correctly when items are removed from the source collection.

---------

Co-authored-by: Copilot <[email protected]>

Author: tig

.config/dotnet-tools.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {}
+}

Examples/UICatalog/Scenarios/AllViewsTester.cs

@@ -65,7 +65,7 @@ public override void Main ()
                                                   // Dispose existing current View, if any
                                                   DisposeCurrentView ();
 
-                                                  CreateCurrentView (_viewClasses.Values.ToArray () [_classListView.SelectedItem]);
+                                                  CreateCurrentView (_viewClasses.Values.ToArray () [_classListView.SelectedItem.Value]);
 
                                                   // Force ViewToEdit to be the view and not a subview
                                                   if (_adornmentsEditor is { })

Examples/UICatalog/Scenarios/ComboBoxIteration.cs

@@ -42,8 +42,8 @@ public override void Main ()
 
         listview.SelectedItemChanged += (s, e) =>
                                         {
-                                            lbListView.Text = items [e.Item];
-                                            comboBox.SelectedItem = e.Item;
+                                            lbListView.Text = items [e.Item!.Value];
+                                            comboBox.SelectedItem = e.Item.Value;
                                         };
 
         comboBox.SelectedItemChanged += (sender, text) =>

Examples/UICatalog/Scenarios/DynamicMenuBar.cs

@@ -712,7 +712,7 @@ public DynamicMenuBarSample ()
 
             btnUp.Accepting += (s, e) =>
                              {
-                                 int i = _lstMenus.SelectedItem;
+                                 int i = _lstMenus.SelectedItem.Value;
                                  MenuItem menuItem = DataContext.Menus.Count > 0 ? DataContext.Menus [i].MenuItem : null;
 
                                  if (menuItem != null)
@@ -734,7 +734,7 @@ public DynamicMenuBarSample ()
 
             btnDown.Accepting += (s, e) =>
                                {
-                                   int i = _lstMenus.SelectedItem;
+                                   int i = _lstMenus.SelectedItem.Value;
                                    MenuItem menuItem = DataContext.Menus.Count > 0 ? DataContext.Menus [i].MenuItem : null;
 
                                    if (menuItem != null)
@@ -836,7 +836,7 @@ public DynamicMenuBarSample ()
                                                               : MenuItemCheckStyle.Radio,
                                          ShortcutKey = frmMenuDetails.TextShortcutKey.Text
                                      };
-                                     UpdateMenuItem (_currentEditMenuBarItem, menuItem, _lstMenus.SelectedItem);
+                                     UpdateMenuItem (_currentEditMenuBarItem, menuItem, _lstMenus.SelectedItem.Value);
                                  }
                              };
 
@@ -885,8 +885,8 @@ public DynamicMenuBarSample ()
 
             btnRemove.Accepting += (s, e) =>
                                 {
-                                    MenuItem menuItem = (DataContext.Menus.Count > 0 && _lstMenus.SelectedItem > -1
-                                                             ? DataContext.Menus [_lstMenus.SelectedItem].MenuItem
+                                    MenuItem menuItem = (DataContext.Menus.Count > 0 && _lstMenus.SelectedItem is {} selectedItem
+                                                             ? DataContext.Menus [selectedItem].MenuItem
                                                              : _currentEditMenuBarItem);
 
                                     if (menuItem != null)
@@ -905,9 +905,9 @@ public DynamicMenuBarSample ()
                                             SelectCurrentMenuBarItem ();
                                         }
 
-                                        if (_lstMenus.SelectedItem > -1)
+                                        if (_lstMenus.SelectedItem is {} selected)
                                         {
-                                            DataContext.Menus?.RemoveAt (_lstMenus.SelectedItem);
+                                            DataContext.Menus?.RemoveAt (selected);
                                         }
 
                                         if (_lstMenus.Source.Count > 0 && _lstMenus.SelectedItem > _lstMenus.Source.Count - 1)
@@ -927,7 +927,7 @@ public DynamicMenuBarSample ()
 
             _lstMenus.OpenSelectedItem += (s, e) =>
                                           {
-                                              _currentMenuBarItem = DataContext.Menus [e.Item].MenuItem;
+                                              _currentMenuBarItem = DataContext.Menus [e.Item.Value].MenuItem;
 
                                               if (!(_currentMenuBarItem is MenuBarItem))
                                               {
@@ -945,8 +945,8 @@ public DynamicMenuBarSample ()
 
             _lstMenus.HasFocusChanging += (s, e) =>
                                {
-                                   MenuItem menuBarItem = _lstMenus.SelectedItem > -1 && DataContext.Menus.Count > 0
-                                                              ? DataContext.Menus [_lstMenus.SelectedItem].MenuItem
+                                   MenuItem menuBarItem = _lstMenus.SelectedItem is {} selectedItem && DataContext.Menus.Count > 0
+                                                              ? DataContext.Menus [selectedItem].MenuItem
                                                               : null;
                                    SetFrameDetails (menuBarItem);
                                };
@@ -1077,8 +1077,8 @@ void SetFrameDetails (MenuItem menuBarItem = null)
 
                 if (menuBarItem == null)
                 {
-                    menuItem = _lstMenus.SelectedItem > -1 && DataContext.Menus.Count > 0
-                                   ? DataContext.Menus [_lstMenus.SelectedItem].MenuItem
+                    menuItem = _lstMenus.SelectedItem is {} selectedItem && DataContext.Menus.Count > 0
+                                   ? DataContext.Menus [selectedItem].MenuItem
                                    : _currentEditMenuBarItem;
                 }
                 else

Examples/UICatalog/Scenarios/DynamicStatusBar.cs

@@ -312,7 +312,12 @@ public DynamicStatusBarSample ()
 
             btnUp.Accepting += (s, e) =>
                               {
-                                  int i = _lstItems.SelectedItem;
+                                  if (_lstItems.SelectedItem is null)
+                                  {
+                                      return;
+                                  }
+                                  int i = _lstItems.SelectedItem.Value;
+
                                   Shortcut statusItem = DataContext.Items.Count > 0 ? DataContext.Items [i].Shortcut : null;
 
                                   if (statusItem != null)
@@ -335,7 +340,12 @@ public DynamicStatusBarSample ()
 
             btnDown.Accepting += (s, e) =>
                                 {
-                                    int i = _lstItems.SelectedItem;
+                                    if (_lstItems.SelectedItem is null)
+                                    {
+                                        return;
+                                    }
+                                    int i = _lstItems.SelectedItem.Value;
+
                                     Shortcut statusItem = DataContext.Items.Count > 0 ? DataContext.Items [i].Shortcut : null;
 
                                     if (statusItem != null)
@@ -376,14 +386,17 @@ public DynamicStatusBarSample ()
                                   }
                                   else if (_currentEditStatusItem != null)
                                   {
-
                                       var statusItem = new DynamicStatusItem
                                       {
                                           Title = frmStatusBarDetails.TextTitle.Text,
                                           Action = frmStatusBarDetails.TextAction.Text,
                                           Shortcut = frmStatusBarDetails.TextShortcut.Text
                                       };
-                                      UpdateStatusItem (_currentEditStatusItem, statusItem, _lstItems.SelectedItem);
+
+                                      if (_lstItems.SelectedItem is { } selectedItem)
+                                      {
+                                          UpdateStatusItem (_currentEditStatusItem, statusItem, selectedItem);
+                                      }
                                   }
                               };
 
@@ -420,14 +433,14 @@ public DynamicStatusBarSample ()
             btnRemove.Accepting += (s, e) =>
                                   {
                                       Shortcut statusItem = DataContext.Items.Count > 0
-                                                                  ? DataContext.Items [_lstItems.SelectedItem].Shortcut
+                                                                  ? DataContext.Items [_lstItems.SelectedItem.Value].Shortcut
                                                                   : null;
 
                                       if (statusItem != null)
                                       {
                                           _statusBar.RemoveShortcut (_currentSelectedStatusBar);
                                           statusItem.Dispose ();
-                                          DataContext.Items.RemoveAt (_lstItems.SelectedItem);
+                                          DataContext.Items.RemoveAt (_lstItems.SelectedItem.Value);
 
                                           if (_lstItems.Source.Count > 0 && _lstItems.SelectedItem > _lstItems.Source.Count - 1)
                                           {
@@ -442,7 +455,7 @@ public DynamicStatusBarSample ()
             _lstItems.HasFocusChanging += (s, e) =>
                                {
                                    Shortcut statusItem = DataContext.Items.Count > 0
-                                                               ? DataContext.Items [_lstItems.SelectedItem].Shortcut
+                                                               ? DataContext.Items [_lstItems.SelectedItem.Value].Shortcut
                                                                : null;
                                    SetFrameDetails (statusItem);
                                };
@@ -489,7 +502,7 @@ void SetFrameDetails (Shortcut statusItem = null)
                 if (statusItem == null)
                 {
                     newStatusItem = DataContext.Items.Count > 0
-                                        ? DataContext.Items [_lstItems.SelectedItem].Shortcut
+                                        ? DataContext.Items [_lstItems.SelectedItem.Value].Shortcut
                                         : null;
                 }
                 else

Examples/UICatalog/Scenarios/ListViewWithSelection.cs

@@ -237,7 +237,7 @@ public void Render (
             int col,
             int line,
             int width,
-            int start = 0
+            int viewportX = 0
         )
         {
             container.Move (col, line);
@@ -247,7 +247,7 @@ public void Render (
                                       string.Format ("{{0,{0}}}", -_nameColumnWidth),
                                       Scenarios [item].GetName ()
                                      );
-            RenderUstr (container, $"{s} ({Scenarios [item].GetDescription ()})", col, line, width, start);
+            RenderUstr (container, $"{s} ({Scenarios [item].GetDescription ()})", col, line, width, viewportX);
         }
 
         public void SetMark (int item, bool value)
@@ -288,10 +288,10 @@ Scenarios [i].GetName ()
         }
 
         // A slightly adapted method from: https://github.com/gui-cs/Terminal.Gui/blob/fc1faba7452ccbdf49028ac49f0c9f0f42bbae91/Terminal.Gui/Views/ListView.cs#L433-L461
-        private void RenderUstr (View view, string ustr, int col, int line, int width, int start = 0)
+        private void RenderUstr (View view, string ustr, int col, int line, int width, int viewportX = 0)
         {
             var used = 0;
-            int index = start;
+            int index = viewportX;
 
             while (index < ustr.Length)
             {

Examples/UICatalog/Scenarios/ListsAndCombos.cs

@@ -50,7 +50,7 @@ public override void Main ()
             Width = Dim.Percent (40),
             Source = new ListWrapper<string> (items)
         };
-        listview.SelectedItemChanged += (s, e) => lbListView.Text = items [listview.SelectedItem];
+        listview.SelectedItemChanged += (s, e) => lbListView.Text = items [listview.SelectedItem.Value];
         win.Add (lbListView, listview);
 
         //var scrollBar = new ScrollBarView (listview, true);

Examples/UICatalog/Scenarios/SpinnerStyles.cs

@@ -153,7 +153,7 @@ public override void Main ()
                                           else
                                           {
                                               spinner.Visible = true;
-                                              spinner.Style = (SpinnerStyle)Activator.CreateInstance (styleDict [e.Item].Value);
+                                              spinner.Style = (SpinnerStyle)Activator.CreateInstance (styleDict [e.Item.Value].Value);
                                               delayField.Text = spinner.SpinDelay.ToString ();
                                               ckbBounce.CheckedState = spinner.SpinBounce ? CheckState.Checked : CheckState.UnChecked;
                                               ckbNoSpecial.CheckedState = !spinner.HasSpecialCharacters ? CheckState.Checked : CheckState.UnChecked;

Examples/UICatalog/UICatalogTop.cs

@@ -43,7 +43,11 @@ public UICatalogTop ()
         Unloaded += UnloadedHandler;
 
         // Restore previous selections
-        _categoryList.SelectedItem = _cachedCategoryIndex;
+        if (_categoryList.Source?.Count > 0) {
+            _categoryList.SelectedItem = _cachedCategoryIndex ?? 0;
+        } else {
+            _categoryList.SelectedItem = null;
+        }
         _scenarioList.SelectedRow = _cachedScenarioIndex;
 
         SchemeName = CachedTopLevelScheme = SchemeManager.SchemesToSchemeName (Schemes.Base);
@@ -510,7 +514,7 @@ private void ScenarioView_OpenSelectedItem (object? sender, EventArgs? e)
     #region Category List
 
     private readonly ListView? _categoryList;
-    private static int _cachedCategoryIndex;
+    private static int? _cachedCategoryIndex;
     public static ObservableCollection<string>? CachedCategories { get; set; }
 
     private ListView CreateCategoryList ()
@@ -540,7 +544,11 @@ private ListView CreateCategoryList ()
 
     private void CategoryView_SelectedChanged (object? sender, ListViewItemEventArgs? e)
     {
-        string item = CachedCategories! [e!.Item];
+        if (e is null or { Item: null })
+        {
+            return;
+        }
+        string item = CachedCategories! [e.Item.Value];
         ObservableCollection<Scenario> newScenarioList;
 
         if (e.Item == 0)

Scripts/Run-LocalCoverage.ps1

@@ -27,7 +27,7 @@ dotnet test Tests/UnitTests `
   --verbosity minimal `
   --collect:"XPlat Code Coverage" `
   --settings Tests/UnitTests/runsettings.coverage.xml `
-  --blame-hang-timeout 10s
+  --blame-hang-timeout 60s
 
 # ------------------------------------------------------------
 # 4. Run UNIT TESTS (parallel)