Previously, we used index-ordering for layers, meaning, we looked keys up based
on the index of active layers. This turned out to be confusing, and in many
cases, limiting, since we couldn't easily shift to a lower layer from a higher
one. As such, index-ordering required careful planning of one's layers, and a
deeper understanding of the system.
This patch switches us to activation-ordering: the layer subsystem now keeps
track of the order in which layers are activated, and uses that order to look
keys up, instead of the index of layers. This makes it easier to understand how
the system works, and allows us to shift to lower layers too.
It does require a bit more resources, since we can't just store a bitmap of
active layers, but need 32 bytes to store the order. We still keep the bitmap,
to make `Layer.isActive()` fast: looking up a bit in the bitmap is more
efficient than walking the active layer array, and this function is often used
in cases where speed matters.
As a side effect of the switch, a number of methods were deprecated, and similar
ones with more appropriate names were introduced. See the updated `UPGRADING.md`
document for more details.
Plugins that used the deprecated methods were updated to use the new ones.
Fixes#857.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
Key masking was a bandaid, and we have better ways to achieve the same thing
now. All current users have been switched over to different methods now, so lets
deprecate the masking.
We only put the `DEPRECATED` label on the `maskKey` method, because the rest are
used internally too, and we do not want to emit warnings for those.
Fixes#884.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
Originally scheduled for removal by mid-March. This also removes the similarly
deprecated named hardware object aliases.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
This adds `LEDControl.disable()` and `LEDControl.enable()` which disable and
enable LED operations, respectively. These are meant to replace the current
`LEDControl.paused` property (which is getting deprecated with this change), and
do some additional work on top of just disabling or re-enabling future updates
and sync. Namely, `disable()` will also turn LEDs off, while `enable()` will
refresh them all, too.
We also add a dedicated `Key_LEDToggle` key to disable/enable LEDs. This is
useful when one wants to turn LEDs off, without changing active LED mode to
`LEDOff`.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
This was done to enable separate inclusion of the central runtime
class without having to include the central header
kaleidoscope/Kaleidoscope.h which used to pull in a lot of stuff that is
not required in many compilation units.
The new class `Runtime_` lives in namespace kaleidoscope its singleton
instance is `kaleidoscope::Runtime`. It is now only available internally
in library Kaleidoscope but not from the sketch.
The original class name `Kaleidoscope_` in global scope has been deprecated.
The original instance name `Kaleidoscope` in global scope has been
preserved to be used by end users in their sketches.
Signed-off-by: Florian Fleissner <florian.fleissner@inpartik.de>
Unions are a C-reminiscense that are better avoided in modern C++.
They cause specific problems due to their nature of representing
independent types. The way they are used in Kaleidoscope, they
can easily be replaced by a class.
This enables it to properly work with Key objects in constexpr context
where with the old union-based implementation the compiler reported
errors when one Key was constructed based on a key_code/flags pair and
another one through raw-data. In such a case, the compiler assumes that
both Key instances represent something entirely different. This is
because unions were never meant for type conversions and the C++
standard considers their use for that purpose as undefined behavior.
The new class provides accessor methods for raw-data access and for
key_code/flags-data access.
This is a breaking change as it is is not possible to replace direct
member access patterns like
key.raw = 0xFFFF;
based on the raw-accessors.
For the .keyCode and .flags members, proxy objects are used
to enable the generation of suitable deprecations warnings.
All direct access via .raw, .keyCode and .flags have been replaced
throughout Kaleidoscope.
Information on how to upgrade is provided in UPGRADING.md
Signed-off-by: Florian Fleissner <florian.fleissner@inpartik.de>
The new device APIs were built on top of composition (instead of inheritance,
like the former one). At the highest level, we have `kaleidoscope::device::Base`
and `kaleidoscope::device::BaseProps`. The latter is a set of overrideable
properties, components that make up the device: the key scanner, LEDs, MCU, and
so on.
Many components - like the key scanner and LEDs - also come in a similar setup:
the base class and properties, because this allows us to make them fairly
efficient templates.
All of the existing devices have been ported to the new APIs. While the old
`Hardware` base class remains - for now, and deprecated - it is not guaranteed
to work.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
Some boards used to provide the device object under an alias named after the
device itself. For the sake of consistency, we do not want to provide these
aliases in the future. As such, deprecate them, and update all users to use
`KeyboardHardware` instead.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
Various old methods provided by `Layer` have been deprecated for a while, and
were scheduled to be removed by February 14, 2019. We're past that, so lets
remove them.
Fixes#577.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
In general, we want method names to be verbs, because they convey actions. The
`Layer.on()`, `Layer.off()`, etc family of functions weren't like that. It
wasn't immediately obvious that they turn layers on and off.
Furthermore, `Layer.next()` and `Layer.previous()` were even more confusing,
because one could easily think they implied moving to the selected layers, while
in practice, they just activated them.
All of these have new names, that better describe what they do. The old names
are still present, but emit a deprecation warning.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
In the original `KeyboardioFirmware`, this was used to store the default keymap
index in EEPROM. When we removed the EEPROM storage, it was meant to be used by
sketches to set a default layer (the minimum layer one can switch to), which was
not nearly as useful. Even worse, the behaviour was complicated to reason about,
and it wasn't used anyway.
For these reasons, it is now deprecated, and will eventually be removed.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
After talking with Jesse, this changes the license to GPLv3 (only), where
appropriate, and adds copyright headers to all files that were missing them.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Scheduled for removal on 2018-08-20, this drops the V1 API and all deprecation
messages. We only keep one message, that errors out in case
`KALEIDOSCOPE_ENABLE_V1_PLUGIN_API` is set. Also drops `Consumer_SNapshot`,
which was a typo'd name.
`UPGRADING.md` updated accordingly.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
As per UPGRADE.md, remove `Kaleidoscope.setup(KEYMAP_SIZE)`,
`event_handler_hook_use`, `loop_hook_use`, `USE_PLUGINS`, `MOMENTARY_OFFSET`,
`key_was_pressed`, `key_is_pressed`, `key_toggled_on`, and `key_toggled_off`.
These were deprecated between July and October 2017, and have been marked for
deletion for over a month.
Also updated UPGRADE.md, moving the section about these to a new, "deprecated
and removed" section.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
By far the most common deprecation will be the event handler and loop hook
deprecation. Make them less scary, and point out that unless one's a developer,
they likely need not care.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
Moving the deprecation messages to a separate header, and adding a few helpers
allow us to write much more detailed deprecation messages, without needlessly
making the code look incredibly messy.
This also updates most of the deprecation messages to be much more helpful, and
provide hints at how to fix the warnings produced by them.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
Jesse Vincent
Gergely Nagy
Florian Fleissner
Gergely Nagy