# Trying to understand key flags and onKeyswitchEvent()

**URL:** <https://community.keyboard.io/t/trying-to-understand-key-flags-and-onkeyswitchevent/2435>\
**Category:** Programming\
**Created:** [January 19, 2019, 5:53am UTC](https://community.keyboard.io/t/trying-to-understand-key-flags-and-onkeyswitchevent/2435 "2019-01-19T05:53:11Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![tiltowaitt](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/tiltowaitt/32/4764_2.png) [@tiltowaitt](https://community.keyboard.io/u/tiltowaitt)\
**Post date:** [January 19, 2019, 5:53am UTC](https://community.keyboard.io/t/trying-to-understand-key-flags-and-onkeyswitchevent/2435/1 "2019-01-19T05:53:11Z")

</div>

In `onKeyswitchEvent()`, how does the mapped `Key`'s `.flags` variable work in the following situations?

1. Key toggled down, no modifiers
2. Key toggled down, shift already active
3. Shift key toggled down

It seems to me that in cases 2 & 3, `if(mapped_key.flags & SHIFT_HELD)` should return `true`, but that doesn’t seem to be the case—at least, not reliably so.

---

<div class="post-metadata">

**Author:** ![algernon](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/algernon/32/4404_2.png) [@algernon](https://community.keyboard.io/u/algernon)\
**Post date:** [January 19, 2019, 6:48am UTC](https://community.keyboard.io/t/trying-to-understand-key-flags-and-onkeyswitchevent/2435/2 "2019-01-19T06:48:26Z")

</div>

`SHIFT_HELD` is only put in flags if the key in question is `LSHIFT(Key_Something)`. Otherwise Shift is just a regular key held together with the rest. Well, mostly… we do send modifiers in a separate part of the report, but if shift is held, that does not appear in other keys’ `.flags`.

`.flags` is there to differentiate between normal keys and special keys that are only meaningful to the keyboard, such as the modifier-augmented ones, mouse keys, macros, layer keys, and so on.

---

<div class="post-metadata">

**Author:** ![tiltowaitt](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/tiltowaitt/32/4764_2.png) [@tiltowaitt](https://community.keyboard.io/u/tiltowaitt)\
**Post date:** [January 19, 2019, 6:52am UTC](https://community.keyboard.io/t/trying-to-understand-key-flags-and-onkeyswitchevent/2435/3 "2019-01-19T06:52:42Z")

</div>

I see. If I want to know if _any_ modifier is being held, what would be the best/simplest way to do so? Currently, I’m just using `wasModifierKeyActive()` a bunch of times, which seems inefficient.

---

<div class="post-metadata">

**Author:** ![algernon](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/algernon/32/4404_2.png) [@algernon](https://community.keyboard.io/u/algernon)\
**Post date:** [January 19, 2019, 6:58am UTC](https://community.keyboard.io/t/trying-to-understand-key-flags-and-onkeyswitchevent/2435/4 "2019-01-19T06:58:37Z")

</div>

While not a particularly nice or recommended API, you can look at `Keyboard.lastKeyReport.modifiers`. If it is non-zero, then the previous report cycle had modifiers. You can also look at `Keyboard.keyReport.modifiers` for the current report, but depending on where the scanner is in the scanning process, this might not be entirely up-to-date.

Can you file a bug on Kaleidoscope, requesting a proper API to discover all held modifiers?

---

<div class="post-metadata">

**Author:** ![tiltowaitt](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/tiltowaitt/32/4764_2.png) [@tiltowaitt](https://community.keyboard.io/u/tiltowaitt)\
**Post date:** [January 19, 2019, 5:32pm UTC](https://community.keyboard.io/t/trying-to-understand-key-flags-and-onkeyswitchevent/2435/5 "2019-01-19T17:32:06Z")

</div>

> [@algernon](#):
>
> Can you file a bug on Kaleidoscope, requesting a proper API to discover all held modifiers?

Can do. If it’s just going to follow the pattern of the existing `wasModifierKeyActive()` function, I can also submit a PR (sometime this evening).

EDIT: Also, how stable is the order of the bitmap in `Keyboard.lastKeyReport.modifiers`? I ask, because I also need to find out if any modifiers _other than shift_ are active. I can easily do this in a single line of code by applying a mask:

```c++
return Keyboard.lastKeyReport.modifiers & B11011101; // Running off of memory; not at my computer right now

```

It’s kind of an icky way of doing it, but it’s certainly fast. If the positions in the bit field are likely to change, however, I won’t do it.

---

<div class="post-metadata">

**Author:** ![algernon](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/algernon/32/4404_2.png) [@algernon](https://community.keyboard.io/u/algernon)\
**Post date:** [January 19, 2019, 5:38pm UTC](https://community.keyboard.io/t/trying-to-understand-key-flags-and-onkeyswitchevent/2435/6 "2019-01-19T17:38:35Z")

</div>

I didn’t think about how it’d look, the `wasModifierKeyActive()` pattern seems good, and a PR would be lovely. Thanks in advance!

---

<div class="post-metadata">

**Author:** ![tiltowaitt](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/tiltowaitt/32/4764_2.png) [@tiltowaitt](https://community.keyboard.io/u/tiltowaitt)\
**Post date:** [January 19, 2019, 5:40pm UTC](https://community.keyboard.io/t/trying-to-understand-key-flags-and-onkeyswitchevent/2435/7 "2019-01-19T17:40:39Z")

</div>

Cool; will do. Also, I just edited my previous post. Can you let me know if I’m doing something crazy? (This isn’t for the PR, but it’s related.)

---

<div class="post-metadata">

**Author:** ![algernon](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/algernon/32/4404_2.png) [@algernon](https://community.keyboard.io/u/algernon)\
**Post date:** [January 19, 2019, 5:52pm UTC](https://community.keyboard.io/t/trying-to-understand-key-flags-and-onkeyswitchevent/2435/8 "2019-01-19T17:52:58Z")

</div>

> [@tiltowaitt](#):
>
> ```c++
> return Keyboard.lastKeyReport.modifiers & B11011101;
> 
> ```

You can use something like this instead to make this easier:

```c++
const uint8_t modifierIndex = key.raw - Key_LeftControl.raw;
return Keyboard.lastKeyReport.modifiers & (1 << modifierIndex);

```

The order of modifiers is set in stone, from bit 0 to 8, it is Left Control, Left Shift, Left Alt, Left Gui, Right Control, Right Shift, Right Alt, Right Gui.

It might make sense to introduce a helper, that would build us a mask. Say, `kaleidoscope::hid::modifierBitMask(Key_LeftControl, Key_LeftShift)` would return `(1 << 0) | (1 << 1)`. This is doable with a little bit of templating, but a PR without this is just as good. The intended use is:

```c++
// assuming we're in the kaleidoscope::hid namespace
// return true-ish if Ctrl+Shift was held
return lastActiveModifiers() & modifierBitMask(Key_LeftControl, Key_LeftShift);

```

Another option is to have `#define`s for the various modifiers, stuff one could OR together, but I failed to come up with a good name for those, so went with the helper instead.

---

<div class="post-metadata">

**Author:** ![tiltowaitt](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/tiltowaitt/32/4764_2.png) [@tiltowaitt](https://community.keyboard.io/u/tiltowaitt)\
**Post date:** [January 20, 2019, 2:36am UTC](https://community.keyboard.io/t/trying-to-understand-key-flags-and-onkeyswitchevent/2435/10 "2019-01-20T02:36:48Z")

</div>

> [@algernon](#):
>
> a PR would be lovely

Issue and related PRs are [here](https://github.com/keyboardio/Kaleidoscope/issues/532). First time ever opening a PR, so hopefully I did everything okay.