You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
77 lines
2.8 KiB
77 lines
2.8 KiB
# Kaleidoscope-ShapeShifter
|
|
|
|
![status][st:stable]
|
|
|
|
[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
|
|
|
|
`ShapeShifter` is a plugin that makes it considerably easier to change what
|
|
symbol is input when a key is pressed together with `Shift`. If one wants to
|
|
rearrange the symbols on the number row for example, without modifying the
|
|
layout on the operating system side, this plugin is where one can turn to.
|
|
|
|
What it does, is very simple: if any key in its dictionary is found pressed
|
|
while `Shift` is held, it will press another key instead of the one triggering
|
|
the event. For example, if it sees `Shift + 1` pressed together, which normally
|
|
results in a `!`, it will press `4` instead of `1`, inputting `$`.
|
|
|
|
## Using the plugin
|
|
|
|
To use the plugin, one needs to include the header, create a dictionary, and
|
|
configure the provided `ShapeShifter` object to use the dictionary:
|
|
|
|
```c++
|
|
#include <Kaleidoscope.h>
|
|
#include <Kaleidoscope-ShapeShifter.h>
|
|
|
|
static const KaleidoscopePlugins::ShapeShifter::dictionary_t shapeShiftDictionary[] PROGMEM = {
|
|
{Key_1, Key_4},
|
|
{Key_4, Key_1},
|
|
{Key_NoKey, Key_NoKey},
|
|
};
|
|
|
|
void setup () {
|
|
ShapeShifter.configure (shapeShiftDictionary);
|
|
|
|
Kaleidoscope.setup (KEYMAP_SIZE);
|
|
Kaleidoscope.use (&ShapeShifter, NULL);
|
|
}
|
|
```
|
|
|
|
The dictionary is made up of `Key` pairs: the first one is to replace, the
|
|
second is the replacement. The dictionary must be closed with a `{Key_NoKey,
|
|
Key_NoKey}` pair, and **must** reside in `PROGMEM`.
|
|
|
|
## Plugin methods
|
|
|
|
The plugin provides the `ShapeShifter` object, with the following methods:
|
|
|
|
### `.configure(dictionary)`
|
|
|
|
> Tells `ShapeShifter` to use the specified dictionary. The dictionary is an
|
|
> array of `KaleidoscopePlugins::ShapeShifter::dictionary_t` elements, which is
|
|
> just a very verbose way of saying that its a pair of keys. The first one is
|
|
> the one to replace, and the other is to replace it with.
|
|
>
|
|
> Be aware that the replacement key will be pressed with `Shift` held, so do
|
|
> keep that in mind!
|
|
|
|
### `.on()`
|
|
|
|
> Turns the shape shifting functionality on. Requires that the plugin
|
|
> be [configured](#configuredictionary) first.
|
|
|
|
### `.off()`
|
|
|
|
> Turns the shape shifting functionality off. In this case, no transformations
|
|
> will be applied, and even if symbols appear in the dictionary, they will be
|
|
> ignored until the plugin is turned back on.
|
|
|
|
## 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-ShapeShifter/blob/master/examples/ShapeShifter/ShapeShifter.ino
|