Move the documentation to `doc/plugin/ShapeShifter.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^2
parent
104247fb24
commit
f478112e2d
@ -0,0 +1,69 @@
|
|||||||
|
# Kaleidoscope-ShapeShifter
|
||||||
|
|
||||||
|
`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 kaleidoscope::plugin::ShapeShifter::dictionary_t shape_shift_dictionary[] PROGMEM = {
|
||||||
|
{Key_1, Key_4},
|
||||||
|
{Key_4, Key_1},
|
||||||
|
{Key_NoKey, Key_NoKey},
|
||||||
|
};
|
||||||
|
|
||||||
|
KALEIDOSCOPE_INIT_PLUGINS(ShapeShifter);
|
||||||
|
|
||||||
|
void setup() {
|
||||||
|
Kaleidoscope.setup();
|
||||||
|
|
||||||
|
ShapeShifter.dictionary = shape_shift_dictionary;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
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 and
|
||||||
|
properties:
|
||||||
|
|
||||||
|
### `.dictionary`
|
||||||
|
|
||||||
|
> Set this property to the dictionary `ShapeShifter` should use. The dictionary
|
||||||
|
> is an array of `kaleidoscope::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!
|
||||||
|
|
||||||
|
## 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
|
||||||
|
|
||||||
|
## Upgrading
|
||||||
|
|
||||||
|
Previous versions of `ShapeShifter` used
|
||||||
|
`kaleidoscope::ShapeShifter::dictionary_t` as a type for defining the
|
||||||
|
dictionary. In newer versions, this is
|
||||||
|
`kaleidoscope::plugin::ShapeShifter::dictionary_t`. The old name still works,
|
||||||
|
but will be removed by 2019-01-14.
|
Loading…
Reference in new issue