Major redesign of the plugin and hooking interface
With this redesign, we introduce a new way to create plugins, which is easier to
extend with new hook points, provides a better interface, uses less memory, less
program space, and is a tiny bit faster too.
It all begins with `kaleidoscope::Plugin` being the base class, which provides
the hook methods plugins can implement. Plugins should be declared with
`KALEIDOSCOPE_INIT_PLUGINS` instead of `Kaleidoscope.use()`. Behind this macro
is a bit of magic (see the in-code documentation) that allows us to unroll the
hook method calls, avoid vtables, and so on. It creates an override for
`kaleidoscope::Hooks::*` methods, each of which will call the respective methods
of each initialized plugin.
With the new API come new names: all of the methods plugins can implement
received new, more descriptive names that all follow a similar pattern.
The old (dubbed V1) API still remains in place, although deprecated. One can
turn it off by setting the `KALEIDOSCOPE_ENABLE_V1_PLUGIN_API` define to zero,
while compiling the firmware.
This work is based on #276, written by @noseglasses. @obra and @algernon did
some cleaning up and applied a little naming treatment.
Signed-off-by: noseglasses <shinynoseglasses@gmail.com>
Signed-off-by: Jesse Vincent <jesse@keyboard.io>
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
7 years ago
|
|
|
# Glossary
|
|
|
|
|
|
|
|
|
|
This document is intended to name and describe the concepts, functions and data structures inside Kaleidoscope.
|
|
|
|
|
|
|
|
|
|
It is, as yet, incredibly incomplete.
|
|
|
|
|
|
|
|
|
|
Entries should be included in dictionary order. When describing an identifier of any kind from the codebase, it should be
|
Major redesign of the plugin and hooking interface
With this redesign, we introduce a new way to create plugins, which is easier to
extend with new hook points, provides a better interface, uses less memory, less
program space, and is a tiny bit faster too.
It all begins with `kaleidoscope::Plugin` being the base class, which provides
the hook methods plugins can implement. Plugins should be declared with
`KALEIDOSCOPE_INIT_PLUGINS` instead of `Kaleidoscope.use()`. Behind this macro
is a bit of magic (see the in-code documentation) that allows us to unroll the
hook method calls, avoid vtables, and so on. It creates an override for
`kaleidoscope::Hooks::*` methods, each of which will call the respective methods
of each initialized plugin.
With the new API come new names: all of the methods plugins can implement
received new, more descriptive names that all follow a similar pattern.
The old (dubbed V1) API still remains in place, although deprecated. One can
turn it off by setting the `KALEIDOSCOPE_ENABLE_V1_PLUGIN_API` define to zero,
while compiling the firmware.
This work is based on #276, written by @noseglasses. @obra and @algernon did
some cleaning up and applied a little naming treatment.
Signed-off-by: noseglasses <shinynoseglasses@gmail.com>
Signed-off-by: Jesse Vincent <jesse@keyboard.io>
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
7 years ago
|
|
|
written using identical capitalization to its use in the code and surrounded by backticks: `identifierName`
|
|
|
|
|
|
|
|
|
|
### Cycle
|
Major redesign of the plugin and hooking interface
With this redesign, we introduce a new way to create plugins, which is easier to
extend with new hook points, provides a better interface, uses less memory, less
program space, and is a tiny bit faster too.
It all begins with `kaleidoscope::Plugin` being the base class, which provides
the hook methods plugins can implement. Plugins should be declared with
`KALEIDOSCOPE_INIT_PLUGINS` instead of `Kaleidoscope.use()`. Behind this macro
is a bit of magic (see the in-code documentation) that allows us to unroll the
hook method calls, avoid vtables, and so on. It creates an override for
`kaleidoscope::Hooks::*` methods, each of which will call the respective methods
of each initialized plugin.
With the new API come new names: all of the methods plugins can implement
received new, more descriptive names that all follow a similar pattern.
The old (dubbed V1) API still remains in place, although deprecated. One can
turn it off by setting the `KALEIDOSCOPE_ENABLE_V1_PLUGIN_API` define to zero,
while compiling the firmware.
This work is based on #276, written by @noseglasses. @obra and @algernon did
some cleaning up and applied a little naming treatment.
Signed-off-by: noseglasses <shinynoseglasses@gmail.com>
Signed-off-by: Jesse Vincent <jesse@keyboard.io>
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
7 years ago
|
|
|
|
|
|
|
|
The `loop` method in one's sketch file is the heart of the firmware. It runs -
|
|
|
|
|
as the name suggests - in a loop. We call these runs cycles. A lot of things
|
|
|
|
|
happen within a cycle: from key scanning, through key event handling, LED
|
|
|
|
|
animations, and so on and so forth.
|
Major redesign of the plugin and hooking interface
With this redesign, we introduce a new way to create plugins, which is easier to
extend with new hook points, provides a better interface, uses less memory, less
program space, and is a tiny bit faster too.
It all begins with `kaleidoscope::Plugin` being the base class, which provides
the hook methods plugins can implement. Plugins should be declared with
`KALEIDOSCOPE_INIT_PLUGINS` instead of `Kaleidoscope.use()`. Behind this macro
is a bit of magic (see the in-code documentation) that allows us to unroll the
hook method calls, avoid vtables, and so on. It creates an override for
`kaleidoscope::Hooks::*` methods, each of which will call the respective methods
of each initialized plugin.
With the new API come new names: all of the methods plugins can implement
received new, more descriptive names that all follow a similar pattern.
The old (dubbed V1) API still remains in place, although deprecated. One can
turn it off by setting the `KALEIDOSCOPE_ENABLE_V1_PLUGIN_API` define to zero,
while compiling the firmware.
This work is based on #276, written by @noseglasses. @obra and @algernon did
some cleaning up and applied a little naming treatment.
Signed-off-by: noseglasses <shinynoseglasses@gmail.com>
Signed-off-by: Jesse Vincent <jesse@keyboard.io>
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
7 years ago
|
|
|
|
|
|
|
|
### Event handler
|
|
|
|
|
|
|
|
|
|
A function, usually provided by a [`Plugin`](#plugin) that is run by a [`Hook`](#hook).
|
|
|
|
|
|
|
|
|
|
At the time of this writing, the following event handlers are run by hooks:
|
|
|
|
|
|
|
|
|
|
- `onSetup`: Run once, when the plugin is initialised during
|
|
|
|
|
`Kaleidoscope.setup()`.
|
|
|
|
|
- `beforeEachCycle`: Run as the first thing at the start of each [cycle](#cycle).
|
|
|
|
|
- `onKeyswitchEvent`: Run for every non-idle key, in each [cycle](#cycle) the
|
|
|
|
|
key isn't idle in. If a key gets pressed, released, or is held, it is not
|
|
|
|
|
considered idle, and this event handler will run for it too.
|
|
|
|
|
- `beforeReportingState`: Runs each [cycle](#cycle) right before sending the
|
|
|
|
|
various reports (keys pressed, mouse events, etc) to the host.
|
|
|
|
|
- `afterEachCycle`: Runs at the very end of each [cycle](#cycle).
|
|
|
|
|
|
|
|
|
|
### Hook
|
|
|
|
|
|
|
|
|
|
A point where the core firmware calls [event handlers](#event-handler), allowing
|
|
|
|
|
[plugins](#plugin) to augment the firmware behaviour, by running custom code.
|
|
|
|
|
|
|
|
|
|
### Plugin
|
|
|
|
|
|
|
|
|
|
An Arduino library prepared to work with Kaleidoscope. They implement methods
|
|
|
|
|
from the `kaleidoscope::Plugin` (usually a subset of them). See [event
|
|
|
|
|
handlers](#event-handler) above for a list of methods.
|
