Fixes #4027. Add collection search matcher

Terminal.Gui/Text/CollectionNavigation.cd

@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="utf-8"?>
+<ClassDiagram MajorVersion="1" MinorVersion="1">
+  <Class Name="Terminal.Gui.CollectionNavigatorBase">
+    <Position X="5.75" Y="2" Width="2" />
+    <TypeIdentifier>
+      <HashCode>AAgEAAAAAAAQAAAIAAEAAgAAAAAABAAEAAAAACwAAAA=</HashCode>
+      <FileName>Text\CollectionNavigatorBase.cs</FileName>
+    </TypeIdentifier>
+    <ShowAsAssociation>
+      <Property Name="Matcher" />
+    </ShowAsAssociation>
+    <Lollipop Position="0.2" />
+  </Class>
+  <Class Name="Terminal.Gui.CollectionNavigator">
+    <Position X="2.75" Y="1.75" Width="2" />
+    <TypeIdentifier>
+      <HashCode>AAAAAAAAAAAAQAAAAAAAAgAAAAAAAAAEAAAAAAAAAAA=</HashCode>
+      <FileName>Text\CollectionNavigator.cs</FileName>
+    </TypeIdentifier>
+    <Lollipop Position="0.2" />
+  </Class>
+  <Class Name="Terminal.Gui.DefaultCollectionNavigatorMatcher">
+    <Position X="8.75" Y="3.75" Width="2.75" />
+    <TypeIdentifier>
+      <HashCode>AAACAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAQA=</HashCode>
+      <FileName>Text\DefaultCollectionNavigatorMatcher.cs</FileName>
+    </TypeIdentifier>
+    <Lollipop Position="0.2" />
+  </Class>
+  <Class Name="Terminal.Gui.TableCollectionNavigator" Collapsed="true">
+    <Position X="2.5" Y="6" Width="2.25" />
+    <TypeIdentifier>
+      <HashCode>AAAAAAAAAAAAAAAAAAAAAgABAAAAAAAEAAAAAAAAAAA=</HashCode>
+      <FileName>Text\TableCollectionNavigator.cs</FileName>
+    </TypeIdentifier>
+  </Class>
+  <Class Name="Terminal.Gui.ListView" Collapsed="true">
+    <Position X="0.5" Y="2.5" Width="1.5" />
+    <TypeIdentifier>
+      <HashCode>AAE+ASAkEnAAABAAKGAggYAZJAIAABEAcBAaAwAQIAA=</HashCode>
+      <FileName>Views\ListView.cs</FileName>
+    </TypeIdentifier>
+    <ShowAsAssociation>
+      <Property Name="KeystrokeNavigator" />
+    </ShowAsAssociation>
+    <Lollipop Position="0.2" />
+  </Class>
+  <Class Name="Terminal.Gui.FileDialog" Collapsed="true">
+    <Position X="0.5" Y="4.5" Width="1.75" />
+    <Compartments>
+      <Compartment Name="Nested Types" Collapsed="false" />
+    </Compartments>
+    <TypeIdentifier>
+      <HashCode>iIY4LQFUHDKVIHIESBgigQcFT6GxhBDABGJItBQAwAQ=</HashCode>
+      <FileName>Views\FileDialog.cs</FileName>
+    </TypeIdentifier>
+    <Lollipop Position="0.2" />
+  </Class>
+  <Class Name="Terminal.Gui.FileDialogCollectionNavigator" Collapsed="true">
+    <Position X="2.5" Y="4.5" Width="2.25" />
+    <TypeIdentifier>
+      <HashCode>AAAAAAAAAAAAAAAAAAAAAgAAAAAAAAAEAAAAAAAAAAA=</HashCode>
+      <FileName>Views\FileDialogCollectionNavigator.cs</FileName>
+    </TypeIdentifier>
+  </Class>
+  <Class Name="Terminal.Gui.TableView" Collapsed="true" BaseTypeListCollapsed="true">
+    <Position X="0.5" Y="6" Width="1.5" />
+    <TypeIdentifier>
+      <HashCode>QwUeAxwgICIAcABIABeR0oBAkhoFGGOBDABgAN3oPEI=</HashCode>
+      <FileName>Views\TableView\TableView.cs</FileName>
+    </TypeIdentifier>
+    <Lollipop Position="0.2" />
+  </Class>
+  <Interface Name="Terminal.Gui.ICollectionNavigatorhMatcher" Collapsed="true">
+    <Position X="8.75" Y="2.75" Width="2.75" />
+    <TypeIdentifier>
+      <HashCode>AAACAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAA=</HashCode>
+      <FileName>Text\ICollectionNavigatorhMatcher.cs</FileName>
+    </TypeIdentifier>
+  </Interface>
+  <Interface Name="Terminal.Gui.IListCollectionNavigator" Collapsed="true">
+    <Position X="2.75" Y="0.75" Width="2" />
+    <TypeIdentifier>
+      <HashCode>AAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</HashCode>
+      <FileName>Text\IListCollectionNavigator.cs</FileName>
+    </TypeIdentifier>
+  </Interface>
+  <Interface Name="Terminal.Gui.ICollectionNavigator" Collapsed="true">
+    <Position X="5.75" Y="0.75" Width="2" />
+    <TypeIdentifier>
+      <HashCode>AAgAAAAAAAAAAAAIAAAAAAAAAAAABAAAAAAAACgAAAA=</HashCode>
+      <FileName>Text\ICollectionNavigator.cs</FileName>
+    </TypeIdentifier>
+  </Interface>
+  <Font Name="Segoe UI" Size="9" />
+</ClassDiagram>

