Code cleanup

Terminal.Gui/View/View.Keyboard.cs

@@ -27,7 +27,7 @@ public partial class View // Keyboard APIs
 
     #region HotKey Support
 
-    /// <summary>Invoked when the <see cref="HotKey"/> is changed.</summary>
+    /// <summary>Raised when the <see cref="HotKey"/> is changed.</summary>
     public event EventHandler<KeyChangedEventArgs>? HotKeyChanged;
 
     private Key _hotKey = new ();
@@ -254,13 +254,13 @@ public partial class View // Keyboard APIs
     ///         first.
     ///     </para>
     ///     <para>
-    ///         If the focused sub view does not handle the key press, this method raises <see cref="OnKeyDown"/>/
+    ///         If a more focused subview does not handle the key press, this method raises <see cref="OnKeyDown"/>/
     ///         <see cref="KeyDown"/> to allow the
     ///         view to pre-process the key press. If <see cref="OnKeyDown"/>/<see cref="KeyDown"/> is not handled
     ///         <see cref="InvokingKeyBindings"/>/<see cref="OnInvokingKeyBindings"/>  will be raised to invoke any key
     ///         bindings.
     ///         Then, only if no key bindings are
-    ///         handled, <see cref="OnProcessKeyDown"/>/<see cref="ProcessKeyDown"/> will be raised allowing the view to
+    ///         handled, <see cref="OnKeyDownNotHandled"/>/<see cref="KeyDownNotHandled"/> will be raised allowing the view to
     ///         process the key press.
     ///     </para>
     ///     <para>
@@ -301,7 +301,7 @@ public partial class View // Keyboard APIs
 
         // After
         // TODO: Is ProcessKeyDown really the right name?
-        if (RaiseProcessKeyDown (key) || key.Handled)
+        if (RaiseKeyDownNotHandled (key) || key.Handled)
         {
             return true;
         }
@@ -322,14 +322,14 @@ public partial class View // Keyboard APIs
             return k.Handled;
         }
 
-        bool RaiseProcessKeyDown (Key k)
+        bool RaiseKeyDownNotHandled (Key k)
         {
-            if (OnProcessKeyDown (k) || k.Handled)
+            if (OnKeyDownNotHandled (k) || k.Handled)
             {
                 return true;
             }
 
-            ProcessKeyDown?.Invoke (this, k);
+            KeyDownNotHandled?.Invoke (this, k);
 
             return false;
         }
@@ -337,14 +337,14 @@ public partial class View // Keyboard APIs
 
     /// <summary>
     ///     Called when the user presses a key, allowing subscribers to pre-process the key down event. Called
-    ///     before <see cref="InvokingKeyBindings"/> and <see cref="ProcessKeyDown"/> are raised. Set <see cref="Key.Handled"/>
+    ///     before <see cref="InvokingKeyBindings"/> and <see cref="KeyDownNotHandled"/> are raised. Set <see cref="Key.Handled"/>
     ///     to true to
-    ///     stop the key from being processed by other views.
+    ///     stop the key from being processed further.
     /// </summary>
-    /// <param name="key">Contains the details about the key that produced the event.</param>
+    /// <param name="key">The key that produced the event.</param>
     /// <returns>
-    ///     <see langword="false"/> if the key press was not handled. <see langword="true"/> if the keypress was handled
-    ///     and no other view should see it.
+    ///     <see langword="false"/> if the key down event was not handled. <see langword="true"/> if the event was handled
+    ///     and processing should stop.
     /// </returns>
     /// <remarks>
     ///     <para>
@@ -356,9 +356,10 @@ public partial class View // Keyboard APIs
     protected virtual bool OnKeyDown (Key key) { return false; }
 
     /// <summary>
-    ///     Raised when the user presses a key, allowing subscribers to pre-process the key down event. Raised
-    ///     before <see cref="InvokingKeyBindings"/> and <see cref="ProcessKeyDown"/>. Set <see cref="Key.Handled"/> to true to
-    ///     stop the key from being processed by other views.
+    ///     Raised when the user presses a key, allowing subscribers to pre-process the key down event. Called
+    ///     before <see cref="InvokingKeyBindings"/> and <see cref="KeyDownNotHandled"/> are raised. Set <see cref="Key.Handled"/>
+    ///     to true to
+    ///     stop the key from being processed further.
     /// </summary>
     /// <remarks>
     ///     <para>
