diff --git a/README.md b/README.md index e3459cb1..c8e09aff 100644 --- a/README.md +++ b/README.md @@ -5,125 +5,4 @@ [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-EEPROM-Keymap-Programmer.svg?branch=master [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-EEPROM-Keymap-Programmer -Inspired by a similar feature on other keyboards, the `EEPROM-Keymap-Programmer` -plugin implements an on-device keymap re-arrangement / re-coding system. There -are two modes of operation: in one, we need to press a key we want to change, -then another to copy from. In the other, we press a key to change, and then -input a key code (terminated by any non-number key). - -## The two modes of operation - -It is worth looking at the two separately, to better understand how they work, -and what they accomplish: - -### Copy mode - -In `COPY` mode, the plugin will use both the built-in, default keymap, and the -override stored in `EEPROM`. When we select a key to override, we need to tap -another, which will be used as the source. The source key's code will be looked -up from the built-in keymap. For example, lets say we want to swap `A` and `B` -for some odd reason. We can do this by triggering the keymap programmer mode, -then tapping `A` to select it as the destination, then `B` as the source. The -plugin will look up the keycode in the built-in keymap for the key in `B`'s -location, and replace the location of `A` in the override with it. Next, we -press the `B` key to select it as the destination, and we press the key that -used to be `A` (but is now `B` too) to select it as a source. Because source -keys are looked up in the built-in keymap, the plugin will find it is `A`. - -Obviously, this method only works if we have a built-in keymap, and it does not -support copying from another layer. It is merely a way to rearrange simple -things, like alphanumerics. - -### Code mode - -In `CODE` mode, instead of selecting a source key, we need to enter a code: -press numbers to input the code, and any non-number key to end the sequence. -Thus, when entering keymap programmer mode, and selecting, say, the `A` key, -then tapping `5 SPACE` will set the key to `B` (which has the keycode of `5`). - -This allows us to use keycodes not present on the built-in keymap, at the -expense of having to know the keycode, and allowing no mistakes. - -## Using the plugin - -Adding the functionality of the plugin to a Sketch is easier the usage explained -above, though it requires that the [EEPROM-Keymap][plugin:eeprom-keymap] plugin -is also used, and set up appropriately. - -Once the prerequisites are dealt with, all we need to do is to use the plugin, -and find a way to trigger entering the keymap programmer mode. One such way is -to use a macro, as in the example below: - -```c++ -#include -#include -#include -#include -#include - -const macro_t *macroAction(uint8_t macroIndex, uint8_t keyState) { - if (macroIndex == 0 && keyToggledOff(keyState)) { - EEPROMKeymapProgrammer.activate(); - } - - return MACRO_NONE; -} - -KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings, - EEPROMKeymapProgrammer, - EEPROMKeymap, - Macros); - -void setup() { - Kaleidoscope.setup(); - - Layer.getKey = EEPROMKeymap.getKey; - - EEPROMKeymap.max_layers(1); - EEPROMSettings.seal(); -} -``` - -The plugin should be used as early as possible, otherwise other plugins that -hook into the event system may start processing events before the programmer can -take over. - -## Plugin methods - -The plugin provides the `EEPROMKeymapProgrammer` object, which has the following -methods and properties: - -### `.activate()` - -> Activates the keymap programmer. This is the function one needs to call from - -> say - a macro, to enter the edit state. - -### `.mode` - -> Set this property to the mode to use for editing: either -> `kaleidoscope::EEPROMKeymapProgrammer::COPY`, or -> `kaleidoscope::EEPROMKeymapProgrammer::CODE`. -> -> Defaults to `kaleidoscope::EEPROMKeymapProgrammer::CODE`. - -## Focus commands - -The plugin provides a single `Focus` hook: `FOCUS_HOOK_KEYMAP_PROGRAMMER`, which -in turn provides the following command: - -### `keymap.toggleProgrammer` - -> Toggles the programmer mode on or off. - -## Dependencies - -* [Kaleidoscope-EEPROM-Keymap][plugin:eeprom-keymap] - - [plugin:eeprom-keymap]: https://github.com/keyboardio/Kaleidoscope-EEPROM-Keymap - -## Further reading - -Starting from the [example][plugin:example] is the recommended way of getting -started with the plugin. - - [plugin:example]: https://github.com/keyboardio/Kaleidoscope-EEPROM-Keymap-Programmer/blob/master/examples/EEPROM-Keymap-Programmer/EEPROM-Keymap-Programmer.ino +See [doc/plugin/EEPROM-Keymap-Programmer.md](doc/plugin/EEPROM-Keymap-Programmer.md) for documentation. diff --git a/doc/plugin/EEPROM-Keymap-Programmer.md b/doc/plugin/EEPROM-Keymap-Programmer.md new file mode 100644 index 00000000..3c00d43c --- /dev/null +++ b/doc/plugin/EEPROM-Keymap-Programmer.md @@ -0,0 +1,124 @@ +# Kaleidoscope-EEPROM-Keymap-Programmer + +Inspired by a similar feature on other keyboards, the `EEPROM-Keymap-Programmer` +plugin implements an on-device keymap re-arrangement / re-coding system. There +are two modes of operation: in one, we need to press a key we want to change, +then another to copy from. In the other, we press a key to change, and then +input a key code (terminated by any non-number key). + +## The two modes of operation + +It is worth looking at the two separately, to better understand how they work, +and what they accomplish: + +### Copy mode + +In `COPY` mode, the plugin will use both the built-in, default keymap, and the +override stored in `EEPROM`. When we select a key to override, we need to tap +another, which will be used as the source. The source key's code will be looked +up from the built-in keymap. For example, lets say we want to swap `A` and `B` +for some odd reason. We can do this by triggering the keymap programmer mode, +then tapping `A` to select it as the destination, then `B` as the source. The +plugin will look up the keycode in the built-in keymap for the key in `B`'s +location, and replace the location of `A` in the override with it. Next, we +press the `B` key to select it as the destination, and we press the key that +used to be `A` (but is now `B` too) to select it as a source. Because source +keys are looked up in the built-in keymap, the plugin will find it is `A`. + +Obviously, this method only works if we have a built-in keymap, and it does not +support copying from another layer. It is merely a way to rearrange simple +things, like alphanumerics. + +### Code mode + +In `CODE` mode, instead of selecting a source key, we need to enter a code: +press numbers to input the code, and any non-number key to end the sequence. +Thus, when entering keymap programmer mode, and selecting, say, the `A` key, +then tapping `5 SPACE` will set the key to `B` (which has the keycode of `5`). + +This allows us to use keycodes not present on the built-in keymap, at the +expense of having to know the keycode, and allowing no mistakes. + +## Using the plugin + +Adding the functionality of the plugin to a Sketch is easier the usage explained +above, though it requires that the [EEPROM-Keymap][plugin:eeprom-keymap] plugin +is also used, and set up appropriately. + +Once the prerequisites are dealt with, all we need to do is to use the plugin, +and find a way to trigger entering the keymap programmer mode. One such way is +to use a macro, as in the example below: + +```c++ +#include +#include +#include +#include +#include + +const macro_t *macroAction(uint8_t macroIndex, uint8_t keyState) { + if (macroIndex == 0 && keyToggledOff(keyState)) { + EEPROMKeymapProgrammer.activate(); + } + + return MACRO_NONE; +} + +KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings, + EEPROMKeymapProgrammer, + EEPROMKeymap, + Macros); + +void setup() { + Kaleidoscope.setup(); + + Layer.getKey = EEPROMKeymap.getKey; + + EEPROMKeymap.max_layers(1); + EEPROMSettings.seal(); +} +``` + +The plugin should be used as early as possible, otherwise other plugins that +hook into the event system may start processing events before the programmer can +take over. + +## Plugin methods + +The plugin provides the `EEPROMKeymapProgrammer` object, which has the following +methods and properties: + +### `.activate()` + +> Activates the keymap programmer. This is the function one needs to call from - +> say - a macro, to enter the edit state. + +### `.mode` + +> Set this property to the mode to use for editing: either +> `kaleidoscope::EEPROMKeymapProgrammer::COPY`, or +> `kaleidoscope::EEPROMKeymapProgrammer::CODE`. +> +> Defaults to `kaleidoscope::EEPROMKeymapProgrammer::CODE`. + +## Focus commands + +The plugin provides a single `Focus` hook: `FOCUS_HOOK_KEYMAP_PROGRAMMER`, which +in turn provides the following command: + +### `keymap.toggleProgrammer` + +> Toggles the programmer mode on or off. + +## Dependencies + +* [Kaleidoscope-EEPROM-Keymap][plugin:eeprom-keymap] + + [plugin:eeprom-keymap]: https://github.com/keyboardio/Kaleidoscope-EEPROM-Keymap + +## Further reading + +Starting from the [example][plugin:example] is the recommended way of getting +started with the plugin. + + [plugin:example]: https://github.com/keyboardio/Kaleidoscope-EEPROM-Keymap-Programmer/blob/master/examples/EEPROM-Keymap-Programmer/EEPROM-Keymap-Programmer.ino diff --git a/src/Kaleidoscope-EEPROM-Keymap-Programmer.h b/src/Kaleidoscope-EEPROM-Keymap-Programmer.h index 0b272bbe..d3df4f61 100644 --- a/src/Kaleidoscope-EEPROM-Keymap-Programmer.h +++ b/src/Kaleidoscope-EEPROM-Keymap-Programmer.h @@ -17,4 +17,4 @@ #pragma once -#include +#include diff --git a/src/Kaleidoscope/EEPROM-Keymap-Programmer.cpp b/src/kaleidoscope/plugin/EEPROM-Keymap-Programmer.cpp similarity index 97% rename from src/Kaleidoscope/EEPROM-Keymap-Programmer.cpp rename to src/kaleidoscope/plugin/EEPROM-Keymap-Programmer.cpp index 701ff483..956c6bb8 100644 --- a/src/Kaleidoscope/EEPROM-Keymap-Programmer.cpp +++ b/src/kaleidoscope/plugin/EEPROM-Keymap-Programmer.cpp @@ -19,6 +19,7 @@ #include namespace kaleidoscope { +namespace plugin { uint16_t EEPROMKeymapProgrammer::update_position_; EEPROMKeymapProgrammer::state_t EEPROMKeymapProgrammer::state_; EEPROMKeymapProgrammer::mode_t EEPROMKeymapProgrammer::mode; @@ -112,6 +113,7 @@ EventHandlerResult EEPROMKeymapProgrammer::onFocusEvent(const char *command) { return EventHandlerResult::EVENT_CONSUMED; } +} } -kaleidoscope::EEPROMKeymapProgrammer EEPROMKeymapProgrammer; +kaleidoscope::plugin::EEPROMKeymapProgrammer EEPROMKeymapProgrammer; diff --git a/src/Kaleidoscope/EEPROM-Keymap-Programmer.h b/src/kaleidoscope/plugin/EEPROM-Keymap-Programmer.h similarity index 93% rename from src/Kaleidoscope/EEPROM-Keymap-Programmer.h rename to src/kaleidoscope/plugin/EEPROM-Keymap-Programmer.h index dcc20cf0..14ba6c57 100644 --- a/src/Kaleidoscope/EEPROM-Keymap-Programmer.h +++ b/src/kaleidoscope/plugin/EEPROM-Keymap-Programmer.h @@ -21,6 +21,7 @@ #include namespace kaleidoscope { +namespace plugin { class EEPROMKeymapProgrammer : public kaleidoscope::Plugin { public: typedef enum { @@ -53,5 +54,6 @@ class EEPROMKeymapProgrammer : public kaleidoscope::Plugin { static Key new_key_; }; } +} -extern kaleidoscope::EEPROMKeymapProgrammer EEPROMKeymapProgrammer; +extern kaleidoscope::plugin::EEPROMKeymapProgrammer EEPROMKeymapProgrammer;