Terminal.Gui/Text/CollectionNavigator.cs

@@ -2,9 +2,9 @@
 
 namespace Terminal.Gui;
 
-/// <inheritdoc/>
+/// <inheritdoc cref="CollectionNavigatorBase"/>
 /// <remarks>This implementation is based on a static <see cref="Collection"/> of objects.</remarks>
-public class CollectionNavigator : CollectionNavigatorBase
+public class CollectionNavigator : CollectionNavigatorBase, IListCollectionNavigator
 {
     /// <summary>Constructs a new CollectionNavigator.</summary>
     public CollectionNavigator () { }
@@ -13,12 +13,12 @@ public CollectionNavigator () { }
     /// <param name="collection"></param>
     public CollectionNavigator (IList collection) { Collection = collection; }
 
-    /// <summary>The collection of objects to search. <see cref="object.ToString()"/> is used to search the collection.</summary>
+    /// <inheritdoc/>
     public IList Collection { get; set; }
 
     /// <inheritdoc/>
     protected override object ElementAt (int idx) { return Collection [idx]; }
 
     /// <inheritdoc/>
     protected override int GetCollectionLength () { return Collection.Count; }
-}
+}

Terminal.Gui/Text/CollectionNavigatorBase.cs

@@ -1,29 +1,16 @@
-using Microsoft.Extensions.Logging;
-
+#nullable enable
 namespace Terminal.Gui;
 
-/// <summary>
-///     Navigates a collection of items using keystrokes. The keystrokes are used to build a search string. The
-///     <see cref="SearchString"/> is used to find the next item in the collection that matches the search string when
-///     <see cref="GetNextMatchingItem(int, char)"/> is called.
-///     <para>
-///         If the user types keystrokes that can't be found in the collection, the search string is cleared and the next
-///         item is found that starts with the last keystroke.
-///     </para>
-///     <para>If the user pauses keystrokes for a short time (see <see cref="TypingDelay"/>), the search string is cleared.</para>
-/// </summary>
-public abstract class CollectionNavigatorBase
+/// <inheritdoc/>
+public abstract class CollectionNavigatorBase : ICollectionNavigator
 {
     private DateTime _lastKeystroke = DateTime.Now;
     private string _searchString = "";
 
-    /// <summary>The comparer function to use when searching the collection.</summary>
-    public StringComparer Comparer { get; set; } = StringComparer.InvariantCultureIgnoreCase;
+    /// <inheritdoc/>
+    public ICollectionNavigatorMatcher Matcher { get; set; } = new DefaultCollectionNavigatorMatcher();
 
-    /// <summary>
-    ///     Gets the current search string. This includes the set of keystrokes that have been pressed since the last
-    ///     unsuccessful match or after <see cref="TypingDelay"/>) milliseconds. Useful for debugging.
-    /// </summary>
+    /// <inheritdoc/>
     public string SearchString
     {
         get => _searchString;
@@ -34,22 +21,10 @@ private set
         }
     }
 
-    /// <summary>
-    ///     Gets or sets the number of milliseconds to delay before clearing the search string. The delay is reset on each
-    ///     call to <see cref="GetNextMatchingItem(int, char)"/>. The default is 500ms.
-    /// </summary>
+    /// <inheritdoc/>
     public int TypingDelay { get; set; } = 500;
 
