Updated readme file

pull/389/head
Ben Gemperline 7 years ago
parent fff8179587
commit 6806fd9720

@ -9,7 +9,7 @@
[st:broken]: https://img.shields.io/badge/broken-X-black.svg?style=flat&colorA=e05d44&colorB=494e52
[st:experimental]: https://img.shields.io/badge/experimental----black.svg?style=flat&colorA=dfb317&colorB=494e52
[Space Cadet][space-cadet] Shift is a way to make it more convenient to input
[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.
@ -25,6 +25,15 @@ 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,
as well. Along with `(` on your left `Shift` key, you with to add other such
programming mainstays as `{` to your `cmd` key and `[` to your left `Control`
key (and, of course, the matching bookend symbols on the right). You can do
whatever you 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
@ -37,38 +46,74 @@ enabling the plugin:
#include <Kaleidoscope-SpaceCadet.h>
void setup() {
Kaleidoscope.use(&SpaceCadetShift);
Kaleidoscope.use(&SpaceCadet);
Kaleidoscope.setup();
}
```
This assumes a US QWERTY layout on the host computer, and will use the `9` and
`0` keys for the left and right parens, respectively. To change these keys, use
the `.opening_paren` and `.closing_paren` properties outlined below.
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>
## Plugin methods
void setup() {
Kaleidoscope.use(&SpaceCadet);
//Set the keymap
static kaleidoscope::ModifierKeyMap 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}
};
//Tell SpaceCadet to use the map
SpaceCadet.setMap(spacecadetmap, sizeof(spacecadetmap)/sizeof(spacecadetmap[0]));
The plugin provides the `SpaceCadetShift` object, with the following methods and
Kaleidoscope.setup();
}
```
## Plugin methods
The plugin provides the `SpaceCadet` object, with the following methods and
properties:
### `.opening_paren`
### `.setMap()`
> Set this property to the key that - when shifted - will result in an opening paren.
> Set the key map. Takes two arguments: the key map and the number of mappings
> in the map array. The key map is an array of `kaleidoscope::ModifierKeyMap`
> objects, and the size is by default set dynamically by the line
> `sizeof(spacecadetmap)/sizeof(spacecadetmap[0])`
>
> Defaults to `Key_9`.
> Defaults to mapping left `shift` to `(` and right `shift` to `)`.
### `.closing_paren`
### `kaleidoscope::ModifierKeyMap`
> Set this property to the key that - when shifted - will result in a closing paren.
>
> Defaults to `Key_0`.
> 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.
> `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.
@ -78,3 +123,7 @@ 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
or
[plugin:example]: https://github.com/advisoray/Kaleidoscope-SpaceCadet/blob/master/examples/SpaceCadet/SpaceCadet.ino

Loading…
Cancel
Save