@@ -370,8 +371,7 @@ public partial class View // Keyboard APIs
     public event EventHandler<Key>? KeyDown;
 
     /// <summary>
-    ///     Called when the user presses a key, allowing views do things during key down events. This is
-    ///     called after the <see cref="KeyDown"/> after <see cref="InvokingKeyBindings"/> are raised.
+    ///     Called when the user has pressed key it wasn't handled by <see cref="KeyDown"/> and was not bound to a key binding.
     /// </summary>
     /// <remarks>
     ///     <para>
@@ -388,12 +388,10 @@ public partial class View // Keyboard APIs
     ///     <see langword="false"/> if the key press was not handled. <see langword="true"/> if the keypress was handled
     ///     and no other view should see it.
     /// </returns>
-    protected virtual bool OnProcessKeyDown (Key key) { return key.Handled; }
+    protected virtual bool OnKeyDownNotHandled (Key key) { return key.Handled; }
 
     /// <summary>
-    ///     Raised when the user presses a key, allowing subscribers to do things during key down events. Set
-    ///     <see cref="Key.Handled"/> to true to stop the key from being processed by other views. Invoked after
-    ///     <see cref="KeyDown"/> and <see cref="InvokingKeyBindings"/>.
+    ///     Raised when the user has pressed key it wasn't handled by <see cref="KeyDown"/> and was not bound to a key binding.
     /// </summary>
     /// <remarks>
     ///     <para>
@@ -401,12 +399,12 @@ public partial class View // Keyboard APIs
     ///         <see cref="KeyBindings.Add(Key, Command[])"/>instead.
     ///     </para>
     ///     <para>
-    ///         SubViews can use the <see cref="ProcessKeyDown"/> of their super view override the default behavior of when
+    ///         SubViews can use the <see cref="KeyDownNotHandled"/> of their super view override the default behavior of when
     ///         key bindings are invoked.
     ///     </para>
     ///     <para>See <see href="../docs/keyboard.md">for an overview of Terminal.Gui keyboard APIs.</see></para>
     /// </remarks>
-    public event EventHandler<Key>? ProcessKeyDown;
+    public event EventHandler<Key>? KeyDownNotHandled;
 
     #endregion KeyDown Event
 
@@ -469,7 +467,7 @@ public partial class View // Keyboard APIs
         }
     }
 
-    /// <summary>Method invoked when a key is released. This method is called from <see cref="NewKeyUpEvent"/>.</summary>
+    /// <summary>Called when a key is released. This method is called from <see cref="NewKeyUpEvent"/>.</summary>
     /// <param name="key">Contains the details about the key that produced the event.</param>
     /// <returns>
     ///     <see langword="false"/> if the keys up event was not handled. <see langword="true"/> if no other view should see
@@ -487,7 +485,7 @@ public partial class View // Keyboard APIs
     public virtual bool OnKeyUp (Key key) { return false; }
 
     /// <summary>
-    ///     Invoked when a key is released. Set <see cref="Key.Handled"/> to true to stop the key up event from being processed
+    ///     Raised when a key is released. Set <see cref="Key.Handled"/> to true to stop the key up event from being processed
     ///     by other views.
     ///     <remarks>
     ///         Not all terminals support key distinct down/up notifications, Applications should avoid depending on
@@ -509,7 +507,7 @@ public partial class View // Keyboard APIs
     private Dictionary<Command, CommandImplementation> CommandImplementations { get; } = new ();
 
     /// <summary>
-    /// 
+    ///     INTERNAL API: Raises the <see cref="InvokingKeyBindings"/> event and invokes the commands bound to <paramref name="key"/>.
     /// </summary>
     /// <param name="key"></param>
     /// <returns>
@@ -576,12 +574,37 @@ public partial class View // Keyboard APIs
         }
 
         return handled;
+    }
 