-    /// <summary>
-    ///     Gets the index of the next item in the collection that matches the current <see cref="SearchString"/> plus the
-    ///     provided character (typically from a key press).
-    /// </summary>
-    /// <param name="currentIndex">The index in the collection to start the search from.</param>
-    /// <param name="keyStruck">The character of the key the user pressed.</param>
-    /// <returns>
-    ///     The index of the item that matches what the user has typed. Returns <see langword="-1"/> if no item in the
-    ///     collection matched.
-    /// </returns>
+    /// <inheritdoc/>
     public int GetNextMatchingItem (int currentIndex, char keyStruck)
     {
         if (!char.IsControl (keyStruck))
@@ -145,18 +120,7 @@ public int GetNextMatchingItem (int currentIndex, char keyStruck)
         return -1;
     }
 
-    /// <summary>
-    ///     Returns true if <paramref name="a"/> is a searchable key (e.g. letters, numbers, etc) that are valid to pass
-    ///     to this class for search filtering.
-    /// </summary>
-    /// <param name="a"></param>
-    /// <returns></returns>
-    public static bool IsCompatibleKey (Key a)
-    {
-        Rune rune = a.AsRune;
 
-        return rune != default (Rune) && !Rune.IsControl (rune);
-    }
 
     /// <summary>
     ///     Invoked when the <see cref="SearchString"/> changes. Useful for debugging. Invokes the
@@ -166,8 +130,7 @@ public static bool IsCompatibleKey (Key a)
     public virtual void OnSearchStringChanged (KeystrokeNavigatorEventArgs e) { SearchStringChanged?.Invoke (this, e); }
 
     /// <summary>This event is invoked when <see cref="SearchString"/>  changes. Useful for debugging.</summary>
-    [CanBeNull]
-    public event EventHandler<KeystrokeNavigatorEventArgs> SearchStringChanged;
+    public event EventHandler<KeystrokeNavigatorEventArgs>? SearchStringChanged;
 
     /// <summary>Returns the collection being navigated element at <paramref name="idx"/>.</summary>
     /// <returns></returns>
