Rearrange the file layout in preparation of becoming a monorepo

Move the documentation to `doc/plugin/MagicCombo.md`, sources under
`src/kaleidoscope/plugin/` (appropriately namespaced). This is in preparation of
merging plugins into a single monorepo.

Signed-off-by: Gergely Nagy <algernon@keyboard.io>
pull/365/head
Gergely Nagy 6 years ago
parent b95c4049c3
commit d3e7364ac7
No known key found for this signature in database
GPG Key ID: AC1E90BAC433F68F

@ -5,71 +5,4 @@
[travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-MagicCombo.svg?branch=master [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-MagicCombo.svg?branch=master
[travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-MagicCombo [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-MagicCombo
The `MagicCombo` extension provides a way to perform custom actions when a See [doc/plugin/MagicCombo.md](doc/plugin/MagicCombo.md) for documentation.
particular set of keys are held down together. The functionality assigned to
these keys are not changed, and the custom action triggers as long as all keys
within the set are pressed. The order in which they were pressed do not matter.
This can be used to tie complex actions to key chords.
## Using the extension
To use the extension, we must include the header, create actions for the magic
combos we want to trigger, and set up a mapping:
```c++
#include <Kaleidoscope.h>
#include <Kaleidoscope-Macros.h>
#include <Kaleidoscope-MagicCombo.h>
enum { KIND_OF_MAGIC };
void kindOfMagic(uint8_t combo_index) {
Macros.type(PSTR("It's a kind of magic!"));
}
USE_MAGIC_COMBOS(
[KIND_OF_MAGIC] = {
.action = kindOfMagic,
.keys = {R3C6, R3C9} // Left Fn + Right Fn
});
KALEIDOSCOPE_INIT_PLUGINS(MagicCombo, Macros);
void setup() {
Kaleidoscope.setup();
}
```
It is recommended to use the `RxCy` macros of the core firmware to set the keys
that are part of a combination.
## Plugin properties
The extension provides a `MagicCombo` singleton object, with the following
property:
### `.min_interval`
> Restrict the magic action to fire at most once every `min_interval`
> milliseconds.
>
> Defaults to 500.
## Plugin callbacks
Whenever a combination is found to be held, the plugin will trigger the
specified action, which is just a regular method with a single `uint8_t`
argument: the index of the magic combo. This function will be called repeatedly
(every `min_interval` milliseconds) while the combination is held.
## Further reading
Starting from the [example][plugin:example] is the recommended way of getting
started with the plugin.
`RxCy` coordinates for a Model01:
![rxcy layout](./docs/rc_layout.png)
[plugin:example]: https://github.com/keyboardio/Kaleidoscope-MagicCombo/blob/master/examples/MagicCombo/MagicCombo.ino

Before

Width:  |  Height:  |  Size: 89 KiB

After

Width:  |  Height:  |  Size: 89 KiB

@ -1,5 +1,75 @@
Breaking changes in `MagicCombo` # Kaleidoscope-MagicCombo
================================
The `MagicCombo` extension provides a way to perform custom actions when a
particular set of keys are held down together. The functionality assigned to
these keys are not changed, and the custom action triggers as long as all keys
within the set are pressed. The order in which they were pressed do not matter.
This can be used to tie complex actions to key chords.
## Using the extension
To use the extension, we must include the header, create actions for the magic
combos we want to trigger, and set up a mapping:
```c++
#include <Kaleidoscope.h>
#include <Kaleidoscope-Macros.h>
#include <Kaleidoscope-MagicCombo.h>
enum { KIND_OF_MAGIC };
void kindOfMagic(uint8_t combo_index) {
Macros.type(PSTR("It's a kind of magic!"));
}
USE_MAGIC_COMBOS(
[KIND_OF_MAGIC] = {
.action = kindOfMagic,
.keys = {R3C6, R3C9} // Left Fn + Right Fn
});
KALEIDOSCOPE_INIT_PLUGINS(MagicCombo, Macros);
void setup() {
Kaleidoscope.setup();
}
```
It is recommended to use the `RxCy` macros of the core firmware to set the keys
that are part of a combination.
## Plugin properties
The extension provides a `MagicCombo` singleton object, with the following
property:
### `.min_interval`
> Restrict the magic action to fire at most once every `min_interval`
> milliseconds.
>
> Defaults to 500.
## Plugin callbacks
Whenever a combination is found to be held, the plugin will trigger the
specified action, which is just a regular method with a single `uint8_t`
argument: the index of the magic combo. This function will be called repeatedly
(every `min_interval` milliseconds) while the combination is held.
## Further reading
Starting from the [example][plugin:example] is the recommended way of getting
started with the plugin.
`RxCy` coordinates for a Model01:
![rxcy layout](../model01_coordinates.png)
[plugin:example]: https://github.com/keyboardio/Kaleidoscope-MagicCombo/blob/master/examples/MagicCombo/MagicCombo.ino
## Upgrading
To make `MagicCombo` more portable, and easier to use, we had to break the API To make `MagicCombo` more portable, and easier to use, we had to break the API
previously provided, there was no way to maintain backwards compatibility. This previously provided, there was no way to maintain backwards compatibility. This

@ -17,4 +17,4 @@
#pragma once #pragma once
#include <Kaleidoscope/MagicCombo.h> #include <kaleidoscope/plugin/MagicCombo.h>

@ -18,6 +18,7 @@
#include <Kaleidoscope-MagicCombo.h> #include <Kaleidoscope-MagicCombo.h>
namespace kaleidoscope { namespace kaleidoscope {
namespace plugin {
uint16_t MagicCombo::min_interval = 500; uint16_t MagicCombo::min_interval = 500;
uint32_t MagicCombo::end_time_; uint32_t MagicCombo::end_time_;
@ -52,6 +53,7 @@ EventHandlerResult MagicCombo::beforeReportingState() {
return EventHandlerResult::OK; return EventHandlerResult::OK;
} }
}; }
}
kaleidoscope::MagicCombo MagicCombo; kaleidoscope::plugin::MagicCombo MagicCombo;

@ -23,11 +23,14 @@
#define USE_MAGIC_COMBOS(...) \ #define USE_MAGIC_COMBOS(...) \
namespace kaleidoscope { \ namespace kaleidoscope { \
namespace plugin { \
namespace magiccombo { \ namespace magiccombo { \
const kaleidoscope::MagicCombo::Combo combos[] PROGMEM = {__VA_ARGS__}; \ const kaleidoscope::plugin::MagicCombo::Combo combos[] PROGMEM = \
{__VA_ARGS__}; \
\ \
const uint8_t combos_length = sizeof(combos) / sizeof(*combos); \ const uint8_t combos_length = sizeof(combos) / sizeof(*combos); \
} \ } \
} \
} }
#define _MAGICCOMBO_API_CHANGE \ #define _MAGICCOMBO_API_CHANGE \
@ -38,6 +41,7 @@
" https://github.com/keyboardio/Kaleidoscope-MagicCombo/blob/master/UPGRADING.md" " https://github.com/keyboardio/Kaleidoscope-MagicCombo/blob/master/UPGRADING.md"
namespace kaleidoscope { namespace kaleidoscope {
namespace plugin {
class MagicCombo : public kaleidoscope::Plugin { class MagicCombo : public kaleidoscope::Plugin {
public: public:
@ -73,4 +77,8 @@ extern const uint8_t combos_length;
} }
extern kaleidoscope::MagicCombo MagicCombo; // Backward compatibility
typedef plugin::MagicCombo MagicCombo;
}
extern kaleidoscope::plugin::MagicCombo MagicCombo;
Loading…
Cancel
Save