qmk

Unnamed repository; edit this file 'description' to name the repository.
git clone git://git.z3bra.org/qmk.git
Log | Files | Refs | Submodules | LICENSE

commit 5fcca9a226b2ab0b1335396e25c37e4b2a261a06
parent f97894d8dba1d20693e71289d284a03335507bd2
Author: Drashna Jaelre <drashna@live.com>
Date:   Thu, 17 Jan 2019 09:04:35 -0800

Add documentation and fix formating (#4860)


Diffstat:
tmk_core/common/action_layer.c | 301++++++++++++++++++++++++++++++++++++++-----------------------------------------
1 file changed, 145 insertions(+), 156 deletions(-)

diff --git a/tmk_core/common/action_layer.c b/tmk_core/common/action_layer.c @@ -17,82 +17,76 @@ uint32_t default_layer_state = 0; /** \brief Default Layer State Set At user Level * - * FIXME: Needs docs + * Run user code on default layer state change */ __attribute__((weak)) uint32_t default_layer_state_set_user(uint32_t state) { - return state; + return state; } /** \brief Default Layer State Set At Keyboard Level * - * FIXME: Needs docs + * Run keyboard code on default layer state change */ __attribute__((weak)) uint32_t default_layer_state_set_kb(uint32_t state) { - return default_layer_state_set_user(state); + return default_layer_state_set_user(state); } /** \brief Default Layer State Set * - * FIXME: Needs docs + * Static function to set the default layer state, prints debug info and clears keys */ -static void default_layer_state_set(uint32_t state) -{ - state = default_layer_state_set_kb(state); - debug("default_layer_state: "); - default_layer_debug(); debug(" to "); - default_layer_state = state; - default_layer_debug(); debug("\n"); +static void default_layer_state_set(uint32_t state) { + state = default_layer_state_set_kb(state); + debug("default_layer_state: "); + default_layer_debug(); debug(" to "); + default_layer_state = state; + default_layer_debug(); debug("\n"); #ifdef STRICT_LAYER_RELEASE - clear_keyboard_but_mods(); // To avoid stuck keys + clear_keyboard_but_mods(); // To avoid stuck keys #else - clear_keyboard_but_mods_and_keys(); // Don't reset held keys + clear_keyboard_but_mods_and_keys(); // Don't reset held keys #endif } /** \brief Default Layer Print * - * FIXME: Needs docs + * Print out the hex value of the 32-bit default layer state, as well as the value of the highest bit. */ -void default_layer_debug(void) -{ - dprintf("%08lX(%u)", default_layer_state, biton32(default_layer_state)); +void default_layer_debug(void) { + dprintf("%08lX(%u)", default_layer_state, biton32(default_layer_state)); } /** \brief Default Layer Set * - * FIXME: Needs docs + * Sets the default layer state. */ -void default_layer_set(uint32_t state) -{ - default_layer_state_set(state); +void default_layer_set(uint32_t state) { + default_layer_state_set(state); } #ifndef NO_ACTION_LAYER /** \brief Default Layer Or * - * FIXME: Needs docs + * Turns on the default layer based on matching bits between specifed layer and existing layer state */ -void default_layer_or(uint32_t state) -{ - default_layer_state_set(default_layer_state | state); +void default_layer_or(uint32_t state) { + default_layer_state_set(default_layer_state | state); } /** \brief Default Layer And * - * FIXME: Needs docs + * Turns on default layer based on matching enabled bits between specifed layer and existing layer state */ -void default_layer_and(uint32_t state) -{ - default_layer_state_set(default_layer_state & state); +void default_layer_and(uint32_t state) { + default_layer_state_set(default_layer_state & state); } /** \brief Default Layer Xor * - * FIXME: Needs docs + * Turns on default layer based on non-matching bits between specifed layer and existing layer state */ -void default_layer_xor(uint32_t state) -{ - default_layer_state_set(default_layer_state ^ state); +void default_layer_xor(uint32_t state) { + default_layer_state_set(default_layer_state ^ state); } #endif @@ -104,170 +98,168 @@ uint32_t layer_state = 0; /** \brief Layer state set user * - * FIXME: Needs docs + * Runs user code on layer state change */ __attribute__((weak)) uint32_t layer_state_set_user(uint32_t state) { - return state; + return state; } /** \brief Layer state set keyboard * - * FIXME: Needs docs + * Runs keyboard code on layer state change */ __attribute__((weak)) uint32_t layer_state_set_kb(uint32_t state) { - return layer_state_set_user(state); + return layer_state_set_user(state); } /** \brief Layer state set * - * FIXME: Needs docs + * Sets the layer to match the specifed state (a bitmask) */ -void layer_state_set(uint32_t state) -{ - state = layer_state_set_kb(state); - dprint("layer_state: "); - layer_debug(); dprint(" to "); - layer_state = state; - layer_debug(); dprintln(); +void layer_state_set(uint32_t state) { + state = layer_state_set_kb(state); + dprint("layer_state: "); + layer_debug(); dprint(" to "); + layer_state = state; + layer_debug(); dprintln(); #ifdef STRICT_LAYER_RELEASE - clear_keyboard_but_mods(); // To avoid stuck keys + clear_keyboard_but_mods(); // To avoid stuck keys #else - clear_keyboard_but_mods_and_keys(); // Don't reset held keys + clear_keyboard_but_mods_and_keys(); // Don't reset held keys #endif } /** \brief Layer clear * - * Turn off all layers. + * Turn off all layers */ -void layer_clear(void) -{ - layer_state_set(0); +void layer_clear(void) { + layer_state_set(0); } /** \brief Layer state is * - * Return whether the given state is on (it might still be shadowed by a higher state, though). + * Return whether the given state is on (it might still be shadowed by a higher state, though) */ -bool layer_state_is(uint8_t layer) -{ - return layer_state_cmp(layer_state, layer); +bool layer_state_is(uint8_t layer) { + return layer_state_cmp(layer_state, layer); } /** \brief Layer state compare * - * FIXME: Needs docs + * Used for comparing layers {mostly used for unit testing} */ bool layer_state_cmp(uint32_t cmp_layer_state, uint8_t layer) { - if (!cmp_layer_state) { return layer == 0; } - return (cmp_layer_state & (1UL<<layer)) != 0; + if (!cmp_layer_state) { return layer == 0; } + return (cmp_layer_state & (1UL<<layer)) != 0; } /** \brief Layer move * - * Turn on the given layer and turn off all other layers. + * Turns on the given layer and turn off all other layers */ -void layer_move(uint8_t layer) -{ - layer_state_set(1UL<<layer); +void layer_move(uint8_t layer) { + layer_state_set(1UL<<layer); } /** \brief Layer on * - * Turn on the given layer. + * Turns on given layer */ -void layer_on(uint8_t layer) -{ - layer_state_set(layer_state | (1UL<<layer)); +void layer_on(uint8_t layer) { + layer_state_set(layer_state | (1UL<<layer)); } /** \brief Layer off * - * FIXME: Needs docs + * Turns off given layer */ -void layer_off(uint8_t layer) -{ - layer_state_set(layer_state & ~(1UL<<layer)); +void layer_off(uint8_t layer) { + layer_state_set(layer_state & ~(1UL<<layer)); } /** \brief Layer invert * - * Toggle the given layer (set it if it's unset, or unset it if it's set). + * Toggle the given layer (set it if it's unset, or unset it if it's set) */ -void layer_invert(uint8_t layer) -{ - layer_state_set(layer_state ^ (1UL<<layer)); +void layer_invert(uint8_t layer) { + layer_state_set(layer_state ^ (1UL<<layer)); } /** \brief Layer or * - * FIXME: Needs docs + * Turns on layers based on matching bits between specifed layer and existing layer state */ -void layer_or(uint32_t state) -{ - layer_state_set(layer_state | state); +void layer_or(uint32_t state) { + layer_state_set(layer_state | state); } /** \brief Layer and * - * FIXME: Needs docs + * Turns on layers based on matching enabled bits between specifed layer and existing layer state */ -void layer_and(uint32_t state) -{ - layer_state_set(layer_state & state); +void layer_and(uint32_t state) { + layer_state_set(layer_state & state); } /** \brief Layer xor * - * FIXME: Needs docs + * Turns on layers based on non-matching bits between specifed layer and existing layer state */ -void layer_xor(uint32_t state) -{ - layer_state_set(layer_state ^ state); +void layer_xor(uint32_t state) { + layer_state_set(layer_state ^ state); } /** \brief Layer debug printing * * Print out the hex value of the 32-bit layer state, as well as the value of the highest bit. */ -void layer_debug(void) -{ - dprintf("%08lX(%u)", layer_state, biton32(layer_state)); +void layer_debug(void) { + dprintf("%08lX(%u)", layer_state, biton32(layer_state)); } #endif #if !defined(NO_ACTION_LAYER) && !defined(STRICT_LAYER_RELEASE) +/** \brief source layer cache + */ + uint8_t source_layers_cache[(MATRIX_ROWS * MATRIX_COLS + 7) / 8][MAX_LAYER_BITS] = {{0}}; -void update_source_layers_cache(keypos_t key, uint8_t layer) -{ - const uint8_t key_number = key.col + (key.row * MATRIX_COLS); - const uint8_t storage_row = key_number / 8; - const uint8_t storage_bit = key_number % 8; - - for (uint8_t bit_number = 0; bit_number < MAX_LAYER_BITS; bit_number++) { - source_layers_cache[storage_row][bit_number] ^= - (-((layer & (1U << bit_number)) != 0) - ^ source_layers_cache[storage_row][bit_number]) - & (1U << storage_bit); - } +/** \brief update source layers cache + * + * Updates the cached keys when changing layers + */ +void update_source_layers_cache(keypos_t key, uint8_t layer) { + const uint8_t key_number = key.col + (key.row * MATRIX_COLS); + const uint8_t storage_row = key_number / 8; + const uint8_t storage_bit = key_number % 8; + + for (uint8_t bit_number = 0; bit_number < MAX_LAYER_BITS; bit_number++) { + source_layers_cache[storage_row][bit_number] ^= + (-((layer & (1U << bit_number)) != 0) + ^ source_layers_cache[storage_row][bit_number]) + & (1U << storage_bit); + } } -uint8_t read_source_layers_cache(keypos_t key) -{ - const uint8_t key_number = key.col + (key.row * MATRIX_COLS); - const uint8_t storage_row = key_number / 8; - const uint8_t storage_bit = key_number % 8; - uint8_t layer = 0; - - for (uint8_t bit_number = 0; bit_number < MAX_LAYER_BITS; bit_number++) { - layer |= - ((source_layers_cache[storage_row][bit_number] - & (1U << storage_bit)) != 0) - << bit_number; - } - - return layer; +/** \brief read source layers cache + * + * reads the cached keys stored when the layer was changed + */ +uint8_t read_source_layers_cache(keypos_t key) { + const uint8_t key_number = key.col + (key.row * MATRIX_COLS); + const uint8_t storage_row = key_number / 8; + const uint8_t storage_bit = key_number % 8; + uint8_t layer = 0; + + for (uint8_t bit_number = 0; bit_number < MAX_LAYER_BITS; bit_number++) { + layer |= + ((source_layers_cache[storage_row][bit_number] + & (1U << storage_bit)) != 0) + << bit_number; + } + + return layer; } #endif @@ -278,61 +270,58 @@ uint8_t read_source_layers_cache(keypos_t key) * when the layer is switched after the down event but before the up * event as they may get stuck otherwise. */ -action_t store_or_get_action(bool pressed, keypos_t key) -{ +action_t store_or_get_action(bool pressed, keypos_t key) { #if !defined(NO_ACTION_LAYER) && !defined(STRICT_LAYER_RELEASE) - if (disable_action_cache) { - return layer_switch_get_action(key); - } - - uint8_t layer; - - if (pressed) { - layer = layer_switch_get_layer(key); - update_source_layers_cache(key, layer); - } - else { - layer = read_source_layers_cache(key); - } - return action_for_key(layer, key); -#else + if (disable_action_cache) { return layer_switch_get_action(key); + } + + uint8_t layer; + + if (pressed) { + layer = layer_switch_get_layer(key); + update_source_layers_cache(key, layer); + } + else { + layer = read_source_layers_cache(key); + } + return action_for_key(layer, key); +#else + return layer_switch_get_action(key); #endif } /** \brief Layer switch get layer * - * FIXME: Needs docs + * Gets the layer based on key info */ -int8_t layer_switch_get_layer(keypos_t key) -{ +int8_t layer_switch_get_layer(keypos_t key) { #ifndef NO_ACTION_LAYER - action_t action; - action.code = ACTION_TRANSPARENT; - - uint32_t layers = layer_state | default_layer_state; - /* check top layer first */ - for (int8_t i = 31; i >= 0; i--) { - if (layers & (1UL<<i)) { - action = action_for_key(i, key); - if (action.code != ACTION_TRANSPARENT) { - return i; - } - } + action_t action; + action.code = ACTION_TRANSPARENT; + + uint32_t layers = layer_state | default_layer_state; + /* check top layer first */ + for (int8_t i = 31; i >= 0; i--) { + if (layers & (1UL<<i)) { + action = action_for_key(i, key); + if (action.code != ACTION_TRANSPARENT) { + return i; + } } - /* fall back to layer 0 */ - return 0; + } + /* fall back to layer 0 */ + return 0; #else - return biton32(default_layer_state); + return biton32(default_layer_state); #endif } /** \brief Layer switch get layer * - * FIXME: Needs docs + * Gets action code based on key position */ -action_t layer_switch_get_action(keypos_t key) -{ - return action_for_key(layer_switch_get_layer(key), key); +action_t layer_switch_get_action(keypos_t key) { + return action_for_key(layer_switch_get_layer(key), key); }