[Docs] New section to modifier docs: Checking Modifier State

[precondition]

Description

Added a new section to the documentation on modifiers on the topic of checking modifier states. I explain how to use mod masks to detect modifiers and give two code examples, including the very frequently asked for shift + backspace → del functionality.

Speaking of the del example, I have used an implementation that involves creating a new variable uint8_t mod_state and using it in set_mods(mod_state). I know that it could be avoided by doing add_mods(MOD_MASK_SHIFT) or add_mods(MOD_BIT(KC_LSFT)) instead but I chose against the latter options for multiple reasons; add_mods(MOD_MASK_SHIFT) would enable both shifts which can be problematic for people for whom pressing both shifts produces something special like toggling Caps Lock. add_mods(MOD_BIT(KC_LSFT)) presupposes that the user chorded KC_BSPC with KC_LSFT which may or may not be the case. This can be problematic for people who use the distinction between left and right shift in other places of their code. Using set_mods(mod_state) might be a little more complex but it avoids those edge cases.

The main problem with the proposed implementation of shift + backspace for delete is that if you hold KC_BSPC held and then turn shift on and off while holding down KC_BSPC, it will ignore the custom shift mapping. The custom shift code only applies on the conditions of the initial press of KC_BSPC. Let me know if there is an implementation which solves this issue.

Since this also explains functions such as add_mods(), can I remove these kinds of comments in tmk_core/common/action_util.c?:

/** \brief Set oneshot layer
 *
 * FIXME: needs doc
 */

Types of Changes

• Core
• Bugfix
• New feature
• Enhancement/optimization
• Keyboard (addition or update)
• Keymap/layout/userspace (addition or update)
• Documentation

Issues Fixed or Closed by This PR

• N/A

Checklist

• My code follows the code style of this project: C, Python
• I have read the PR Checklist document and have made the appropriate changes.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• I have tested the changes and verified that they work and don't break anything (as well as I can manage).

[drashna]

It may be wise to add a link on how to use bitwise operations here, too. :D

As well as cross linking to the macro docs:
https://github.com/qmk/qmk_firmware/blob/master/docs/feature_macros.md#advanced-macros

[precondition]

I've felt like it would be a good idea to add an explanation on the format of the modifier bitmask while we're at it but I'm not entirely convinced of the C_LS_LA_LG_LC_RS_RA_RG_R notation. Is there something better I can use? I've first thought about something like LCLSLALGRCRSRARG but it definitely exceeds 8 characters and is pretty hard to read.

In other respects, my question here still stands unanswered:

Since this also explains functions such as add_mods(), can I remove these kinds of comments in tmk_core/common/action_util.c?:

/** \brief Set oneshot layer
 *
 * FIXME: needs doc
 */

_{^{PS: Sorry that it took me so long to update the PR}}

[fauxpark]

How about:

CSAG_RCSAG_L

(because the right hand mods are actually in the top nibble)

In other respects, my question here still stands unanswered

Those are doc comments, and should be filled out too, but they should describe (briefly) what the function itself does, its parameters and return value, as well as any other pertinent info.

[precondition]

Those are doc comments, and should be filled out too, but they should describe (briefly) what the function itself does, its parameters and return value, as well as any other pertinent info.

Ah so it's more of a in-code docstring that's expected here?

[fauxpark]

Yep, they are supposed to be added to the online docs using Doxygen, but they mostly aren't currently, for...reasons. You can see some of it in the QMK Internals section.

[precondition]

How about:

CSAG_RCSAG_L

(because the right hand mods are actually in the top nibble)

Shouldn't it instead be (GASC)_R(GASC)_L?

I wrote a quick python script to test

def MOD_INDEX(code):
    return code & 0x07

def MOD_BIT(code):
    return 1 << MOD_INDEX(code)

modifiers_codes = []
for code in range(0xE0, 0xE0+8):
    modifiers_codes.append(MOD_BIT(code))

