This repository has been archived by the owner. It is now read-only.

Explain what the range enum defined here is for #2

Merged
merged 1 commit into from Oct 19, 2017

Conversation

Projects
None yet
3 participants
@jamesnvc
Contributor

jamesnvc commented Oct 19, 2017

No description provided.

@obra obra merged commit 613ad91 into keyboardio:master Oct 19, 2017

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@algernon

I like the direction of where this is going. But I also think that the description falls a bit short, and doesn't explain well the difference between the flags + keyCode and the raw + kaleidoscope::ranges method, or why using both of them makes sense.

Mind you, doing this is a challenging job. The PR does add a lot of useful info, but we should improve it further at some (not too distant) point :)

@@ -2,3 +2,43 @@
This plugin contains the ranges used by a number of Kaleidoscope plugins. Mostly
useful for developers, but a dependency of other plugins, too.
If you're a plugin developer and need to know how you can make keycodes for just your plugin to consume, or are otherwise curious what this is for, read one.

This comment has been minimized.

@algernon

algernon Oct 19, 2017

Member

Should that read one at the end be read on instead?

@algernon

algernon Oct 19, 2017

Member

Should that read one at the end be read on instead?

This comment has been minimized.

@jamesnvc

jamesnvc Oct 19, 2017

Contributor

oops, yes indeed

@jamesnvc

jamesnvc Oct 19, 2017

Contributor

oops, yes indeed

However, many plugins want to be able to make key presses do something special and need some way of indicating that a key is not just an ordinary key.
To do this, we take advantage of the fact that our flags field is 8 bits, but there are only five normal modifiers (control, shift, GUI, right alt, and left alt).
<!-- question: does bit six have any signicance? it seems to be unused

This comment has been minimized.

@algernon

algernon Oct 19, 2017

Member

When the RESERVED bit is set, the other 15 bits have no special meaning anymore. When that is set, we only use the key.raw part of the union, the flags and keyCode are unused in this case.

Does that clear things up?

@algernon

algernon Oct 19, 2017

Member

When the RESERVED bit is set, the other 15 bits have no special meaning anymore. When that is set, we only use the key.raw part of the union, the flags and keyCode are unused in this case.

Does that clear things up?

This comment has been minimized.

@jamesnvc

jamesnvc Oct 19, 2017

Contributor

Oh, I was just noticing that bits 1-5 are for modifiers, bit 7 is injected, bit 8 is reserved but bit 6 has no meaning.

@jamesnvc

jamesnvc Oct 19, 2017

Contributor

Oh, I was just noticing that bits 1-5 are for modifiers, bit 7 is injected, bit 8 is reserved but bit 6 has no meaning.

Many plugins will want to do this, so how can they be sure that the key codes they make won't be interpreted by another plugin?
Thus, we come to the purpose of this enum:
The `range` enum gives the ranges of possible raw key values that each plugin will use; by referring to it, plugins can be sure none of them will step on each others' toes.

This comment has been minimized.

@algernon

algernon Oct 19, 2017

Member

My issue with this explanation is that... it is similar to how I'd explain it, and... well. It doesn't make much sense, isn't all that easy to follow.

Unfortunately, I have no better way to propose, either. (Will try to explain my issues later, a bit short on time at the moment)

@algernon

algernon Oct 19, 2017

Member

My issue with this explanation is that... it is similar to how I'd explain it, and... well. It doesn't make much sense, isn't all that easy to follow.

Unfortunately, I have no better way to propose, either. (Will try to explain my issues later, a bit short on time at the moment)

This comment has been minimized.

@jamesnvc

jamesnvc Oct 19, 2017

Contributor

Maybe we could just provide a few examples of normal key press, TapDance key, OneShot key?

@jamesnvc

jamesnvc Oct 19, 2017

Contributor

Maybe we could just provide a few examples of normal key press, TapDance key, OneShot key?

This comment has been minimized.

@jamesnvc

jamesnvc Oct 19, 2017

Contributor

Presumably the only people reading this are plugin authors that have some context to all this stuff?

@jamesnvc

jamesnvc Oct 19, 2017

Contributor

Presumably the only people reading this are plugin authors that have some context to all this stuff?

@obra

This comment has been minimized.

Show comment
Hide comment
@obra

obra Oct 19, 2017

Member

Apologies for over-zealous merging.

Member

obra commented Oct 19, 2017

Apologies for over-zealous merging.

@algernon

This comment has been minimized.

Show comment
Hide comment
@algernon

algernon Oct 19, 2017

Member

No worries. Some docs are better than none, and docs are the easiest to improve!

Member

algernon commented Oct 19, 2017

No worries. Some docs are better than none, and docs are the easiest to improve!

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.