darkkirb/qmk_firmware
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Elaborate on keyboard level encoder functionality (#19839)

Browse source
This commit is contained in:
jack 2023-02-15 15:40:47 -07:00 committed by GitHub
parent e4c41b4337
commit 9cf58ec834
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 21 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

66
docs/feature_encoders.md
View file

@ -1,6 +1,6 @@
# Encoders # 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 ```make
ENCODER_ENABLE = yes ENCODER_ENABLE = yes
@ -104,9 +104,27 @@ 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`: When not using `ENCODER_MAP_ENABLE = yes`, the callback functions can be inserted into your `<keyboard>.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 ```c
bool encoder_update_kb(uint8_t index, bool clockwise) { bool encoder_update_kb(uint8_t index, bool clockwise) {
return encoder_update_user(index, 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);
} 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 true;
} }
``` ```
@ -131,49 +149,7 @@ bool encoder_update_user(uint8_t index, bool clockwise) {
} }
``` ```
!> 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. !> 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.
Layer conditions can also be used with the callback function like the following:
```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;
}
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.
## Hardware ## Hardware