From 128d26391630faa9f8dd66712583892162612f0d Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Tue, 15 Nov 2016 17:39:20 +0100 Subject: [PATCH] Add a bit of docs to key_events.h Briefly document the key event handling flow, to make it clearer how the functions can be used. Signed-off-by: Gergely Nagy --- src/key_events.h | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/src/key_events.h b/src/key_events.h index 3b71e073..55b3945c 100644 --- a/src/key_events.h +++ b/src/key_events.h @@ -15,8 +15,36 @@ extern uint8_t temporary_keymap; extern const Key keymaps[][ROWS][COLS]; // sending events to the computer -void handle_synthetic_key_event( Key mappedKey, uint8_t currentState, uint8_t previousState); +/* The event handling starts with the Scanner calling handle_key_event() for + * every key in the matrix, and it is the task of this method to figure out what + * to do, it is the main entry point. + * + * This function will iterate through an array of handler functions, and stop as + * soon as one of them signals that the event has been handled. To make it + * possible to inject synthetic events, one can call handle_key_event from + * within a custom handler (making the event handling recursive), with a + * different keycode. + * + * This is useful for example for one-shot modifiers, where we would like to + * temporarily disable the one-shot functionality, and have them work as a + * normal modifier instead. In this case, the keymap would contain a key with + * OSM flags set, and the event handler would remove the OSM flags, and let the + * system handle the key as it would have, without the OSM flags. So we simply + * clear the flags, and call handle_key_event again, with the modifier keycode + * as the first argument. This way, we could insert an event, and have the whole + * chain re-process it, instead of registering the keycode ourselves with HID + * ourselves. Injecting allows any and all custom handlers to have a chance, + * too. + * + * For this reason, the handle_key_event receives four arguments: the mapped key + * (or Key_NoKey if we do not want to override what is in the keymap), the row + * and column of the key, so we can look up the code for it, and the current and + * previous state of the key, so we can determine what the event is. + */ void handle_key_event(Key mappedKey, byte row, byte col, uint8_t currentState, uint8_t previousState); + +// Internal use +void handle_synthetic_key_event( Key mappedKey, uint8_t currentState, uint8_t previousState); void press_key(Key mappedKey); void handle_keymap_key_event(Key keymapEntry, uint8_t currentState, uint8_t previousState); void handle_mouse_key_event(Key mappedKey, uint8_t currentState, uint8_t previousState);