diff --git a/README.md b/README.md index a37cad77..19e6ea19 100644 --- a/README.md +++ b/README.md @@ -5,157 +5,4 @@ [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-SpaceCadet.svg?branch=master [travis:status]: https://travis-ci.org/keyboardio/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 -#include - -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 -#include - -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::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::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::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 +See [doc/plugin/SpaceCadet.md](doc/plugin/SpaceCadet.md) for documentation. diff --git a/doc/plugin/SpaceCadet.md b/doc/plugin/SpaceCadet.md new file mode 100644 index 00000000..cb8636d3 --- /dev/null +++ b/doc/plugin/SpaceCadet.md @@ -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 +#include + +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 +#include + +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. diff --git a/examples/SpaceCadet/SpaceCadet.ino b/examples/SpaceCadet/SpaceCadet.ino index 122ef8a8..bd0d7a34 100644 --- a/examples/SpaceCadet/SpaceCadet.ino +++ b/examples/SpaceCadet/SpaceCadet.ino @@ -48,7 +48,7 @@ void setup() { //Set the SpaceCadet map //Setting is {KeyThatWasPressed, AlternativeKeyToSend, TimeoutInMS} //Note: must end with the SPACECADET_MAP_END delimiter - static kaleidoscope::SpaceCadet::KeyBinding spacecadetmap[] = { + static kaleidoscope::plugin::SpaceCadet::KeyBinding spacecadetmap[] = { {Key_LeftShift, Key_LeftParen, 250} , {Key_RightShift, Key_RightParen, 250} , {Key_LeftGui, Key_LeftCurlyBracket, 250} diff --git a/src/Kaleidoscope-SpaceCadet.h b/src/Kaleidoscope-SpaceCadet.h index ad395b3e..197bdc37 100644 --- a/src/Kaleidoscope-SpaceCadet.h +++ b/src/Kaleidoscope-SpaceCadet.h @@ -17,4 +17,4 @@ #pragma once -#include +#include diff --git a/src/Kaleidoscope/SpaceCadet.cpp b/src/kaleidoscope/plugin/SpaceCadet.cpp similarity index 99% rename from src/Kaleidoscope/SpaceCadet.cpp rename to src/kaleidoscope/plugin/SpaceCadet.cpp index 34eedd52..f248fd3a 100644 --- a/src/Kaleidoscope/SpaceCadet.cpp +++ b/src/kaleidoscope/plugin/SpaceCadet.cpp @@ -19,6 +19,7 @@ #include namespace kaleidoscope { +namespace plugin { //Constructor with input and output, and assume default timeout SpaceCadet::KeyBinding::KeyBinding(Key input_, Key output_) { @@ -243,6 +244,7 @@ EventHandlerResult SpaceCadet::onKeyswitchEvent(Key &mapped_key, byte row, byte return EventHandlerResult::OK; } +} } -kaleidoscope::SpaceCadet SpaceCadet; +kaleidoscope::plugin::SpaceCadet SpaceCadet; diff --git a/src/Kaleidoscope/SpaceCadet.h b/src/kaleidoscope/plugin/SpaceCadet.h similarity index 93% rename from src/Kaleidoscope/SpaceCadet.h rename to src/kaleidoscope/plugin/SpaceCadet.h index 708c4cd7..a81ed954 100644 --- a/src/Kaleidoscope/SpaceCadet.h +++ b/src/kaleidoscope/plugin/SpaceCadet.h @@ -28,6 +28,7 @@ #define Key_SpaceCadetDisable (Key) { .raw = kaleidoscope::ranges::SC_LAST } namespace kaleidoscope { +namespace plugin { class SpaceCadet : public kaleidoscope::Plugin { public: @@ -69,6 +70,11 @@ class SpaceCadet : public kaleidoscope::Plugin { private: static bool disabled; }; -}; +} + +// Backwards compatibility +typedef plugin::SpaceCadet SpaceCadet; + +} -extern kaleidoscope::SpaceCadet SpaceCadet; +extern kaleidoscope::plugin::SpaceCadet SpaceCadet;