modifiers_names = ["KC_LCTRL", "KC_LSHIFT", "KC_LALT", "KC_LGUI", "KC_RCTRL", "KC_RSHIFT", "KC_RALT", "KC_RGUI"]

for name, code in zip(modifiers_names, modifiers_codes):
    print(name.ljust(9) + ": " + format(code, "08b").rjust(8))

and the result is

KC_LCTRL : 00000001
KC_LSHIFT: 00000010
KC_LALT  : 00000100
KC_LGUI  : 00001000
KC_RCTRL : 00010000
KC_RSHIFT: 00100000
KC_RALT  : 01000000
KC_RGUI  : 10000000

[precondition]

Surprisingly enough, my example is still correct :p

[drashna]

I kind of feel that this would be better in the feature macros document, than in this one

[precondition]

If I'd like to know how to check modifier state in order to change the behaviour of a certain key when a specific modifier is active, I wouldn't be tempted to go look into the page about macros which “allow you to send multiple keystrokes when pressing just one key”. I don't want to send multiple keystrokes with a single key press.

[drashna]

I agree, but most of the documentation about process_record_* is in the macro page.

And considering that is what you're using ...

A decent compromise would be a link on the macros page to this documentation.

[precondition]

I agree, but most of the documentation about process_record_* is in the macro page.

And considering that is what you're using ...

A decent compromise would be a link on the macros page to this documentation.

@drashna what about this?

[precondition]

PR #10549 got merged in qmk:master in the last develop merge so I updated the documentation accordingly

[jack-davidson]

This pr has been really helpful for me. Precondition helped my on the qmk discord by giving me a link to this. I think that this needs to be added to the official docs because it is not clear for a new user in the docs to make something where you have ctrl-h to do backspace or other mods which you need to check the mod state to use. For example:

  77   │ // Initialize variable holding the binary
  78   │ // representation of active modifiers.
  79   │ uint8_t mod_state;
  80   │ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
  81   │     // Store the current modifier state in the variable for later reference
  82   │     mod_state = get_mods();
  83   │     switch (keycode) {
  84   │         case KC_H:
  85   │         {
  86   │             // Initialize a boolean variable that keeps track
  87   │             // of the bspc key status: registered or not?
  88   │             static bool bspckey_registered;
  89   │             if (record->event.pressed) {
  90   │                 // Detect the activation of either control keys
  91   │                 if (mod_state & MOD_MASK_CTRL) {
  92   │                     // First temporarily canceling both controls so that
  93   │                     // control isn't applied to the KC_BSPC keycode
  94   │                     del_mods(MOD_MASK_CTRL);
  95   │                     register_code(KC_BSPC);
  96   │                     // Update the boolean variable to reflect the status of KC_BSPC
  97   │                     bspckey_registered = true;
  98   │                     // Reapplying modifier state so that the held control key(s)
  99   │                     // still work even after having tapped the H/Backspace key.
 100   │                     set_mods(mod_state);
 101   │                     return false;
 102   │                 }
 103   │             } else { // on release of KC_H
 104   │                 // In case KC_BSPC is still being sent even after the release of KC_H
 105   │                 if (bspckey_registered) {
 106   │                 unregister_code(KC_BSPC);
 107   │                 bspckey_registered = false;
 108   │                 return false;
 109   │                 }
 110   │             }
 111   │             // Let QMK process the KC_H keycode as usual outside of control
 112   │             return true;
 113   │         }
 114   │     }
 115   │     return true;
 116   │ };

That would be quite hard to make as a new user but is much easier once I read the documentation. Precondition provided me with this by making some modifications to his example in the docs and I learned quite a bit from that. I think other new users would have the same feeling if this documentation was added to the official documentation collection and was given a high priority spot on the docs page.

[drashna]

Have some merge conflicts

[precondition]

Woops, I rebased on the wrong branch

[precondition]

Have some merge conflicts

@drashna Resolved the merge conflicts