Fixed broken link to key event constants

lua-api-reference/constants/README.md

@@ -3,8 +3,7 @@ description: This section describes various constants that are provided for Lua
 ---
 
 # Constants
-
-* [Key Events](broken-reference)
+* [Key Events](key-event-constants.md)
 * [Touch Events](touch-event-constants.md)
 * [Flags and Patterns](flags-and-pattern-constants.md)
 * [Colors](color-constants.md)

lua-api-reference/constants/key-event-constants.md

@@ -1,2 +1,82 @@
+---
+description: >-
+  This page describes the value that is passed to scripts in the event
+  parameter. It is used in Telemetry and One-Time scripts, as well as widget
+  scripts in full screen mode.
+---
+
 # Key Event Constants
 
+## The key event mechanism
+
+Each time a key is pressed, held and released a number of events get generated. Here is a typical flow:
+
+* when a key is pressed a `FIRST` event is generated
+* if the key continues to be pressed, then after a while a `LONG` event is generated
+* if the key continues to be pressed, then a `REPEAT` events are being generated
+* when the key is released a `BREAK` event is generated
+
+Couple of examples:
+
+* a short press on key would generate: `FIRST`, `BREAK`
+* a longer pres on key would generate: `FIRST`, `LONG`, `BREAK`
+* even longer press: `FIRST`, `LONG`, `REPEAT,`REPEAT, ..., `BREAK`
+
+This normal key event sequence can be altered with the [killEvents(key)](../general-functions-less-than-greater-than-luadoc-begin-general/killevents.md) function. Any time this function is called (after the `FIRST` event) all further key events for this key will be suppressed until the next key press of this key. Examples:
+
+* kill immediately after the key press would generate: `FIRST`
+* kill after the long key press would generate: `FIRST`, `LONG`
+
+## Constants
+
+The `event` parameter in the [Telemetry](../../part\_i\_-\_script\_type\_overview/telemetry.md) and [One-Time](https://github.com/opentx/opentx-2-3-lua-reference-guide/tree/0d355d19f1961b689994cf78b84005864d33f9b5/one-time\_scripts.md) scripts run function actually carries two pieces of information:
+
+* key number
+* type of event
+
+The two fields are combined into one single number. Some of these combinations are defined as constants and are available to Lua scripts:
+
+|   Key Event Name  |         Comments        |
+| :---------------: | :---------------------: |
+|  EVT\_MENU\_BREAK |   **MENU** key release  |
+|  EVT\_PAGE\_BREAK |   **PAGE** key release  |
+|  EVT\_PAGE\_LONG  | **MENU** key long press |
+| EVT\_ENTER\_BREAK |   **ENT** key release   |
+|  EVT\_ENTER\_LONG |  **ENT** key long press |
+|  EVT\_EXIT\_BREAK |   **EXIT** key release  |
+|  EVT\_PLUS\_BREAK |    **+** key release    |
+| EVT\_MINUS\_BREAK |    **-** key release    |
+|  EVT\_PLUS\_FIRST |     **+** key press     |
+| EVT\_MINUS\_FIRST |     **-** key press     |
+|  EVT\_PLUS\_REPT  |     **+** key repeat    |
+|  EVT\_MINUS\_REPT |     **-** key repeat    |
+
+Radios with rotary encoder (X7 and Horus) have also:
+
+|  Key Event Name |           Comments           |
+| :-------------: | :--------------------------: |
+| EVT\_ROT\_BREAK |    rotary encoder release    |
+|  EVT\_ROT\_LONG |   rotary encoder long press  |
+|  EVT\_ROT\_LEFT |  rotary encoder rotated left |
+| EVT\_ROT\_RIGHT | rotary encoder rotated right |
+
+## Virtual events
+
+Given the large number of radios supported by OpenTX, and the large difference in keys available on those, a set of VIRTUAL KEYS has been defined and are mapped to best fit available hardware
+
+|   Virtual Key Event Name  |        Comments       |
+| :-----------------------: | :-------------------: |
+|  EVT\_VIRTUAL\_NEXT\_PAGE |  for PAGE navigation  |
+|  EVT\_VIRTUAL\_PREV\_PAGE |  for PAGE navigation  |
+|    EVT\_VIRTUAL\_ENTER    |                       |
+| EVT\_VIRTUAL\_ENTER\_LONG |                       |
+|     EVT\_VIRTUAL\_MENU    |                       |
+|  EVT\_VIRTUAL\_MENU\_LONG |                       |
+|     EVT\_VIRTUAL\_NEXT    | for FIELDS navigation |
+|  EVT\_VIRTUAL\_NEXT\_REPT | for FIELDS navigation |
+|     EVT\_VIRTUAL\_PREV    | for FIELDS navigation |
+|  EVT\_VIRTUAL\_PREV\_REPT | for FIELDS navigation |
+|     EVT\_VIRTUAL\_INC     | for VALUES navigation |
+|  EVT\_VIRTUAL\_INC\_REPT  | for VALUES navigation |
+|     EVT\_VIRTUAL\_DEC     | for VALUES navigation |
+|  EVT\_VIRTUAL\_DEC\_REPT  | for VALUES navigation |