Fixes #1588 - Documentation for keybinding (#1595)

README.md

@@ -69,6 +69,20 @@ To enter the key `ESC`, you can either press `ESC` and wait 100 milliseconds, or
 
 `CTRL-Q` is used for exiting views (and apps).
 
+**Terminal.Gui** supports rebinding keys.  For example the default key for activating a button is Enter.  You can change this using the `ClearKeybinding` and `AddKeybinding` methods:
+
+```csharp
+var btn = new Button ("Press Me");
+btn.ClearKeybinding (Command.Accept);
+btn.AddKeyBinding (Key.b, Command.Accept);
+```
+
+The `Command` enum lists generic operations that are implemented by views.  For example `Command.Accept` in a Button results in the `Clicked` event firing while in `TableView` it is bound to `CellActivated`.  Not all commands are implemented by all views (e.g. you cannot scroll in a Button).  To see which commands are implemented by a View you can use the `GetSupportedCommands()` method.
+
+Not all controls have the same key bound for a given command, for example `Command.Accept` defaults to `Key.Enter` in a `Button` but defaults to `Key.Space` in `RadioGroup`.
+
+Keybindings only operate while a view has focus.  To register global hotkeys you can override a view's `bool ProcessHotKey (KeyEvent kb)` method.
+
 ### Driver model
 
 **Terminal.Gui** has support for [ncurses](https://github.com/migueldeicaza/gui.cs/blob/master/Terminal.Gui/ConsoleDrivers/CursesDriver/CursesDriver.cs), [`System.Console`](https://github.com/migueldeicaza/gui.cs/blob/master/Terminal.Gui/ConsoleDrivers/NetDriver.cs), and a full [Win32 Console](https://github.com/migueldeicaza/gui.cs/blob/master/Terminal.Gui/ConsoleDrivers/WindowsDriver.cs) front-end.

UnitTests/ButtonTests.cs

@@ -99,5 +99,43 @@ namespace Terminal.Gui.Views {
 			Assert.True (btn.ProcessHotKey (new KeyEvent (Key.E | Key.AltMask, new KeyModifiers () { Alt = true })));
 			Assert.True (clicked);
 		}
+
+
+		/// <summary>
+		/// This test demonstrates how to change the activation key for Button
+		/// as described in the README.md keyboard handling section
+		/// </summary>
+		[Fact]
+		[AutoInitShutdown]
+		public void KeyBindingExample ()
+		{
+			int pressed = 0;
+			var btn = new Button ("Press Me");
+			btn.Clicked += () => pressed++;
+
+			// The Button class supports the Accept command
+			Assert.Contains(Command.Accept,btn.GetSupportedCommands ());
+
+			Application.Top.Add (btn);
+			Application.Begin (Application.Top);
+
+			// default keybinding is Enter which results in keypress
+			Application.Driver.SendKeys ('\n',ConsoleKey.Enter,false,false,false);
+			Assert.Equal (1, pressed);
+
+			// remove the default keybinding (Enter)
+			btn.ClearKeybinding (Command.Accept);
+			
+			// After clearing the default keystroke the Enter button no longer does anything for the Button
+			Application.Driver.SendKeys ('\n', ConsoleKey.Enter, false, false, false);
+			Assert.Equal (1, pressed);
+
+			// Set a new binding of b for the click (Accept) event
+			btn.AddKeyBinding (Key.b, Command.Accept);
+
+			// now pressing B should call the button click event
+			Application.Driver.SendKeys ('b', ConsoleKey.B, false, false, false);
+			Assert.Equal (2, pressed);
+		}
 	}
 }