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

Merge remote-tracking branch 'plugin/Syster/f/monorepo' into f/monorepo-stage2

Browse Source
pull/389/head
Gergely Nagy 6 years ago
parent 54044b58d2 f5a4116fc3
commit 6dba0a7f68
No known key found for this signature in database
GPG Key ID: AC1E90BAC433F68F
5 changed files with 386 additions and 0 deletions
Show Stats Download Patch File Download Diff File

104
doc/plugin/Syster.md
Unescape View File

@ -0,0 +1,104 @@
# Kaleidoscope-Syster
Syster is a way to input symbols in a different way: instead of macros, Leader
sequences or the like, we trigger the special input mode, and enter the symbol's
name. Once finished, we hit `Space`, and this plugin will do the rest: delete
everything we typed, look up an action for the entered symbol, and execute that.
There are a number of ways this can be useful, but the easiest showcase is
symbolic Unicode input: `SYSTER coffee SPACE` turns into `☕`, with just a
little code.
## Using the plugin
To use the plugin, one needs to include the header and set up a function that
will handle the symbol actions:
```c++
#include <Kaleidoscope.h>
#include <Kaleidoscope-EEPROM-Settings.h>
#include <Kaleidoscope-HostOS.h>
#include <Kaleidoscope-Syster.h>
#include <Kaleidoscope-Unicode.h>
#include <kaleidoscope/hid.h>
void systerAction(kaleidoscope::plugin::Syster::action_t action, const char *symbol) {
switch (action) {
case kaleidoscope::plugin::Syster::StartAction:
Unicode.type (0x2328);
break;
case kaleidoscope::plugin::Syster::EndAction:
handleKeyswitchEvent (Key_Backspace, UNKNOWN_KEYSWITCH_LOCATION, IS_PRESSED | INJECTED);
kaleidoscope::hid::sendKeyboardReport ();
handleKeyswitchEvent (Key_Backspace, UNKNOWN_KEYSWITCH_LOCATION, WAS_PRESSED | INJECTED);
kaleidoscope::hid::sendKeyboardReport ();
break;
case kaleidoscope::plugin::Syster::SymbolAction:
Serial.print ("systerAction: symbol=");
Serial.println (symbol);
if (strcmp (symbol, "coffee") == 0) {
Unicode.type (0x2615);
}
break;
}
}
KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings, HostOS, Unicode, Syster);
void setup() {
Serial.begin(9600);
Kaleidoscope.setup ();
}
```
**Note** that we need to use the `Syster` object before any other that adds or
changes key behaviour! Failing to do so may result in unpredictable behaviour.
## Plugin methods
The plugin provides the `Syster` object, with no public methods. There are two
methods outside of the object, however, that can be overridden:
### `systerAction(action, symbol)`
> Called whenever an action needs to be taken, which can happen in three cases:
> First, when the `Syster` key is pressed and the alternate processing starts.
> In this case, `action` will be set to
> `kaleidoscope::plugin::Syster::StartAction`, and `symbol` will be `NULL`. This
> function can be used to do some setup to make it more obvious that the Syster
> input mode is active, such as sending a Unicode symbol to the host, or
> lighting up LEDs, or anything else we'd like.
>
> Second, when the sequence is finished with a `Space`. In this case, `action`
> will be set to `kaleidoscope::plugin::Syster::EndAction` and `symbol` will be
> `NULL`. This can be used to undo anything that the start action did, if need
> be.
>
> Third, when the action for the symbol should be made. In this case, `action`
> is set to `kaleidoscope::plugin::Syster::SymbolAction`, and `symbol` will be a
> C string. It is up to us, what we do with this information, how we handle it.
### `keyToChar(key)`
> A function that turns a keycode into a character. If using QWERTY on the host,
> the default implementation is sufficient. When using something else, you may
> have to reimplement this function.
## Dependencies
* [Kaleidoscope-Ranges](Ranges.md)
## Further reading
Starting from the [example][plugin:example] is the recommended way of getting
started with the plugin.
[plugin:example]: ../../examples/Syster/Syster.ino
## Upgrading
Previous versions of `Syster` used `kaleidoscope::Syster::action_t` as the type
of Syster actions. In newer versions, this is
`kaleidoscope::plugin::Syster::action_t`. The old name still works, but will be
removed by 2019-01-14.

79
examples/Syster/Syster.ino
Unescape View File

