Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Elaborate on keyboard level encoder functionality #19839

Merged
merged 2 commits into from
Feb 15, 2023
Merged

Elaborate on keyboard level encoder functionality #19839

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eaa20ab
initial
waffle87 Feb 13, 2023
3200256
apply suggestions
waffle87 Feb 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 21 additions & 45 deletions docs/feature_encoders.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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);
Expand All @@ -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

Expand Down