diff --git a/Terminal.Gui/View/View.Keyboard.cs b/Terminal.Gui/View/View.Keyboard.cs index 317079358..c3ccd8ca9 100644 --- a/Terminal.Gui/View/View.Keyboard.cs +++ b/Terminal.Gui/View/View.Keyboard.cs @@ -243,7 +243,8 @@ public partial class View // Keyboard APIs #region Key Down Event /// - /// If the view is enabled, processes a new key down event and returns if the event was + /// If the view is enabled, raises the related key down events on the view, and returns if the + /// event was /// handled. /// /// @@ -252,10 +253,19 @@ public partial class View // Keyboard APIs /// first. /// /// - /// If the focused sub view does not handle the key press, this method calls to allow the - /// view to pre-process the key press. If returns , this method then - /// calls to invoke any key bindings. Then, only if no key bindings are - /// handled, will be called allowing the view to process the key press. + /// If the focused sub view 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 + /// process the key press. + /// + /// + /// Callling this method for a key bound to the view via an Application-scoped keybinding will have no effect. + /// Instead, + /// use . /// /// See for an overview of Terminal.Gui keyboard APIs. /// @@ -287,7 +297,8 @@ public partial class View // Keyboard APIs return true; } - if (RaiseProcessKeyDown(key) || key.Handled) + // After + if (RaiseProcessKeyDown (key) || key.Handled) { return true; } @@ -344,11 +355,11 @@ public partial class View // Keyboard APIs } } - - /// - /// Low-level API called when the user presses a key, allowing a view to pre-process the key down event. This is - /// called from before . + /// Called 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 by other views. /// /// Contains the details about the key that produced the event. /// @@ -362,14 +373,11 @@ public partial class View // Keyboard APIs /// /// Fires the event. /// - protected virtual bool OnKeyDown (Key keyEvent) - { - return false; - } + protected virtual bool OnKeyDown (Key keyEvent) { return false; } /// - /// Invoked when the user presses a key, allowing subscribers to pre-process the key down event. This is fired - /// from before . Set to true to + /// 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. /// /// @@ -382,47 +390,39 @@ public partial class View // Keyboard APIs public event EventHandler? KeyDown; /// - /// Low-level API called when the user presses a key, allowing views do things during key down events. This is - /// called from after . + /// Called when the user presses a key, allowing views do things during key down events. This is + /// called after the after are raised. /// - /// Contains the details about 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. - /// /// /// - /// Override to override the behavior of how the base class processes key down - /// events. - /// - /// /// For processing s and commands, use and /// instead. /// - /// Fires the event. /// /// Not all terminals support distinct key up notifications; applications should avoid depending on distinct /// KeyUp events. /// /// - protected virtual bool OnProcessKeyDown (Key keyEvent) - { - return keyEvent.Handled; - } + /// Contains the details about 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. + /// + protected virtual bool OnProcessKeyDown (Key keyEvent) { return keyEvent.Handled; } /// - /// Invoked when the user presses a key, allowing subscribers to do things during key down events. Set + /// 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 before . + /// and . /// /// /// - /// SubViews can use the of their super view override the default behavior of when - /// key bindings are invoked. + /// For processing s and commands, use and + /// instead. /// /// - /// Not all terminals support distinct key up notifications; applications should avoid depending on distinct - /// KeyUp events. + /// 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. /// @@ -433,8 +433,9 @@ public partial class View // Keyboard APIs #region KeyUp Event /// - /// If the view is enabled, processes a new key up event and returns if the event was - /// handled. Called before . + /// If the view is enabled, raises the related key up events on the view, and returns if the + /// event was + /// handled. /// /// /// @@ -446,8 +447,9 @@ public partial class View // Keyboard APIs /// first. /// /// - /// If the focused sub view does not handle the key press, this method calls , which is - /// cancellable. + /// If the focused sub view does not handle the key press, this method raises / + /// to allow the + /// view to pre-process the key press. If /. /// /// See for an overview of Terminal.Gui keyboard APIs. /// @@ -460,11 +462,16 @@ public partial class View // Keyboard APIs return false; } + // Before if (RaiseKeyUp (key) || key.Handled) { return true; } + // During + + // After + return false; bool RaiseKeyUp (Key key) @@ -482,7 +489,6 @@ public partial class View // Keyboard APIs } } - /// Method invoked when a key is released. This method is called from . /// Contains the details about the key that produced the event. /// @@ -498,10 +504,7 @@ public partial class View // Keyboard APIs /// /// See for an overview of Terminal.Gui keyboard APIs. /// - public virtual bool OnKeyUp (Key keyEvent) - { - return false; - } + public virtual bool OnKeyUp (Key keyEvent) { return false; } /// /// Invoked when a key is released. Set to true to stop the key up event from being processed @@ -537,7 +540,8 @@ public partial class View // Keyboard APIs /// The scope. /// /// if no event was raised; input proessing should continue. - /// if the event was raised and was not handled (or cancelled); input proessing should continue. + /// if the event was raised and was not handled (or cancelled); input proessing should + /// continue. /// if the event was raised and handled (or cancelled); input proessing should stop. /// public virtual bool? OnInvokingKeyBindings (Key keyEvent, KeyBindingScope scope) @@ -715,7 +719,8 @@ public partial class View // Keyboard APIs /// The scope. /// /// if no command was invoked; input proessing should continue. - /// if at least one command was invoked and was not handled (or cancelled); input proessing should continue. + /// if at least one command was invoked and was not handled (or cancelled); input proessing + /// should continue. /// if at least one command was invoked and handled (or cancelled); input proessing should stop. /// protected bool? InvokeKeyBindings (Key key, KeyBindingScope scope)