@ -0,0 +1,79 @@
/* -*- mode: c++ -*-
* Kaleidoscope-Syster -- Symbolic input system
* Copyright (C) 2017, 2018 Keyboard.io, Inc
*
* This program is free software: you can redistribute it and/or modify it under
* the terms of the GNU General Public License as published by the Free Software
* Foundation, version 3.
*
* This program is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
* FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
* details.
*
* You should have received a copy of the GNU General Public License along with
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
#include <Kaleidoscope.h>
#include <Kaleidoscope-EEPROM-Settings.h>
#include <Kaleidoscope-HostOS.h>
#include <Kaleidoscope-Syster.h>
#include <Kaleidoscope-Unicode.h>
#include <kaleidoscope/hid.h>
// *INDENT-OFF*
const Key keymaps[][ROWS][COLS] PROGMEM = {
[0] = KEYMAP_STACKED
(
Key_NoKey, Key_1, Key_2, Key_3, Key_4, Key_5, Key_NoKey,
Key_Backtick, Key_Q, Key_W, Key_E, Key_R, Key_T, Key_Tab,
Key_PageUp, Key_A, Key_S, Key_D, Key_F, Key_G,
Key_PageDown, Key_Z, Key_X, Key_C, Key_V, Key_B, Key_Escape,
Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift,
SYSTER,
Key_skip, Key_6, Key_7, Key_8, Key_9, Key_0, Key_skip,
Key_Enter, Key_Y, Key_U, Key_I, Key_O, Key_P, Key_Equals,
Key_H, Key_J, Key_K, Key_L, Key_Semicolon, Key_Quote,
Key_skip, Key_N, Key_M, Key_Comma, Key_Period, Key_Slash, Key_Minus,
Key_RightShift, Key_RightAlt, Key_Spacebar, Key_RightControl,
SYSTER),
};
// *INDENT-ON*
void systerAction(kaleidoscope::plugin::Syster::action_t action, const char *symbol) {
switch (action) {
case kaleidoscope::plugin::Syster::StartAction:
Unicode.type(0x2328);
break;
case kaleidoscope::plugin::Syster::EndAction:
handleKeyswitchEvent(Key_Backspace, UNKNOWN_KEYSWITCH_LOCATION, IS_PRESSED | INJECTED);
kaleidoscope::hid::sendKeyboardReport();
handleKeyswitchEvent(Key_Backspace, UNKNOWN_KEYSWITCH_LOCATION, WAS_PRESSED | INJECTED);
kaleidoscope::hid::sendKeyboardReport();
break;
case kaleidoscope::plugin::Syster::SymbolAction:
Serial.print("systerAction: symbol=");
Serial.println(symbol);
if (strcmp(symbol, "coffee") == 0) {
Unicode.type(0x2615);
}
break;
}
}
KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings,
HostOS,
Unicode,
Syster);
void setup() {
Kaleidoscope.setup();
}
void loop() {
Kaleidoscope.loop();
}

20
src/Kaleidoscope-Syster.h
Unescape View File

@ -0,0 +1,20 @@
/* -*- mode: c++ -*-
* Kaleidoscope-Syster -- Symbolic input system
* Copyright (C) 2016, 2017 Keyboard.io, Inc
*
* This program is free software: you can redistribute it and/or modify it under
* the terms of the GNU General Public License as published by the Free Software
* Foundation, version 3.
*
* This program is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
* FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
* details.
*
* You should have received a copy of the GNU General Public License along with
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
#pragma once
#include <kaleidoscope/plugin/Syster.h>

122
src/kaleidoscope/plugin/Syster.cpp
Unescape View File

@ -0,0 +1,122 @@
/* -*- mode: c++ -*-
* Kaleidoscope-Syster -- Symbolic input system
* Copyright (C) 2017, 2018 Keyboard.io, Inc
*
* This program is free software: you can redistribute it and/or modify it under
* the terms of the GNU General Public License as published by the Free Software
* Foundation, version 3.
*
* This program is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
* FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
* details.
*
* You should have received a copy of the GNU General Public License along with
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
#include <Kaleidoscope-Syster.h>
#include <kaleidoscope/hid.h>
#undef SYSTER
namespace kaleidoscope {
namespace plugin {
// --- state ---
char Syster::symbol_[SYSTER_MAX_SYMBOL_LENGTH + 1];
uint8_t Syster::symbol_pos_;
bool Syster::is_active_;
// --- helpers ---
#define isSyster(k) (k == kaleidoscope::ranges::SYSTER)
// --- api ---
void Syster::reset(void) {
symbol_pos_ = 0;
symbol_[0] = 0;
is_active_ = false;
}
bool Syster::is_active(void) {
return is_active_;
}
// --- hooks ---
EventHandlerResult Syster::onKeyswitchEvent(Key &mapped_key, byte row, byte col, uint8_t keyState) {
if (!is_active_) {
if (!isSyster(mapped_key))
return EventHandlerResult::OK;
if (keyToggledOn(keyState)) {
is_active_ = true;
systerAction(StartAction, NULL);
}
return EventHandlerResult::EVENT_CONSUMED;
}
if (keyState & INJECTED)
return EventHandlerResult::OK;
if (isSyster(mapped_key)) {
return EventHandlerResult::EVENT_CONSUMED;
}
if (mapped_key == Key_Backspace && symbol_pos_ == 0) {
return EventHandlerResult::EVENT_CONSUMED;
}
if (keyToggledOff(keyState)) {
if (mapped_key == Key_Spacebar) {
for (uint8_t i = 0; i <= symbol_pos_; i++) {
handleKeyswitchEvent(Key_Backspace, UNKNOWN_KEYSWITCH_LOCATION, IS_PRESSED | INJECTED);
hid::sendKeyboardReport();
handleKeyswitchEvent(Key_Backspace, UNKNOWN_KEYSWITCH_LOCATION, WAS_PRESSED | INJECTED);
hid::sendKeyboardReport();
}
systerAction(EndAction, NULL);
symbol_[symbol_pos_] = 0;
systerAction(SymbolAction, symbol_);
reset();
return EventHandlerResult::EVENT_CONSUMED;
}
}
if (keyToggledOn(keyState)) {
if (mapped_key == Key_Backspace) {
if (symbol_pos_ > 0)
symbol_pos_--;
} else {
const char c = keyToChar(mapped_key);
if (c)
symbol_[symbol_pos_++] = c;
}
}
return EventHandlerResult::OK;
}
}
}
__attribute__((weak)) const char keyToChar(Key key) {
if (key.flags != 0)
return 0;
switch (key.keyCode) {
case Key_A.keyCode ... Key_Z.keyCode:
return 'a' + (key.keyCode - Key_A.keyCode);
case Key_1.keyCode ... Key_0.keyCode:
return '1' + (key.keyCode - Key_1.keyCode);
}
return 0;
}
__attribute__((weak)) void systerAction(kaleidoscope::Syster::action_t action, const char *symbol) {
}
kaleidoscope::plugin::Syster Syster;

61
src/kaleidoscope/plugin/Syster.h
Unescape View File

@ -0,0 +1,61 @@
/* -*- mode: c++ -*-
* Kaleidoscope-Syster -- Symbolic input system
* Copyright (C) 2017, 2018 Keyboard.io, Inc
*
* This program is free software: you can redistribute it and/or modify it under
* the terms of the GNU General Public License as published by the Free Software
* Foundation, version 3.
*
* This program is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
* FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
* details.
*
* You should have received a copy of the GNU General Public License along with
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
#pragma once
#include <Kaleidoscope.h>
#include <Kaleidoscope-Ranges.h>
#define SYSTER_MAX_SYMBOL_LENGTH 32
#define SYSTER ((Key) { .raw = kaleidoscope::ranges::SYSTER })
namespace kaleidoscope {
namespace plugin {
class Syster : public kaleidoscope::Plugin {
public:
typedef enum {
StartAction,
EndAction,
SymbolAction
} action_t;
Syster(void) {}
static void reset(void);
bool is_active(void);
EventHandlerResult onKeyswitchEvent(Key &mapped_key, byte row, byte col, uint8_t keyState);
private:
static char symbol_[SYSTER_MAX_SYMBOL_LENGTH + 1];
static uint8_t symbol_pos_;
static bool is_active_;
};
}
// Backwards compatibility
typedef plugin::Syster Syster;
}
const char keyToChar(Key key);
void systerAction(kaleidoscope::plugin::Syster::action_t action, const char *symbol);
extern kaleidoscope::plugin::Syster Syster;
Write Preview
Loading…
Cancel
Save