alpha
/
Kaleidoscope
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'd803f4731a'
${ noResults }
Kaleidoscope/docs/codebase/glossary.md

43 lines
1.8 KiB
Raw Normal View History Unescape

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.
doc/glossary.md: A small update Updates the formatting a bit, and adds a few entries too. Still much to be done, but... small steps! Signed-off-by: Gergely Nagy <algernon@keyboard.io>
7 years ago
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`
doc/glossary.md: A small update Updates the formatting a bit, and adds a few entries too. Still much to be done, but... small steps! Signed-off-by: Gergely Nagy <algernon@keyboard.io>
7 years ago
### 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
doc/glossary.md: A small update Updates the formatting a bit, and adds a few entries too. Still much to be done, but... small steps! 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
doc/glossary.md: A small update Updates the formatting a bit, and adds a few entries too. Still much to be done, but... small steps! 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.