Fixes #2926 - Refactor KeyEvent and KeyEventEventArgs to simplify

[tig]

Fixes #2926 - Refactor KeyEvent and KeyEventEventArgs to simplify
Fixes #2978 - Simplify Key - BackTab and upper-case alphas
Fixes #3038 - 'View.HotKey' automatic setting supports only char.IsLetterOrDigit
Fixes #3042 - Enable Views to declare key bindings for their SuperView
Fixes #2826 - v2 lowercase letters must be removed from the Key enum.

• Rearrange Event.cs to Keyboard.cs and Mouse.cs.
• Rename KeyEventEventArgs to KeyEventArgs
• Merge KeyEvent members into KeyEventArgs, delete KeyEvent
• Rename ProcessKey etc...
• Fix broken things
• Add View.ProcessKeyPressed (non-virtual) and move virtual OnKeyPressed from Responder.
• Remove Shortcut from View as shortcuts are only relevant for Menu
• Hack Menu and StatusBar to work properly
• Fully remove OnHot/ColdKey
• Update API docs
• Remove Key.BackTab; it's only relevant w/in CursesDriver and confuses the App API
• Figure out if the whole OnHot/ColdKey thing can be nuked
• Get rid of KeyEventArgs._keyModifiers and replace IsAlt etc .. with test for mask. - Overly complicates system given benefit (enabled tracking of Caps, scroll, and num lock on WindowsDriver only.
  • Remove IsCapsLock, IsNumLock, and IsScrollLock
  • Remove KeyModifiers class and and change KeyEventArgs to test for the masks in the IsAlt etc... properties.
• Remove Key.a-z
• Fix NetDriver
• Fix CursesDriver
• Finish Fixes Enable Views to declare key bindings for their SuperView #3042 - Enable Views to declare key bindings for their SuperView
• Ensure all library code uses consistent naming/usage
• Ensure all Scenario code uses best practices related to new design.
• Re-re-edit keyboard.md and API docs

Pull Request checklist:

• I've named my PR in the form of "Fixes #issue. Terse description."
• My code follows the style guidelines of Terminal.Gui - if you use Visual Studio, hit CTRL-K-D to automatically reformat your files before committing.
• My code follows the Terminal.Gui library design guidelines
• I ran dotnet test before commit
• I have made corresponding changes to the API documentation (using /// style comments)
• My changes generate no new warnings
• I have checked my code and corrected any poor grammar or misspellings
• I conducted basic QA to assure all features are working

[BDisp]

I propose to remove the KeyCode.Unknown which aren't used by the drivers now, since they return KeyCode.Null if KeyChar is '\0'. Thus avoids using the prior to check if a key is valid or not and only compare if it's KeyCode.Null.

[BDisp]

It's needed many information about Alt, Ctrl and Shift?

[tig]

Should methods that invoke events should be protected virtual instead of public virtual? See here https://stackoverflow.com/questions/54914477/why-the-method-that-fires-the-c-sharp-event-must-be-protected-virtual.

I actually went to bed thinking that last night.

[tig]

Based on this, I moved running the test to windows-latest instead of ubuntu-latest. Tests now pass.
microsoft/vstest#2952
Sheesh.

My opinion is that when that vstest issue is fixed then change it again to ubuntu-latest again because normally Windows users forgot to test in WSL first to detect conflicts before pushing them. Don't you think?

I agree. FWIW, the tests DO sometimes fail for me now under WSL:

So, this might just be a bad test on our part.

[tig]

I propose to remove the KeyCode.Unknown which aren't used by the drivers now, since they return KeyCode.Null if KeyChar is '\0'. Thus avoids using the prior to check if a key is valid or not and only compare if it's KeyCode.Null.

I agree.

[BDisp]

So, this might just be a bad test on our part.

It may have to do with .Net 8.0. Sometimes I see tests that aren't runs, flagged as not run without any information on what going on. This is really a bug after the latest VS2022 update.

[tig]

It's needed many information about Alt, Ctrl and Shift?

I think the API docs for each of those makes it clear what they all do. They are all different, and not all are checks.

The idea is Key is a high-level class with helper functions for common things that are either tricky to remember to do correctly, or cause ugly code.

The Is properties (e.g. IsShift) test for shift state.

The With properties (e.g. WithShift) return a copy of the Key with the shift modifier applied.

The No properties (e.g. NoShift) return a copy of the Key with the shift modifier removed.

I considered making the No properties be Remove properties (e.g. RemoveShift), but I liked the shortness of No better. Happy to debate this though.

The BareKey is a helper that is not actually used, so I'll remove it.

[tig]

I propose to remove the KeyCode.Unknown which aren't used by the drivers now, since they return KeyCode.Null if KeyChar is '\0'. Thus avoids using the prior to check if a key is valid or not and only compare if it's KeyCode.Null.

I agree.

Note that Key already doesn't have Unknown.

[BDisp]

It seems that is a Xunit bug.

[tig]

Here's a snapshot of the lastest API docs:

[tig]

I'm about to merge this. I have to stop working on it or my personal life is going to hell.

I know this is going to cause hell for the other outstanding PRs.... Sorry.

[BDisp]

One question. When the user do With.Shift, With.Ctrl and With.Alt what's KeyCode is used on the Key class?

[BDisp]

I propose to remove the KeyCode.Unknown which aren't used by the drivers now, since they return KeyCode.Null if KeyChar is '\0'. Thus avoids using the prior to check if a key is valid or not and only compare if it's KeyCode.Null.

I agree.

Note that Key already doesn't have Unknown.

I think it should also been removed from the KeyCode enum.

[tig]

This is merged.

FWIW, see the new API docs: https://gui-cs.github.io/Terminal.GuiV2Docs/docs/keyboard.html