Add section on physical keyswitch events

Signed-off-by: Michael Richters <gedankenexperimenter@gmail.com>

docs/customization/plugin-authors-guide.md

@@ -401,10 +401,58 @@ The simplest mechanism used by many plugins that mark their generated events "in
 
 There are other techniques to avoid inifinite loops, employed by plugins whose injected events should be processed by other plugins, but since most of those will be using the `onKeyswitchEvent()` handler instead of `onKeyEvent()`, we'll cover that later in this guide.
 
+## Physical keyswitch events
+
+Most plugins that respond to key events can do their work using the `onKeyEvent()` handler, but in some cases, it's necessary to use the `onKeyswitchEvent()` handler instead.  These event handlers are strictly intended for physical keyswitch events, and plugins that implement the `onKeyswitchEvent()` handler must abide by certain rules in order to work well with each other.  As a result, such a plugin is a bit more complex, but there are helper mechanisms to make things easier:
+
+```c++
+#include "kaleidoscope/KeyEventTracker.h"
+
+namespace kaleidoscope {
+namespace plugin {
+
+class MyKeyswitchPlugin : public Plugin {
+ public:
+  EventHandlerResult onKeyswitchEvent(KeyEvent &event) {
+    if (event_tracker_.shouldIgnore(event))
+      return EventHandlerResult::OK;
+    // Plugin logic goes here...
+    return EventHandlerResult::OK;
+  }
+ private:
+  KeyEventTracker event_tracker_;
+};
+
+} // namespace kaleidoscope
+} // namespace plugin
+
+kaleidoscope::plugin::MyKeyswitchPlugin;
+```
+
+We've just added a `KeyEventTracker` object to our plugin, and made the first line of its `onKeyswitchEvent()` handler call that event tracker's `shouldIgnore()` method, returning `OK` if it returns `true` (thereby ignoring the event).  Every plugin that implements `onKeyswitchEvent()` should follow this template to avoid plugin interaction bugs, including possible infinite loops.
+
+The main reason for this event tracker mechanism is that plugins with `onKeyswitchEvent()` handlers often delay events because some aspect of those events (usually `event.key`) needs to be determined by subsequent events or timeouts.  To do this, event information is stored, and the event is later regenerated by the plugin, which calls `Runtime.handleKeyswitchEvent()` so that the other `onKeyswitchEvent()` handlers can process it.
+
+We need to prevent infinite loops, but simply marking the regenerated event `INJECTED` is no good, because it would prevent the other plugins from acting on it, so we instead keep track of a monotonically increasing event id number and use the `KeyEventTracker` helper class to ignore events that our plugin has already recieved, so that when the plugin regenerates an event with the same event id, it (and all the plugins before it) can ignore that event, but the subsequent plugins, which haven't seen that event yet, will recongize it as new and process the event accordingly.
+
+### Regenerating stored events
+
+When a plugin that implements `onKeyswitchEvent()` regenerates a stored event later so that it can be processed by the next plugin in the chain, it must use the correct event id value (the same one used by the original event).  This is an object of type `EventId`, and is retrieved by calling `event.id()` (unlike the other properties of a `KeyEvent` object the event id is not directly accessible).
+
+```c++
+KeyEventId stored_id = event.id();
+```
+
+When reconstructing an event to allow it to proceed, we then use the four-argument version of the `KeyEvent` constructor:
+
+```c++
+KeyEvent event = KeyEvent(addr, state, key, stored_id);
+```
+
+In the above, `addr` and `state` are usually also the same as the original event's values, and `key` is most often the thing that changes.  If your plugin wants a keymap lookup to take place, the value `Key_Undefined` can be used instead of explicitly doing the lookup itself.
+
 ## Controlling LEDs
 
 ## HID reports
 
-## Physical keyswitch events
-
 ## Layer changes