[Docs] New section to modifier docs: Checking Modifier State (#10550)
* Added new section to docs: Checking Modifier State
* Added id anchors to all headers in modifiers docs
* Added a Wikipedia link to bitwise operators and...
crosslinked to the QMK macro docs.
* Added an explanation on the format of mod bitmask
* Added .md extension to hyperlinks to macros docs
* Corrected mod mask order and changed notation
* Documented add_oneshot_mods and del_oneshot_mods
* Mentioned modifier checks in the macro docs
* Explained strict modifier checking
i.e. using `get_mods() & MOD_MASK == MOD_MASK` instead of simply
`get_mods() & MOD_MASK`
* Added (un)register_mods to the docs
* Put left term of comparison in parens
@ -23,6 +23,141 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown
You can also chain them, for example `LCTL(LALT(KC_DEL))` or `C(A(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
# Checking Modifier State :id=checking-modifier-state
The current modifier state can mainly be accessed with two functions: `get_mods()` for normal modifiers and modtaps and `get_oneshot_mods()` for one-shot modifiers (unless they're held, in which case they act like normal modifier keys).
The presence of one or more specific modifiers in the current modifier state can be detected by ANDing the modifier state with a mod mask corresponding to the set of modifiers you want to match for. The reason why bitwise operators are used is that the modifier state is stored as a single byte in the format (GASC)<sub>R</sub>(GASC)<sub>L</sub>.
Thus, to give an example, `01000010` would be the internal representation of LShift+RAlt.
For more information on bitwise operators in C, click [here](https://en.wikipedia.org/wiki/Bitwise_operations_in_C) to open the Wikipedia page on the topic.
In practice, this means that you can check whether a given modifier is active with `get_mods() & MOD_BIT(KC_<modifier>)` (see the [list of modifier keycodes](keycodes_basic.md#modifiers)) or with `get_mods() & MOD_MASK_<modifier>` if the difference between left and right hand modifiers is not important and you want to match both. Same thing can be done for one-shot modifiers if you replace `get_mods()` with `get_oneshot_mods()`.
To check that *only* a specific set of mods is active at a time, AND the modifier state and your desired mod mask as explained above and compare the result to the mod mask itself: `get_mods() & <mod mask> == <mod mask>`.
For example, let's say you want to trigger a piece of custom code if one-shot left control and one-shot left shift are on but every other one-shot mods are off. To do so, you can compose the desired mod mask by combining the mod bits for left control and shift with `(MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT))` and then plug it in: `get_oneshot_mods & (MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT)) == (MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT))`. Using `MOD_MASK_CS` instead for the mod bitmask would have forced you to press four modifier keys (both versions of control and shift) to fulfill the condition.
Aside from accessing the currently active modifiers using `get_mods()`, there exists some other functions you can use to modify the modifier state, where the `mods` argument refers to the modifiers bitmask.
* `add_mods(mods)`: Enable `mods` without affecting any other modifiers
* `register_mods(mods)`: Like `add_mods` but send a keyboard report immediately.
* `del_mods(mods)`: Disable `mods` without affecting any other modifiers
* `unregister_mods(mods)`: Like `del_mods` but send a keyboard report immediately.
* `set_mods(mods)`: Overwrite current modifier state with `mods`
* `clear_mods()`: Reset the modifier state by disabling all modifiers
Similarly, in addition to `get_oneshot_mods()`, there also exists these functions for one-shot mods:
* `add_oneshot_mods(mods)`: Enable `mods` without affecting any other one-shot modifiers
* `del_oneshot_mods(mods)`: Disable `mods` without affecting any other one-shot modifiers
* `set_oneshot_mods(mods)`: Overwrite current one-shot modifier state with `mods`
* `clear_oneshot_mods()`: Reset the one-shot modifier state by disabling all one-shot modifiers
## Examples :id=examples
The following examples use [advanced macro functions](feature_macros.md#advanced-macro-functions) which you can read more about in the [documentation page on macros](feature_macros.md).
### Alt + Escape for Alt + Tab :id=alt-escape-for-alt-tab
Simple example where chording Left Alt with `KC_ESC` makes it behave like `KC_TAB` for alt-tabbing between applications. This example strictly checks if only Left Alt is active, meaning you can't do Alt+Shift+Esc to switch between applications in reverse order. Also keep in mind that this removes the ability to trigger the actual Alt+Escape keyboard shortcut, though it keeps the ability to do AltGr+Escape.
if ((get_mods() & MOD_BIT(KC_LALT)) == MOD_BIT(KC_LALT)) {
if (record->event.pressed) {
// No need to register KC_LALT because it's already active.
// The Alt modifier will apply on this KC_TAB.
register_code(KC_TAB);
} else {
unregister_code(KC_TAB);
}
// Do not let QMK process the keycode further
return false;
}
// Else, let QMK process the KC_ESC keycode as usual
return true;
}
return true;
};
```
### Shift + Backspace for Delete :id=shift-backspace-for-delete
Advanced example where the original behaviour of shift is cancelled when chorded with `KC_BSPC` and is instead fully replaced by `KC_DEL`. Two main variables are created to make this work well: `mod_state` and `delkey_registered`. The first one stores the modifier state and is used to restore it after registering `KC_DEL`. The second variable is a boolean variable (true or false) which keeps track of the status of `KC_DEL` to manage the release of the whole Backspace/Delete key correctly.
As opposed to the previous example, this doesn't use strict modifier checking. Pressing `KC_BSPC` while one or two shifts are active is enough to trigger this custom code, regardless of the state of other modifiers. That approach offers some perks: Ctrl+Shift+Backspace lets us delete the next word (Ctrl+Delete) and Ctrl+Alt+Shift+Backspace lets us execute the Ctrl+Alt+Del keyboard shortcut.
// Store the current modifier state in the variable for later reference
mod_state = get_mods();
switch (keycode) {
case KC_BSPC:
{
// Initialize a boolean variable that keeps track
// of the delete key status: registered or not?
static bool delkey_registered;
if (record->event.pressed) {
// Detect the activation of either shift keys
if (mod_state & MOD_MASK_SHIFT) {
// First temporarily canceling both shifts so that
// shift isn't applied to the KC_DEL keycode
del_mods(MOD_MASK_SHIFT);
register_code(KC_DEL);
// Update the boolean variable to reflect the status of KC_DEL
delkey_registered = true;
// Reapplying modifier state so that the held shift key(s)
// still work even after having tapped the Backspace/Delete key.
set_mods(mod_state);
return false;
}
} else { // on release of KC_BSPC
// In case KC_DEL is still being sent even after the release of KC_BSPC
if (delkey_registered) {
unregister_code(KC_DEL);
delkey_registered = false;
return false;
}
}
// Let QMK process the KC_BSPC keycode as usual outside of shift
return true;
}
}
return true;
};
```
# Legacy Content :id=legacy-content
This page used to encompass a large set of features. We have moved many sections that used to be part of this page to their own pages. Everything below this point is simply a redirect so that people following old links on the web find what they're looking for.
There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro, if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple.
?> You can also use the functions described in [Useful functions](ref_functions.md) for additional functionality. For example `reset_keyboard()` allows you to reset the keyboard as part of a macro.
?> You can also use the functions described in [Useful function](ref_functions.md) and [Checking modifier state](feature_advanced_keycodes#checking-modifier-state) for additional functionality. For example,`reset_keyboard()` allows you to reset the keyboard as part of a macro and `get_mods() & MOD_MASK_SHIFT` lets you check for the existence of active shift modifiers.
precondition
3 years ago
GitHub