diff options
| -rw-r--r-- | docs/feature_encoders.md | 66 | 
1 files changed, 21 insertions, 45 deletions
| diff --git a/docs/feature_encoders.md b/docs/feature_encoders.md index cccdcbe4b3..1c521a4eff 100644 --- a/docs/feature_encoders.md +++ b/docs/feature_encoders.md @@ -1,6 +1,6 @@  # Encoders -Basic encoders are supported by adding this to your `rules.mk`: +Basic (EC11 compatible) encoders are supported by adding this to your `rules.mk`:  ```make  ENCODER_ENABLE = yes @@ -104,16 +104,13 @@ Using encoder mapping pumps events through the normal QMK keycode processing pip  When not using `ENCODER_MAP_ENABLE = yes`, the callback functions can be inserted into your `<keyboard>.c`: -```c -bool encoder_update_kb(uint8_t index, bool clockwise) { -    return encoder_update_user(index, clockwise); -} -``` - -or `keymap.c`: +?> Those who are adding new keyboard support where encoders are enabled at the keyboard level should include basic encoder functionality at the keyboard level (`<keyboard>.c`) using the `encoder_update_kb()` function, that way it works for QMK Configuator users and exists in general.  ```c -bool encoder_update_user(uint8_t index, bool clockwise) { +bool encoder_update_kb(uint8_t index, bool clockwise) { +    if (!encoder_update_user(index, clockwise)) { +      return false; /* Don't process further events if user function exists and returns false */ +    }      if (index == 0) { /* First encoder */          if (clockwise) {              tap_code_delay(KC_VOLU, 10); @@ -127,53 +124,32 @@ bool encoder_update_user(uint8_t index, bool clockwise) {              rgb_matrix_decrease_hue();          }      } -    return false; +    return true;  }  ``` -!> If you return `true`, it will allow the keyboard level code to run as well. Returning `false` will override the keyboard level code, depending on how the keyboard function is set up. - -Layer conditions can also be used with the callback function like the following: +or `keymap.c`:  ```c  bool encoder_update_user(uint8_t index, bool clockwise) { -    switch(get_highest_layer(layer_state|default_layer_state)) { -        case 0: -            if (index == 0) { -                if (clockwise) { -                    tap_code(KC_PGDN); -                } else { -                    tap_code(KC_PGUP); -                } -            } else if (index == 1) { -                if (clockwise) { -                    rgb_matrix_increase_speed(); -                } else { -                    rgb_matrix_decrease_speed(); -                } -            } -            break; -        case 1: -            if (index == 0) { -                if (clockwise) { -                    tap_code(KC_WH_D); -                } else { -                    tap_code(KC_WH_U); -                } -            } else if (index == 1) { -                if (clockwise) { -                    tap_code_delay(KC_VOLU, 10); -                } else { -                    tap_code_delay(KC_VOLD, 10); -                } -            } -            break; +    if (index == 0) { /* First encoder */ +        if (clockwise) { +            tap_code_delay(KC_VOLU, 10); +        } else { +            tap_code_delay(KC_VOLD, 10); +        } +    } else if (index == 1) { /* Second encoder */ +        if (clockwise) { +            rgb_matrix_increase_hue(); +        } else { +            rgb_matrix_decrease_hue(); +        }      }      return false;  }  ``` -?> Media and mouse countrol keycodes such as `KC_VOLU` and `KC_WH_D` requires `EXTRAKEY_ENABLE = yes` and `MOUSEKEY_ENABLE = yes` respectively in user's `rules.mk` if they are not enabled as default on keyboard level configuration. +!> If you return `true` in the keymap level `_user` function, it will allow the keyboard level encoder code to run on top of your own. Returning `false` will override the keyboard level function, if setup correctly. This is generally the safest option to avoid confusion.  ## Hardware | 