@@ -195,7 +158,7 @@ internal int GetNextMatchingItem (int currentIndex, string search, bool minimize
 
         int collectionLength = GetCollectionLength ();
 
-        if (currentIndex != -1 && currentIndex < collectionLength && IsMatch (search, ElementAt (currentIndex)))
+        if (currentIndex != -1 && currentIndex < collectionLength && Matcher.IsMatch (search, ElementAt (currentIndex)))
         {
             // we are already at a match
             if (minimizeMovement)
@@ -209,7 +172,7 @@ internal int GetNextMatchingItem (int currentIndex, string search, bool minimize
                 //circular
                 int idxCandidate = (i + currentIndex) % collectionLength;
 
-                if (IsMatch (search, ElementAt (idxCandidate)))
+                if (Matcher.IsMatch (search, ElementAt (idxCandidate)))
                 {
                     return idxCandidate;
                 }
@@ -222,7 +185,7 @@ internal int GetNextMatchingItem (int currentIndex, string search, bool minimize
         // search terms no longer match the current selection or there is none
         for (var i = 0; i < collectionLength; i++)
         {
-            if (IsMatch (search, ElementAt (i)))
+            if (Matcher.IsMatch (search, ElementAt (i)))
             {
                 return i;
             }
@@ -237,6 +200,4 @@ private void ClearSearchString ()
         SearchString = "";
         _lastKeystroke = DateTime.Now;
     }
-
-    private bool IsMatch (string search, object value) { return value?.ToString ().StartsWith (search, StringComparison.InvariantCultureIgnoreCase) ?? false; }
-}
+}

Terminal.Gui/Text/DefaultCollectionNavigatorMatcher.cs

@@ -0,0 +1,30 @@
+#nullable enable
+
+namespace Terminal.Gui;
+
+/// <summary>
+///     Default implementation of <see cref="ICollectionNavigatorMatcher"/>, performs
+///     case-insensitive (see <see cref="Comparer"/>) matching of items based on
+///     <see cref="object.ToString()"/>.
+/// </summary>
+public class DefaultCollectionNavigatorMatcher : ICollectionNavigatorMatcher
+{
+    /// <summary>The comparer function to use when searching the collection.</summary>
+    public StringComparison Comparer { get; set; } = StringComparison.InvariantCultureIgnoreCase;
+
+    /// <inheritdoc/>
+    public bool IsMatch (string search, object? value) { return value?.ToString ()?.StartsWith (search, Comparer) ?? false; }
+
+    /// <summary>
+    ///     Returns true if <paramref name="a"/> is a searchable key (e.g. letters, numbers, etc) that are valid to pass
+    ///     to this class for search filtering.
+    /// </summary>
+    /// <param name="a"></param>
+    /// <returns></returns>
+    public bool IsCompatibleKey (Key a)
+    {
+        Rune rune = a.AsRune;
+
+        return rune != default (Rune) && !Rune.IsControl (rune);
+    }
+}

Terminal.Gui/Text/ICollectionNavigator.cs

@@ -0,0 +1,48 @@
+#nullable enable
+namespace Terminal.Gui;
+
+/// <summary>
+///     Navigates a collection of items using keystrokes. The keystrokes are used to build a search string. The
+///     <see cref="SearchString"/> is used to find the next item in the collection that matches the search string when
+///     <see cref="GetNextMatchingItem(int, char)"/> is called.
+///     <para>
+///         If the user types keystrokes that can't be found in the collection, the search string is cleared and the next
+///         item is found that starts with the last keystroke.
+///     </para>
+///     <para>If the user pauses keystrokes for a short time (see <see cref="TypingDelay"/>), the search string is cleared.</para>
+/// </summary>
+public interface ICollectionNavigator
+{
+    /// <summary>
+    ///     Gets or sets the number of milliseconds to delay before clearing the search string. The delay is reset on each
+    ///     call to <see cref="GetNextMatchingItem(int, char)"/>. The default is 500ms.
+    /// </summary>
+    public int TypingDelay { get; set; }
+
+    /// <summary>This event is invoked when <see cref="SearchString"/>  changes. Useful for debugging.</summary>
+    public event EventHandler<KeystrokeNavigatorEventArgs>? SearchStringChanged;
+
+    /// <summary>
+    ///     Gets the current search string. This includes the set of keystrokes that have been pressed since the last
+    ///     unsuccessful match or after <see cref="TypingDelay"/>) milliseconds. Useful for debugging.
+    /// </summary>
+    string SearchString { get; }
+
+    /// <summary>
+    ///     Class responsible for deciding whether given entries in the collection match
+    ///     the search term the user is typing.
+    /// </summary>
+    ICollectionNavigatorMatcher Matcher { get; set; }
+
+    /// <summary>
+    ///     Gets the index of the next item in the collection that matches the current <see cref="SearchString"/> plus the
+    ///     provided character (typically from a key press).
+    /// </summary>
+    /// <param name="currentIndex">The index in the collection to start the search from.</param>
+    /// <param name="keyStruck">The character of the key the user pressed.</param>
+    /// <returns>
+    ///     The index of the item that matches what the user has typed. Returns <see langword="-1"/> if no item in the
+    ///     collection matched.
+    /// </returns>
+    int GetNextMatchingItem (int currentIndex, char keyStruck);
+}

Terminal.Gui/Text/ICollectionNavigatorMatcher.cs

@@ -0,0 +1,26 @@
+namespace Terminal.Gui;
+
+/// <summary>
+///     Determines which keys trigger collection manager navigation
+///     and how to match typed strings to objects in the collection.
+///     Default implementation is <see cref="DefaultCollectionNavigatorMatcher"/>.
+/// </summary>
+public interface ICollectionNavigatorMatcher
+{
+    /// <summary>
+    ///     Returns true if <paramref name="a"/> is a searchable key (e.g. letters, numbers, etc) that are valid to pass
+    ///     to this class for search filtering.
+    /// </summary>
+    /// <param name="a"></param>
+    /// <returns></returns>
+    bool IsCompatibleKey (Key a);
+
+    /// <summary>
+    ///     Return true if the <paramref name="value"/> matches (e.g. starts with)
+    ///     the <paramref name="search"/> term.
+    /// </summary>
+    /// <param name="search"></param>
+    /// <param name="value"></param>
+    /// <returns></returns>
+    bool IsMatch (string search, object value);
+}

Terminal.Gui/Text/IListCollectionNavigator.cs

@@ -0,0 +1,13 @@
+using System.Collections;
+
+namespace Terminal.Gui;
+
+/// <summary>
+///     <see cref="ICollectionNavigator"/> sub-interface for <see cref="ListView"/>. See also
+///     <see cref="ListView.KeystrokeNavigator"/>
+/// </summary>
+public interface IListCollectionNavigator : ICollectionNavigator
+{
+    /// <summary>The collection of objects to search. <see cref="object.ToString()"/> is used to search the collection.</summary>
+    IList Collection { get; set; }
+}