alpha
/
Kaleidoscope
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Kaleidoscope Style Guide conformance

Browse Source 
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
pull/365/head
Gergely Nagy 7 years ago
parent 7da1fe702a
commit e8f3495f7c
4 changed files with 74 additions and 69 deletions
Show Stats Download Patch File Download Diff File

53
README.md
Unescape View File

@ -5,9 +5,9 @@
[travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-MagicCombo.svg?branch=master
[travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-MagicCombo
[st:stable]: https://img.shields.io/badge/stable-✔-black.png?style=flat&colorA=44cc11&colorB=494e52
[st:broken]: https://img.shields.io/badge/broken-X-black.png?style=flat&colorA=e05d44&colorB=494e52
[st:experimental]: https://img.shields.io/badge/experimental----black.png?style=flat&colorA=dfb317&colorB=494e52
[st:stable]: https://img.shields.io/badge/stable-✔-black.svg?style=flat&colorA=44cc11&colorB=494e52
[st:broken]: https://img.shields.io/badge/broken-X-black.svg?style=flat&colorA=e05d44&colorB=494e52
[st:experimental]: https://img.shields.io/badge/experimental----black.svg?style=flat&colorA=dfb317&colorB=494e52
The `MagicCombo` extension provides a way to perform custom actions when a
particular set of keys are held down together. The functionality assigned to
@ -18,54 +18,67 @@ This can be used to tie complex actions to key chords.
## Using the extension
To use the extension, we must include the header, create a dictionary, and
configure the plugin to use it:
To use the extension, we must include the header, create an array of combos we
want to work with, let the plugin know we want to work with those, and then use
a special function to handle the combos:
```c++
#include <Kaleidoscope.h>
#include <Kaleidoscope-MagicCombo.h>
static const KaleidoscopePlugins::MagicCombo::dictionary_t dictionary[] PROGMEM = {
static const KaleidoscopePlugins::MagicCombo::combo_t magic_combos[] PROGMEM = {
{R1C3 | R2C1 | R2C4 | R2C7, // left hand,
R0C11 | R1C12 | R2C14 //right hand
},
{0, 0}
};
void setup (void) {
MagicCombo.configure (dictionary);
void magicComboActions(uint8_t combo_index, uint32_t left_hand, uint32_t right_hand) {
switch (combo_index) {
case 0:
Serial.println("It's a kind of magic!");
break;
}
}
void setup() {
Serial.begin(9600);
USE_PLUGINS(&MagicCombo);
Kaleidoscope.setup (KEYMAP_SIZE);
Kaleidoscope.use (&MagicCombo, NULL);
Kaleidoscope.setup();
MagicCombo.magic_combos = magic_combos;
}
```
The dictionary **must** reside in `PROGMEM`, and is a list of tuples. Each
The combo list **must** reside in `PROGMEM`, and is a list of tuples. Each
element in the array has two fields: the left hand state, and the right hand
state upon which to trigger the custom action. Both of these are bit fields,
each bit set tells the extension that the key with that index must be held for
the action to trigger. It is recommended to use the `RxCy` macros of the core
`KaleidoscopeFirmware`, and *or* them together to form a bitfield.
The dictionary **must** end with an element containing zero values for both the
The combo list **must** end with an element containing zero values for both the
left and the right halves.
## Extension methods
The extension provides a `MagicCombo` singleton object, with the following method:
The extension provides a `MagicCombo` singleton object, with the following
methods and properties:
### `.configure(dictionary)`
### `.magic_combos`
> Configures the extension to use the supplied dictionary.
> Setting this property lets the plugin know which combinations of key presses
> we are interested in. If any of these are found active, the
> `magicComboActions()` function will be called.
### `.minInterval`
### `.min_interval`
> Restrict the magic action to fire at most once every `minInterval`
> milliseconds.
>
> Defaults to 500.
>
> Not strictly a method, it is a variable one can assign a new value to.
## Overrideable methods
@ -73,12 +86,12 @@ Whenever an combination is found to be held, the extension will trigger an
action, in each scan cycle until the keys remain held. This is done by calling
the overrideable `magicComboActions` function:
### `magicComboActions(comboIndex, leftHand, rightHand)`
### `magicComboActions(combo_index, left_hand, right_hand)`
> Called whenever a combination is found to be held. The function by default
> does nothing, and it is recommended to override it from within the Sketch.
>
> The first argument will be the index in the dictionary, the other two are the
> The first argument will be the index in the combo list, the other two are the
> key states on the left and right halves, respectively.
>
> Plugins that build upon this extensions *should not* override this function,

20
examples/MagicCombo/MagicCombo.ino
Unescape View File

@ -19,18 +19,18 @@
#include <Kaleidoscope.h>
#include <Kaleidoscope-MagicCombo.h>
void magicComboActions(uint8_t comboIndex, uint32_t leftHand, uint32_t rightHand) {
switch (comboIndex) {
void magicComboActions(uint8_t combo_index, uint32_t left_hand, uint32_t right_hand) {
switch (combo_index) {
case 0:
Serial.println("It's a kind of magic!");
break;
}
}
static const KaleidoscopePlugins::MagicCombo::dictionary_t dictionary[] PROGMEM = {
static const kaleidoscope::MagicCombo::combo_t magic_combos[] PROGMEM = {
{
R1C3 | R2C1 | R2C4 | R2C7, // left hand,
R0C11 | R1C12 | R2C14 //right hand
R1C3 | R2C1 | R2C4 | R2C7, // left hand,
R0C11 | R1C12 | R2C14 // right hand
},
{0, 0}
};
@ -53,17 +53,17 @@ const Key keymaps[][ROWS][COLS] PROGMEM = {
Key_skip, Key_N, Key_M, Key_Comma, Key_Period, Key_Slash, Key_Minus,
Key_RightShift, Key_RightAlt, Key_Spacebar, Key_RightControl,
Key_NoKey
),
Key_NoKey),
};
void setup() {
Serial.begin(9600);
MagicCombo.configure(dictionary);
USE_PLUGINS(&MagicCombo);
Kaleidoscope.setup(KEYMAP_SIZE);
Kaleidoscope.use(&MagicCombo, NULL);
Kaleidoscope.setup();
MagicCombo.magic_combos = magic_combos;
}
void loop() {

47
src/Kaleidoscope/MagicCombo.cpp
Unescape View File

@ -28,44 +28,37 @@
#define RIGHTHANDSTATE KeyboardHardware.scanner.rightHandState
#endif
namespace KaleidoscopePlugins {
namespace kaleidoscope {
const MagicCombo::dictionary_t *MagicCombo::dictionary;
uint16_t MagicCombo::minInterval = 500;
uint32_t MagicCombo::endTime;
const MagicCombo::combo_t *MagicCombo::magic_combos;
uint16_t MagicCombo::min_interval = 500;
uint32_t MagicCombo::end_time_;
MagicCombo::MagicCombo(void) {
}
void
MagicCombo::begin(void) {
loop_hook_use(this->loopHook);
void MagicCombo::begin(void) {
loop_hook_use(loopHook);
}
void
MagicCombo::configure(const MagicCombo::dictionary_t dictionary_[]) {
dictionary = (dictionary_t *)dictionary_;
}
void
MagicCombo::loopHook(bool postClear) {
if (!dictionary || postClear)
void MagicCombo::loopHook(bool is_post_clear) {
if (!magic_combos || is_post_clear)
return;
for (byte i = 0;; i++) {
dictionary_t combo;
combo_t combo;
combo.leftHand = pgm_read_dword(&(dictionary[i].leftHand));
combo.rightHand = pgm_read_dword(&(dictionary[i].rightHand));
combo.left_hand = pgm_read_dword(&(magic_combos[i].left_hand));
combo.right_hand = pgm_read_dword(&(magic_combos[i].right_hand));
if (combo.leftHand == 0 && combo.rightHand == 0)
if (combo.left_hand == 0 && combo.right_hand == 0)
break;
if (LEFTHANDSTATE.all == combo.leftHand &&
RIGHTHANDSTATE.all == combo.rightHand) {
if (millis() >= endTime) {
magicComboActions(i, combo.leftHand, combo.rightHand);
endTime = millis() + minInterval;
if (LEFTHANDSTATE.all == combo.left_hand &&
RIGHTHANDSTATE.all == combo.right_hand) {
if (millis() >= end_time_) {
magicComboActions(i, combo.left_hand, combo.right_hand);
end_time_ = millis() + min_interval;
}
break;
}
@ -74,9 +67,7 @@ MagicCombo::loopHook(bool postClear) {
};
__attribute__((weak))
void
magicComboActions(uint8_t comboIndex, uint32_t leftHand, uint32_t rightHand) {
__attribute__((weak)) void magicComboActions(uint8_t comboIndex, uint32_t left_hand, uint32_t right_hand) {
}
KaleidoscopePlugins::MagicCombo MagicCombo;
kaleidoscope::MagicCombo MagicCombo;

23
src/Kaleidoscope/MagicCombo.h
Unescape View File

@ -20,28 +20,29 @@
#include <Kaleidoscope.h>
namespace KaleidoscopePlugins {
namespace kaleidoscope {
class MagicCombo : public KaleidoscopePlugin {
public:
typedef struct {
uint32_t leftHand, rightHand;
} dictionary_t;
uint32_t left_hand, right_hand;
} combo_t;
MagicCombo(void);
void begin(void) final;
static void configure(const dictionary_t dictionary[]);
static uint16_t minInterval;
static const combo_t *magic_combos;
static uint16_t min_interval;
private:
static const dictionary_t *dictionary;
static uint32_t endTime;
static uint32_t end_time_;
static void loopHook(bool postClear);
};
static void loopHook(bool is_post_clear);
};
void magicComboActions(uint8_t comboIndex, uint32_t leftHand, uint32_t rightHand);
}
void magicComboActions(uint8_t combo_index, uint32_t left_hand, uint32_t right_hand);
extern KaleidoscopePlugins::MagicCombo MagicCombo;
extern kaleidoscope::MagicCombo MagicCombo;

Write Preview
Loading…
Cancel
Save