Merge pull request #183 from cdisselkoen/for-upstream

Improved documentation and clarity for keyswitch states

src/keyswitch_state.h

@@ -7,15 +7,38 @@
 #define IS_PRESSED  B00000010
 #define WAS_PRESSED B00000001
 
-#define keyWasPressed(keyState) ((keyState) & WAS_PRESSED)
+/* keyIsPressed(): This is true if the key is pressed during this scan cycle.
+ * This will be true for several consecutive cycles even for a single tap of
+ *   the key.
+ * Use this for events which should fire every scan cycle the key is held.
+ * If you want an event which fires only once when a key is pressed, use
+ *   keyToggledOn() or keyToggledOff() (defined below).
+ */
 #define keyIsPressed(keyState)  ((keyState) & IS_PRESSED)
+
+/* keyWasPressed(): This is true if the key was pressed during the previous
+     scan cycle, regardless of whether it is pressed or not in this scan cycle.
+ */
+#define keyWasPressed(keyState) ((keyState) & WAS_PRESSED)
+
+/* keyToggledOn(): This is true if the key is newly pressed during this scan
+ *   cycle, i.e. was not pressed in the previous scan cycle but is now.
+ * Use this for events which should fire exactly once per keypress, on a
+ *   "key-down" event.
+ */
 #define keyToggledOn(keyState)  (keyIsPressed(keyState) && ! keyWasPressed(keyState))
+
+/* keyToggledOff(): This is true if the key is newly not-pressed during this
+ *   scan cycle, i.e. is not pressed now but was in the previous scan cycle.
+ * Use this for events which should fire exactly once per keypress, on a
+ *   "key-down" event.
+ */
 #define keyToggledOff(keyState) (keyWasPressed(keyState) && ! keyIsPressed(keyState))
 
 
 // Deprecated - Remove once the core has transitioned
 
-#define key_was_pressed(keyState) ((keyState) & WAS_PRESSED)
-#define key_is_pressed(keyState)  ((keyState) & IS_PRESSED)
-#define key_toggled_on(keyState)  (key_is_pressed(keyState) && ! key_was_pressed(keyState))
-#define key_toggled_off(keyState) (key_was_pressed(keyState) && ! key_is_pressed(keyState))
+#define key_was_pressed(keyState) keyWasPressed(keyState)
+#define key_is_pressed(keyState)  keyIsPressed(keyState)
+#define key_toggled_on(keyState)  keyToggledOn(keyState)
+#define key_toggled_off(keyState) keyToggledOff(keyState)