+    /// <summary>
+    ///     Called when a key is pressed that may be mapped to a key binding. Set <see cref="Key.Handled"/> to true to
+    ///     stop the key from being processed by other views.
+    /// </summary>
+    /// <remarks>
+    ///     <para>See <see href="../docs/keyboard.md">for an overview of Terminal.Gui keyboard APIs.</see></para>
+    /// </remarks>
+    /// <param name="key">Contains the details about the key that produced the event.</param>
+    /// <param name="scope">The scope.</param>
+    /// <returns>
+    ///     <see langword="false"/> if the event was raised and was not handled (or cancelled); input processing should
+    ///     continue.
+    ///     <see langword="true"/> if the event was raised and handled (or cancelled); input processing should stop.
+    /// </returns>
+    protected virtual bool OnInvokingKeyBindings (Key key, KeyBindingScope scope)
+    {
+        return false;
     }
 
+    // TODO: This does not carry KeyBindingScope, but OnInvokingKeyBindings does
+    /// <summary>
+    ///     Raised when a key is pressed that may be mapped to a key binding. Set <see cref="Key.Handled"/> to true to
+    ///     stop the key from being processed by other views.
+    /// </summary>
+    public event EventHandler<Key>? InvokingKeyBindings;
+
     private bool ProcessAdornmentKeyBindings (Adornment adornment, Key key, KeyBindingScope scope, ref bool? handled)
     {
-        bool? adornmentHandled = adornment.OnInvokingKeyBindings (key, scope);
+        bool? adornmentHandled = adornment.RaiseInvokingKeyBindingsAndInvokeCommands (key);
 
         if (adornmentHandled is true)
         {
@@ -595,7 +618,7 @@ public partial class View // Keyboard APIs
 
         foreach (View subview in adornment.Subviews)
         {
-            bool? subViewHandled = subview.OnInvokingKeyBindings (key, scope);
+            bool? subViewHandled = subview.RaiseInvokingKeyBindingsAndInvokeCommands (key);
 
             if (subViewHandled is { })
             {
@@ -689,33 +712,6 @@ public partial class View // Keyboard APIs
         return false;
     }
 
-
-    /// <summary>
-    ///     Called when a key is pressed that may be mapped to a key binding. Set <see cref="Key.Handled"/> to true to
-    ///     stop the key from being processed by other views.
-    /// </summary>
-    /// <remarks>
-    ///     <para>See <see href="../docs/keyboard.md">for an overview of Terminal.Gui keyboard APIs.</see></para>
-    /// </remarks>
-    /// <param name="key">Contains the details about the key that produced the event.</param>
-    /// <param name="scope">The scope.</param>
-    /// <returns>
-    ///     <see langword="false"/> if the event was raised and was not handled (or cancelled); input processing should
-    ///     continue.
-    ///     <see langword="true"/> if the event was raised and handled (or cancelled); input processing should stop.
-    /// </returns>
-    protected virtual bool OnInvokingKeyBindings (Key key, KeyBindingScope scope)
-    {
-        return false;
-    }
-
-    // TODO: This does not carry KeyBindingScope, but OnInvokingKeyBindings does
-    /// <summary>
-    ///     Raised when a key is pressed that may be mapped to a key binding. Set <see cref="Key.Handled"/> to true to
-    ///     stop the key from being processed by other views.
-    /// </summary>
-    public event EventHandler<Key>? InvokingKeyBindings;
-
     /// <summary>
     ///     Invokes the Commands bound to <paramref name="key"/>.
     ///     <para>See <see href="../docs/keyboard.md">for an overview of Terminal.Gui keyboard APIs.</see></para>

Terminal.Gui/Views/DateField.cs

@@ -131,7 +131,7 @@ public class DateField : TextField
     public virtual void OnDateChanged (DateTimeEventArgs<DateTime> args) { DateChanged?.Invoke (this, args); }
 
     /// <inheritdoc/>
-    protected override bool OnProcessKeyDown (Key a)
+    protected override bool OnKeyDownNotHandled (Key a)
     {
         // Ignore non-numeric characters.
         if (a >= Key.D0 && a <= Key.D9)

Terminal.Gui/Views/HexView.cs

@@ -452,7 +452,7 @@ public class HexView : View, IDesignable
     public virtual void OnPositionChanged () { PositionChanged?.Invoke (this, new HexViewEventArgs (Position, CursorPosition, BytesPerLine)); }
 
     /// <inheritdoc/>
-    protected override bool OnProcessKeyDown (Key keyEvent)
+    protected override bool OnKeyDownNotHandled (Key keyEvent)
     {
         if (!AllowEdits)
         {

Terminal.Gui/Views/Menu/Menu.cs

@@ -306,7 +306,7 @@ internal sealed class Menu : View
     }
 
     /// <inheritdoc />
-    protected override bool OnProcessKeyDown (Key keyEvent)
+    protected override bool OnKeyDownNotHandled (Key keyEvent)
     {
         // We didn't handle the key, pass it on to host
         return _host.RaiseInvokingKeyBindingsAndInvokeCommands (keyEvent) == true;

Terminal.Gui/Views/TextField.cs

@@ -1037,25 +1037,8 @@ public class TextField : View
         //	ClearAllSelection ();
     }
 
-    /// TODO: Flush out these docs
-    /// <summary>
-    ///     Processes key presses for the <see cref="TextField"/>.
-    ///     <remarks>
-    ///         The <see cref="TextField"/> control responds to the following keys:
-    ///         <list type="table">
-    ///             <listheader>
-    ///                 <term>Keys</term> <description>Function</description>
-    ///             </listheader>
-    ///             <item>
-    ///                 <term><see cref="Key.Delete"/>, <see cref="Key.Backspace"/></term>
-    ///                 <description>Deletes the character before cursor.</description>
-    ///             </item>
-    ///         </list>
-    ///     </remarks>
-    /// </summary>
-    /// <param name="a"></param>
-    /// <returns></returns>
-    protected override bool OnProcessKeyDown (Key a)
+    /// <inheritdoc />
+    protected override bool OnKeyDownNotHandled (Key a)
     {
         // Remember the cursor position because the new calculated cursor position is needed
         // to be set BEFORE the TextChanged event is triggered.

Terminal.Gui/Views/TextValidateField.cs

@@ -597,7 +597,7 @@ namespace Terminal.Gui
         }
 
         /// <inheritdoc/>
-        protected override bool OnProcessKeyDown (Key a)
+        protected override bool OnKeyDownNotHandled (Key a)
         {
             if (_provider is null)
             {

Terminal.Gui/Views/TextView.cs

@@ -3703,7 +3703,7 @@ public class TextView : View
     }
 
     /// <inheritdoc/>
-    protected override bool OnProcessKeyDown (Key a)
+    protected override bool OnKeyDownNotHandled (Key a)
     {
         if (!CanFocus)
         {

Terminal.Gui/Views/TileView.cs

@@ -286,7 +286,7 @@ public class TileView : View
 
     //// BUGBUG: Why is this not handled by a key binding???
     /// <inheritdoc/>
-    protected override bool OnProcessKeyDown (Key keyEvent)
+    protected override bool OnKeyDownNotHandled (Key keyEvent)
     {
         var focusMoved = false;
 

Terminal.Gui/Views/TimeField.cs

@@ -177,7 +177,7 @@ public class TimeField : TextField
     }
 
     /// <inheritdoc/>
-    protected override bool OnProcessKeyDown (Key a)
+    protected override bool OnKeyDownNotHandled (Key a)
     {
         // Ignore non-numeric characters.
         if (a.KeyCode is >= (KeyCode)(int)KeyCode.D0 and <= (KeyCode)(int)KeyCode.D9)

Terminal.Gui/Views/Wizard/Wizard.cs

@@ -381,12 +381,12 @@ public class Wizard : Dialog
     /// <summary>
     ///     <see cref="Wizard"/> is derived from <see cref="Dialog"/> and Dialog causes <c>Esc</c> to call
     ///     <see cref="Application.RequestStop(Toplevel)"/>, closing the Dialog. Wizard overrides
-    ///     <see cref="OnProcessKeyDown"/> to instead fire the <see cref="Cancelled"/> event when Wizard is being used as a
+    ///     <see cref="OnKeyDownNotHandled"/> to instead fire the <see cref="Cancelled"/> event when Wizard is being used as a
     ///     non-modal (see <see cref="Wizard.Modal"/>).
     /// </summary>
     /// <param name="key"></param>
     /// <returns></returns>
-    protected override bool OnProcessKeyDown (Key key)
+    protected override bool OnKeyDownNotHandled (Key key)
     {
         //// BUGBUG: Why is this not handled by a key binding???
         if (!Modal)

UnitTests/View/Keyboard/KeyboardEventTests.cs

@@ -43,7 +43,7 @@ public class KeyboardEventTests (ITestOutputHelper output) : TestsAllViews
 
         var keyDownProcessed = false;
 
-        view.ProcessKeyDown += (s, a) =>
+        view.KeyDownNotHandled += (s, a) =>
                                {
                                    a.Handled = true;
                                    keyDownProcessed = true;
@@ -112,7 +112,7 @@ public class KeyboardEventTests (ITestOutputHelper output) : TestsAllViews
                             Assert.True (view.OnKeyDownCalled);
                             keyDown = true;
                         };
-        view.ProcessKeyDown += (s, e) => { keyPressed = true; };
+        view.KeyDownNotHandled += (s, e) => { keyPressed = true; };
 
         view.KeyUp += (s, e) =>
                       {
@@ -178,7 +178,7 @@ public class KeyboardEventTests (ITestOutputHelper output) : TestsAllViews
                                         Assert.Equal (KeyCode.N, e.KeyCode);
                                     };
 
-        view.ProcessKeyDown += (s, e) =>
+        view.KeyDownNotHandled += (s, e) =>
                                {
                                    processKeyPressInvoked = true;
                                    processKeyPressInvoked = true;
@@ -230,7 +230,7 @@ public class KeyboardEventTests (ITestOutputHelper output) : TestsAllViews
                                         invokingKeyBindings = true;
                                     };
 
-        view.ProcessKeyDown += (s, e) =>
+        view.KeyDownNotHandled += (s, e) =>
                                {
                                    Assert.Equal (KeyCode.A, e.KeyCode);
                                    Assert.False (keyPressed);
@@ -278,7 +278,7 @@ public class KeyboardEventTests (ITestOutputHelper output) : TestsAllViews
                                         invokingKeyBindings = true;
                                     };
 
-        view.ProcessKeyDown += (s, e) =>
+        view.KeyDownNotHandled += (s, e) =>
                                {
                                    Assert.Equal (KeyCode.A, e.KeyCode);
                                    Assert.False (keyPressed);
@@ -319,7 +319,7 @@ public class KeyboardEventTests (ITestOutputHelper output) : TestsAllViews
                                         Assert.Equal (KeyCode.N, e.KeyCode);
                                     };
 
-        view.ProcessKeyDown += (s, e) =>
+        view.KeyDownNotHandled += (s, e) =>
                                {
                                    processKeyPressInvoked = true;
                                    Assert.False (e.Handled);
@@ -367,7 +367,7 @@ public class KeyboardEventTests (ITestOutputHelper output) : TestsAllViews
                                         invokingKeyBindings = true;
                                     };
 
-        view.ProcessKeyDown += (s, e) =>
+        view.KeyDownNotHandled += (s, e) =>
                                {
                                    Assert.Equal (KeyCode.A, e.KeyCode);
                                    Assert.False (processKeyDown);
@@ -472,7 +472,7 @@ public class KeyboardEventTests (ITestOutputHelper output) : TestsAllViews
             return CancelVirtualMethods;
         }
 
-        protected override bool OnProcessKeyDown (Key keyEvent)
+        protected override bool OnKeyDownNotHandled (Key keyEvent)
         {
             OnProcessKeyDownCalled = true;
 

UnitTests/View/ViewTests.cs

@@ -1146,7 +1146,7 @@ At 0,0
             return true;
         }
 
-        protected override bool OnProcessKeyDown (Key keyEvent)
+        protected override bool OnKeyDownNotHandled (Key keyEvent)
         {
             IsKeyPress = true;