Move the documentation to `doc/plugin/SpaceCadet.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
014f2d4ae9
commit
d610ca2d0c
@ -0,0 +1,164 @@
|
|||||||
|
# Kaleidoscope-SpaceCadet
|
||||||
|
|
||||||
|
[Space Cadet][space-cadet] is a way to make it more convenient to input
|
||||||
|
parens - those `(` and `)` things -, symbols that a lot of programming languages
|
||||||
|
use frequently. If you are working with Lisp, you are using these all the time.
|
||||||
|
|
||||||
|
What it does, is that it turns your left and right `Shift` keys into parens if
|
||||||
|
you tap and release them, without pressing any other key while holding them.
|
||||||
|
Therefore, to input, say, `(print foo)`, you don't need to press `Shift`, hold
|
||||||
|
it, and press `9` to get a `(`, you simply press and release `Shift`, and
|
||||||
|
continue writing. You use it as if you had a dedicated key for parens!
|
||||||
|
|
||||||
|
But if you wish to write capital letters, you hold it, as usual, and you will
|
||||||
|
not see any parens when you release it. You can also hold it for a longer time,
|
||||||
|
and it still would act as a `Shift`, without the parens inserted on release:
|
||||||
|
this is useful when you want to augment some mouse action with `Shift`, to
|
||||||
|
select text, for example.
|
||||||
|
|
||||||
|
After getting used to the Space Cadet style of typing, you may wish to enable
|
||||||
|
this sort of functionality on other keys, as well. Fortunately, the Space Cadet
|
||||||
|
plugin is configurable and extensible to support adding symbols to other keys.
|
||||||
|
Along with `(` on your left `Shift` key and `)` on your right `Shift` key,
|
||||||
|
you may wish to add other such programming mainstays as `{` to your left-side `cmd` key,
|
||||||
|
`}` to your right-side `alt` key, `[` to your left `Control` key, and `]` to your right
|
||||||
|
`Control` key. You can map the keys in whatever way you may wish to do, so feel free to
|
||||||
|
experiment with different combinations and discover what works best for you!
|
||||||
|
|
||||||
|
[space-cadet]: https://en.wikipedia.org/wiki/Space-cadet_keyboard
|
||||||
|
|
||||||
|
## Using the plugin
|
||||||
|
|
||||||
|
Using the plugin with its defaults is as simple as including the header, and
|
||||||
|
enabling the plugin:
|
||||||
|
|
||||||
|
```c++
|
||||||
|
#include <Kaleidoscope.h>
|
||||||
|
#include <Kaleidoscope-SpaceCadet.h>
|
||||||
|
|
||||||
|
KALEIDOSCOPE_INIT_PLUGINS(SpaceCadet);
|
||||||
|
|
||||||
|
void setup() {
|
||||||
|
Kaleidoscope.setup();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This assumes a US QWERTY layout on the host computer, though the plugin sends
|
||||||
|
the correct keymap code for each symbol. Because the mapping is entirely
|
||||||
|
configurable, though, you may switch out keys at your leisure.
|
||||||
|
|
||||||
|
If you wish to enable additional modifier keys (or disable the default behavior
|
||||||
|
for the shift and parentheses combinations), configuration is as simple as
|
||||||
|
passing a new keymap into the SpaceCadet object, as shown below:
|
||||||
|
|
||||||
|
|
||||||
|
```c++
|
||||||
|
#include <Kaleidoscope.h>
|
||||||
|
#include <Kaleidoscope-SpaceCadet.h>
|
||||||
|
|
||||||
|
KALEIDOSCOPE_INIT_PLUGINS(SpaceCadet);
|
||||||
|
|
||||||
|
void setup() {
|
||||||
|
Kaleidoscope.setup();
|
||||||
|
|
||||||
|
//Set the keymap with a 250ms timeout per-key
|
||||||
|
//Setting is {KeyThatWasPressed, AlternativeKeyToSend, TimeoutInMS}
|
||||||
|
//Note: must end with the SPACECADET_MAP_END delimiter
|
||||||
|
static kaleidoscope::plugin::SpaceCadet::KeyBinding spacecadetmap[] = {
|
||||||
|
{Key_LeftShift, Key_LeftParen, 250}
|
||||||
|
, {Key_RightShift, Key_RightParen, 250}
|
||||||
|
, {Key_LeftGui, Key_LeftCurlyBracket, 250}
|
||||||
|
, {Key_RightAlt, Key_RightCurlyBracket, 250}
|
||||||
|
, {Key_LeftAlt, Key_RightCurlyBracket, 250}
|
||||||
|
, {Key_LeftControl, Key_LeftBracket, 250}
|
||||||
|
, {Key_RightControl, Key_RightBracket, 250}
|
||||||
|
, SPACECADET_MAP_END
|
||||||
|
};
|
||||||
|
//Set the map.
|
||||||
|
SpaceCadet.map = spacecadetmap;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Plugin methods
|
||||||
|
|
||||||
|
The plugin provides the `SpaceCadet` object, with the following methods and
|
||||||
|
properties:
|
||||||
|
|
||||||
|
### `.map`
|
||||||
|
|
||||||
|
> Set the key map. This takes an array of
|
||||||
|
> `kaleidoscope::plugin::SpaceCadet::KeyBinding` objects with the special
|
||||||
|
> `SPACECADET_MAP_END` sentinal to mark the end of the map. Each KeyBinding
|
||||||
|
> object takes, in order, the key that was pressed, the key that should be sent
|
||||||
|
> instead, and an optional per-key timeout override
|
||||||
|
>
|
||||||
|
> If not explicitly set, defaults to mapping left `shift` to `(` and right `shift`
|
||||||
|
> to `)`.
|
||||||
|
|
||||||
|
### `kaleidoscope::plugin::SpaceCadet::KeyBinding`
|
||||||
|
|
||||||
|
> An object consisting of the key that is pressed, the key that should be sent
|
||||||
|
> in its place, and the timeout (in milliseconds) until the key press is
|
||||||
|
> considered to be a "held" key press. The third parameter, the timeout, is
|
||||||
|
> optional and may be set per-key or left out entirely (or set to `0`) to use
|
||||||
|
> the default timeout value.
|
||||||
|
|
||||||
|
### `.time_out`
|
||||||
|
|
||||||
|
> Set this property to the number of milliseconds to wait before considering a
|
||||||
|
> held key in isolation as its secondary role. That is, we'd have to hold a
|
||||||
|
> `Shift` key this long, by itself, to trigger the `Shift` role in itself. This
|
||||||
|
> timeout setting can be overridden by an individual key in the keymap, but if
|
||||||
|
> it is omitted or set to `0` in the key map, the global timeout will be used.
|
||||||
|
>
|
||||||
|
> Defaults to 1000.
|
||||||
|
|
||||||
|
### `.enable()`
|
||||||
|
|
||||||
|
> This method enables the SpaceCadet plugin. This is useful for interfacing
|
||||||
|
> with other plugins or macros, especially where SpaceCadet functionality isn't
|
||||||
|
> always desired.
|
||||||
|
>
|
||||||
|
> The default behavior is `enabled`.
|
||||||
|
|
||||||
|
### `.disable()`
|
||||||
|
|
||||||
|
> This method disables the SpaceCadet behavior. This is useful for interfacing
|
||||||
|
> with other plugins or macros, especially where SpaceCadet functionality isn't
|
||||||
|
> always desired.
|
||||||
|
|
||||||
|
### `.active()`
|
||||||
|
|
||||||
|
> This method returns `true` if SpaceCadet is enabled and `false` if SpaceCadet
|
||||||
|
> is disabled. This is useful for interfacing with other plugins or macros,
|
||||||
|
> especially where SpaceCadet functionality isn't always desired.
|
||||||
|
|
||||||
|
### `Key_SpaceCadetEnable`
|
||||||
|
|
||||||
|
> This provides a key for placing on a keymap for enabling the SpaceCadet
|
||||||
|
> behavior. This is only triggered on initial downpress, and does not
|
||||||
|
> trigger again if held down or when the key is released.
|
||||||
|
|
||||||
|
### `Key_SpaceCadetDisable`
|
||||||
|
|
||||||
|
> This provides a key for placing on a keymap for disabling the SpaceCadet
|
||||||
|
> behavior. This is only triggered on initial downpress, and does not
|
||||||
|
> trigger again if held down or when the key is released.
|
||||||
|
|
||||||
|
## 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-SpaceCadet/blob/master/examples/SpaceCadet/SpaceCadet.ino
|
||||||
|
|
||||||
|
## Upgrading
|
||||||
|
|
||||||
|
Previous versions of `SpaceCadet` used
|
||||||
|
`kaleidoscope::SpaceCadet::KeyBinding` as a type for defining keybindings. In newer versions, this is
|
||||||
|
`kaleidoscope::plugin::SpaceCadet::KeyBinding`. The old name still works,
|
||||||
|
but will be removed by 2019-01-14.
|
||||||
Loading…
Reference in new issue