summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/feature_encoders.md66
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