Move the documentation to `doc/plugin/Syster.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/389/head
Gergely Nagy
6 years ago
parent
e9542c28bd
commit
a0cabc6727
@ -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](https://github.com/keyboardio/Kaleidoscope-Ranges)
|
||||
|
||||
## 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-Syster/blob/master/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.
|
||||
Loading…
Reference in new issue