From f63860134658ae002184e5f1e0900d12b9adab09 Mon Sep 17 00:00:00 2001
From: waffle87 <0x6a73@protonmail.com>
Date: Wed, 15 Feb 2023 22:42:15 +0000
Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20@=20qmk/qmk?=
 =?UTF-8?q?=5Ffirmware@9cf58ec8349769195e81b5100faf76f380c02757=20?=
 =?UTF-8?q?=F0=9F=9A=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 feature_encoders.md | 66 +++++++++++++++------------------------------
 1 file changed, 21 insertions(+), 45 deletions(-)

diff --git a/feature_encoders.md b/feature_encoders.md
index cccdcbe4b31..1c521a4eff7 100644
--- a/feature_encoders.md
+++ b/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