diff --git a/Terminal.Gui/View/View.Keyboard.cs b/Terminal.Gui/View/View.Keyboard.cs index e3b2ab2ba..2bb4b3da6 100644 --- a/Terminal.Gui/View/View.Keyboard.cs +++ b/Terminal.Gui/View/View.Keyboard.cs @@ -27,7 +27,7 @@ public partial class View // Keyboard APIs #region HotKey Support - /// Invoked when the is changed. + /// Raised when the is changed. public event EventHandler? HotKeyChanged; private Key _hotKey = new (); @@ -254,13 +254,13 @@ public partial class View // Keyboard APIs /// first. /// /// - /// If the focused sub view does not handle the key press, this method raises / + /// If a more focused subview does not handle the key press, this method raises / /// to allow the /// view to pre-process the key press. If / is not handled /// / will be raised to invoke any key /// bindings. /// Then, only if no key bindings are - /// handled, / will be raised allowing the view to + /// handled, / will be raised allowing the view to /// process the key press. /// /// @@ -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 /// /// Called when the user presses a key, allowing subscribers to pre-process the key down event. Called - /// before and are raised. Set + /// before and are raised. Set /// to true to - /// stop the key from being processed by other views. + /// stop the key from being processed further. /// - /// Contains the details about the key that produced the event. + /// The key that produced the event. /// - /// if the key press was not handled. if the keypress was handled - /// and no other view should see it. + /// if the key down event was not handled. if the event was handled + /// and processing should stop. /// /// /// @@ -356,9 +356,10 @@ public partial class View // Keyboard APIs protected virtual bool OnKeyDown (Key key) { return false; } /// - /// Raised when the user presses a key, allowing subscribers to pre-process the key down event. Raised - /// before and . Set 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 and are raised. Set + /// to true to + /// stop the key from being processed further. /// /// /// @@ -370,8 +371,7 @@ public partial class View // Keyboard APIs public event EventHandler? KeyDown; /// - /// Called when the user presses a key, allowing views do things during key down events. This is - /// called after the after are raised. + /// Called when the user has pressed key it wasn't handled by and was not bound to a key binding. /// /// /// @@ -388,12 +388,10 @@ public partial class View // Keyboard APIs /// if the key press was not handled. if the keypress was handled /// and no other view should see it. /// - protected virtual bool OnProcessKeyDown (Key key) { return key.Handled; } + protected virtual bool OnKeyDownNotHandled (Key key) { return key.Handled; } /// - /// Raised when the user presses a key, allowing subscribers to do things during key down events. Set - /// to true to stop the key from being processed by other views. Invoked after - /// and . + /// Raised when the user has pressed key it wasn't handled by and was not bound to a key binding. /// /// /// @@ -401,12 +399,12 @@ public partial class View // Keyboard APIs /// instead. /// /// - /// SubViews can use the of their super view override the default behavior of when + /// SubViews can use the of their super view override the default behavior of when /// key bindings are invoked. /// /// See for an overview of Terminal.Gui keyboard APIs. /// - public event EventHandler? ProcessKeyDown; + public event EventHandler? KeyDownNotHandled; #endregion KeyDown Event @@ -469,7 +467,7 @@ public partial class View // Keyboard APIs } } - /// Method invoked when a key is released. This method is called from . + /// Called when a key is released. This method is called from . /// Contains the details about the key that produced the event. /// /// if the keys up event was not handled. if no other view should see @@ -487,7 +485,7 @@ public partial class View // Keyboard APIs public virtual bool OnKeyUp (Key key) { return false; } /// - /// Invoked when a key is released. Set to true to stop the key up event from being processed + /// Raised when a key is released. Set to true to stop the key up event from being processed /// by other views. /// /// 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 CommandImplementations { get; } = new (); /// - /// + /// INTERNAL API: Raises the event and invokes the commands bound to . /// /// /// @@ -576,12 +574,37 @@ public partial class View // Keyboard APIs } return handled; - } + /// + /// Called when a key is pressed that may be mapped to a key binding. Set to true to + /// stop the key from being processed by other views. + /// + /// + /// See for an overview of Terminal.Gui keyboard APIs. + /// + /// Contains the details about the key that produced the event. + /// The scope. + /// + /// if the event was raised and was not handled (or cancelled); input processing should + /// continue. + /// if the event was raised and handled (or cancelled); input processing should stop. + /// + protected virtual bool OnInvokingKeyBindings (Key key, KeyBindingScope scope) + { + return false; + } + + // TODO: This does not carry KeyBindingScope, but OnInvokingKeyBindings does + /// + /// Raised when a key is pressed that may be mapped to a key binding. Set to true to + /// stop the key from being processed by other views. + /// + public event EventHandler? 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; } - - /// - /// Called when a key is pressed that may be mapped to a key binding. Set to true to - /// stop the key from being processed by other views. - /// - /// - /// See for an overview of Terminal.Gui keyboard APIs. - /// - /// Contains the details about the key that produced the event. - /// The scope. - /// - /// if the event was raised and was not handled (or cancelled); input processing should - /// continue. - /// if the event was raised and handled (or cancelled); input processing should stop. - /// - protected virtual bool OnInvokingKeyBindings (Key key, KeyBindingScope scope) - { - return false; - } - - // TODO: This does not carry KeyBindingScope, but OnInvokingKeyBindings does - /// - /// Raised when a key is pressed that may be mapped to a key binding. Set to true to - /// stop the key from being processed by other views. - /// - public event EventHandler? InvokingKeyBindings; - /// /// Invokes the Commands bound to . /// See for an overview of Terminal.Gui keyboard APIs. diff --git a/Terminal.Gui/Views/DateField.cs b/Terminal.Gui/Views/DateField.cs index 43060c0a5..49da4f100 100644 --- a/Terminal.Gui/Views/DateField.cs +++ b/Terminal.Gui/Views/DateField.cs @@ -131,7 +131,7 @@ public class DateField : TextField public virtual void OnDateChanged (DateTimeEventArgs args) { DateChanged?.Invoke (this, args); } /// - protected override bool OnProcessKeyDown (Key a) + protected override bool OnKeyDownNotHandled (Key a) { // Ignore non-numeric characters. if (a >= Key.D0 && a <= Key.D9) diff --git a/Terminal.Gui/Views/HexView.cs b/Terminal.Gui/Views/HexView.cs index 8f7e3c1a0..a5a213b82 100644 --- a/Terminal.Gui/Views/HexView.cs +++ b/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)); } /// - protected override bool OnProcessKeyDown (Key keyEvent) + protected override bool OnKeyDownNotHandled (Key keyEvent) { if (!AllowEdits) { diff --git a/Terminal.Gui/Views/Menu/Menu.cs b/Terminal.Gui/Views/Menu/Menu.cs index 9ee580d49..b3429b190 100644 --- a/Terminal.Gui/Views/Menu/Menu.cs +++ b/Terminal.Gui/Views/Menu/Menu.cs @@ -306,7 +306,7 @@ internal sealed class Menu : View } /// - 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; diff --git a/Terminal.Gui/Views/TextField.cs b/Terminal.Gui/Views/TextField.cs index d1cfed3b1..cb6d2e82a 100644 --- a/Terminal.Gui/Views/TextField.cs +++ b/Terminal.Gui/Views/TextField.cs @@ -1037,25 +1037,8 @@ public class TextField : View // ClearAllSelection (); } - /// TODO: Flush out these docs - /// - /// Processes key presses for the . - /// - /// The control responds to the following keys: - /// - /// - /// Keys Function - /// - /// - /// , - /// Deletes the character before cursor. - /// - /// - /// - /// - /// - /// - protected override bool OnProcessKeyDown (Key a) + /// + 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. diff --git a/Terminal.Gui/Views/TextValidateField.cs b/Terminal.Gui/Views/TextValidateField.cs index 579b22f56..c6927b5e3 100644 --- a/Terminal.Gui/Views/TextValidateField.cs +++ b/Terminal.Gui/Views/TextValidateField.cs @@ -597,7 +597,7 @@ namespace Terminal.Gui } /// - protected override bool OnProcessKeyDown (Key a) + protected override bool OnKeyDownNotHandled (Key a) { if (_provider is null) { diff --git a/Terminal.Gui/Views/TextView.cs b/Terminal.Gui/Views/TextView.cs index 4cc86bf2f..97ccc47a9 100644 --- a/Terminal.Gui/Views/TextView.cs +++ b/Terminal.Gui/Views/TextView.cs @@ -3703,7 +3703,7 @@ public class TextView : View } /// - protected override bool OnProcessKeyDown (Key a) + protected override bool OnKeyDownNotHandled (Key a) { if (!CanFocus) { diff --git a/Terminal.Gui/Views/TileView.cs b/Terminal.Gui/Views/TileView.cs index 4adbb5b1b..ec117c652 100644 --- a/Terminal.Gui/Views/TileView.cs +++ b/Terminal.Gui/Views/TileView.cs @@ -286,7 +286,7 @@ public class TileView : View //// BUGBUG: Why is this not handled by a key binding??? /// - protected override bool OnProcessKeyDown (Key keyEvent) + protected override bool OnKeyDownNotHandled (Key keyEvent) { var focusMoved = false; diff --git a/Terminal.Gui/Views/TimeField.cs b/Terminal.Gui/Views/TimeField.cs index 305a3ce59..687a8cd71 100644 --- a/Terminal.Gui/Views/TimeField.cs +++ b/Terminal.Gui/Views/TimeField.cs @@ -177,7 +177,7 @@ public class TimeField : TextField } /// - 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) diff --git a/Terminal.Gui/Views/Wizard/Wizard.cs b/Terminal.Gui/Views/Wizard/Wizard.cs index 338328b02..b9bc49bd5 100644 --- a/Terminal.Gui/Views/Wizard/Wizard.cs +++ b/Terminal.Gui/Views/Wizard/Wizard.cs @@ -381,12 +381,12 @@ public class Wizard : Dialog /// /// is derived from and Dialog causes Esc to call /// , closing the Dialog. Wizard overrides - /// to instead fire the event when Wizard is being used as a + /// to instead fire the event when Wizard is being used as a /// non-modal (see ). /// /// /// - protected override bool OnProcessKeyDown (Key key) + protected override bool OnKeyDownNotHandled (Key key) { //// BUGBUG: Why is this not handled by a key binding??? if (!Modal) diff --git a/UnitTests/View/Keyboard/KeyboardEventTests.cs b/UnitTests/View/Keyboard/KeyboardEventTests.cs index 471016231..6b484ec58 100644 --- a/UnitTests/View/Keyboard/KeyboardEventTests.cs +++ b/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; diff --git a/UnitTests/View/ViewTests.cs b/UnitTests/View/ViewTests.cs index 54b9b31b5..1dc072e3a 100644 --- a/UnitTests/View/ViewTests.cs +++ b/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;