From 75adcf4da924753113861ca5776e00dd86b5d315 Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Tue, 3 Jun 2025 09:59:22 +1000 Subject: [PATCH] Invert logic for encoder map, enabling by default. - Removes `ENCODER_MAP_ENABLE=yes` as it's now the default behaviour. - Adds `ENCODER_CALLBACKS_ENABLE=yes` to restore historical behaviour. - Docs updated to reflect the new logic. --- builddefs/common_features.mk | 5 ++++- builddefs/show_options.mk | 2 +- docs/features/encoders.md | 36 ++++++++++++++++++++++++------------ docs/features/swap_hands.md | 2 +- docs/pr_checklist.md | 2 +- 5 files changed, 31 insertions(+), 16 deletions(-) diff --git a/builddefs/common_features.mk b/builddefs/common_features.mk index ca60873becf..c299df88463 100644 --- a/builddefs/common_features.mk +++ b/builddefs/common_features.mk @@ -929,7 +929,10 @@ ifeq ($(strip $(ENCODER_ENABLE)), yes) SRC += encoder_$(strip $(ENCODER_DRIVER)).c endif - ifeq ($(strip $(ENCODER_MAP_ENABLE)), yes) + # Encoder callbacks are now opt-in, default is encoder map + ifeq ($(strip $(ENCODER_CALLBACKS_ENABLE)), yes) + OPT_DEFS += -DENCODER_CALLBACKS_ENABLE + else OPT_DEFS += -DENCODER_MAP_ENABLE endif endif diff --git a/builddefs/show_options.mk b/builddefs/show_options.mk index 1c1a3ebf8e0..a9100ce8de6 100644 --- a/builddefs/show_options.mk +++ b/builddefs/show_options.mk @@ -55,7 +55,7 @@ OTHER_OPTION_NAMES = \ HELIX ZINC \ AUTOLOG_ENABLE \ DEBUG_ENABLE \ - ENCODER_MAP_ENABLE \ + ENCODER_CALLBACKS_ENABLE \ ENCODER_ENABLE_CUSTOM \ GERMAN_ENABLE \ HAPTIC_ENABLE \ diff --git a/docs/features/encoders.md b/docs/features/encoders.md index a674eaa4a64..c3201a30311 100644 --- a/docs/features/encoders.md +++ b/docs/features/encoders.md @@ -73,16 +73,12 @@ Keep in mind that whenver you change the encoder resolution, you will need to re ## Encoder map {#encoder-map} -Encoder mapping may be added to your `keymap.c`, which replicates the normal keyswitch layer handling functionality, but with encoders. Add this to your keymap's `rules.mk`: +Encoder mapping may be added to your `keymap.c`, which replicates the normal keyswitch layer handling functionality, but with encoders. -```make -ENCODER_MAP_ENABLE = yes -``` - -Your `keymap.c` will then need an encoder mapping defined (for four layers and two encoders): +Your `keymap.c` will then need an encoder mapping defined (in this example, for four layers and two encoders): ```c -#if defined(ENCODER_MAP_ENABLE) +#if !defined(ENCODER_CALLBACKS_ENABLE) const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] = { [0] = { ENCODER_CCW_CW(MS_WHLU, MS_WHLD), ENCODER_CCW_CW(KC_VOLD, KC_VOLU) }, [1] = { ENCODER_CCW_CW(UG_HUED, UG_HUEU), ENCODER_CCW_CW(UG_SATD, UG_SATU) }, @@ -92,10 +88,6 @@ const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] = { #endif ``` -::: tip -This should only be enabled at the keymap level. -::: - Using encoder mapping pumps events through the normal QMK keycode processing pipeline, resulting in a _keydown/keyup_ combination pushed through `process_record_xxxxx()`. To configure the amount of time between the encoder "keyup" and "keydown", you can add the following to your `config.h`: ```c @@ -108,13 +100,30 @@ By default, the encoder map delay matches the value of `TAP_CODE_DELAY`. ## Callbacks +::: warning +Encoder callbacks were the initial method of using encoders with QMK. This strategy has been deprecated, and should not be used going forward as it is slated for removal. +::: + +To enable encoder callbacks, add the following to your `rules.mk` file: + +```mk +ENCODER_CALLBACKS_ENABLE = yes +``` + +This will disable any use of encoder map. + +::: tip +This should only be enabled at the keymap level. +::: + ::: tip [**Default Behaviour**](https://github.com/qmk/qmk_firmware/blob/master/quantum/encoder.c#L79-): all encoders installed will function as volume up (`KC_VOLU`) on clockwise rotation and volume down (`KC_VOLD`) on counter-clockwise rotation. If you do not wish to override this, no further configuration is necessary. ::: -If you would like the alter the default behaviour, and are not using `ENCODER_MAP_ENABLE = yes`, the callback functions can be inserted into your `.c`: +If you would like the alter the default behaviour, the callback functions can be inserted into your `.c`: ```c +#if defined(ENCODER_CALLBACKS_ENABLE) 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 */ @@ -134,11 +143,13 @@ bool encoder_update_kb(uint8_t index, bool clockwise) { } return true; } +#endif ``` or `keymap.c`: ```c +#if defined(ENCODER_CALLBACKS_ENABLE) bool encoder_update_user(uint8_t index, bool clockwise) { if (index == 0) { /* First encoder */ if (clockwise) { @@ -155,6 +166,7 @@ bool encoder_update_user(uint8_t index, bool clockwise) { } return false; } +#endif ``` ::: warning diff --git a/docs/features/swap_hands.md b/docs/features/swap_hands.md index 0090ce77a9d..22aaa01befc 100644 --- a/docs/features/swap_hands.md +++ b/docs/features/swap_hands.md @@ -40,7 +40,7 @@ Encoder indexes are defined as left-to-right, and the extent of the array needs As an example, if a split keyboard has a single encoder per side, you can swap the order by using the following code in your keymap: ```c -#if defined(SWAP_HANDS_ENABLE) && defined(ENCODER_MAP_ENABLE) +#if defined(SWAP_HANDS_ENABLE) && !defined(ENCODER_CALLBACKS_ENABLE) const uint8_t PROGMEM encoder_hand_swap_config[NUM_ENCODERS] = { 1, 0 }; #endif ``` diff --git a/docs/pr_checklist.md b/docs/pr_checklist.md index 61119178bb4..c089bd5bd07 100644 --- a/docs/pr_checklist.md +++ b/docs/pr_checklist.md @@ -106,7 +106,7 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard - no re-definitions of the default MCU parameters if same value, when compared to the equivalent MCU in [mcu_selection.mk](https://github.com/qmk/qmk_firmware/blob/master/builddefs/mcu_selection.mk) - no "keymap only" features enabled - `COMBO_ENABLE` - - `ENCODER_MAP_ENABLE` + - `ENCODER_CALLBACKS_ENABLE` - keyboard `config.h` - no `#define DESCRIPTION` - no Magic Key Options, MIDI Options or HD44780 configuration