From 65526a1df69d91392f399533269bb375a47853f9 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Tue, 15 May 2018 22:33:48 +0200 Subject: [PATCH] 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 --- doc/glossary.md | 35 ++++++++++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/doc/glossary.md b/doc/glossary.md index c129ee14..03e314c5 100644 --- a/doc/glossary.md +++ b/doc/glossary.md @@ -4,10 +4,39 @@ This document is intended to name and describe the concepts, functions and data 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 +Entries should be included in dictionary order. When describing an identifier of any kind from the codebase, it should be written using identical capitalization to its use in the code and surrounded by backticks: `identifierName` +### Cycle -Event handler +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. -: A function, usually provided by a `Plugin` that is run by a `Hook` +### 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.