diff --git a/README.md b/README.md index 20d15e8b..af84959e 100644 --- a/README.md +++ b/README.md @@ -5,98 +5,4 @@ [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-HostOS.svg?branch=master [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-HostOS -The `HostOS` extension is not all that useful in itself, rather, it is a -building block other plugins and extensions can use to not repeat the same -guesswork and logic. - -The goal is to have a single place that remembers the host OS, whether set by -the end-user in a Sketch, or via a macro, or some other way. This information -can then be reused by other plugins. - -See the [Unicode][plugin:unicode] extension for an example about how to use -`HostOS` in practice. - - [plugin:unicode]: https://github.com/keyboardio/Kaleidoscope-Unicode - -## Using the extension - -The extension provides a `HostOS` singleton object. - -```c++ -#include -#include -#include - -void someFunction(void) { - if (HostOS.os() == kaleidoscope::hostos::LINUX) { - // do something linux-y - } - if (HostOS.os() == kaleidoscope::hostos::OSX) { - // do something OSX-y - } -} - -KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings, HostOS) - -void setup(void) { - Kaleidoscope.setup (); -} -``` - -## Extension methods - -The extension provides the following methods on the `HostOS` singleton: - -### `.os()` - -> Returns the stored type of the Host OS. - -### `.os(type)` - -> Sets the type of the host OS, overriding any previous value. The type is then -> stored in EEPROM for persistence. - -## Host OS Values - -The OS type (i.e. the return type of `.os()` and the arguments to `.os(type)`) will be one of the following: - - - `kaleidoscope::hostos::LINUX` - - `kaleidoscope::hostos::OSX` - - `kaleidoscope::hostos::WINDOWS` - - `kaleidoscope::hostos::OTHER` - -## Focus commands - -The plugin provides the `FocusHostOSCommand` object, which, when enabled, -provides the `hostos.type` Focus command. - -### `hostos.type [type]` - -> Without argument, returns the current OS type set (a numeric value). -> -> With an argument, it sets the OS type. -> -> This command can be used from the host to reliably set the OS type within the firmware. - -## Dependencies - -* [Kaleidoscope-EEPROM-Settings](https://github.com/keyboardio/Kaleidoscope-EEPROM-Settings) - -## Further reading - -Starting from the [example][plugin:example] is the recommended way of getting -started with the extension. - - [plugin:example]: https://github.com/keyboardio/Kaleidoscope-HostOS/blob/master/examples/HostOS/HostOS.ino - -## Upgrading - -Prior versions of `HostOS` used to include a way to auto-detect the host -operating system. This code was brittle, unreliable, and rather big too. For -these reasons, this functionality was removed. The `autoDetect()` method is now -a no-op, and is deprecated. The `Kaleidoscope/HostOS-select.h` header is -similarly obsolete. Both of these produce deprecation messages now, and will be -removed by 2019-01-14. - -Furthermore, `HostOS` now depends on `Kaleidoscope-EEPROM-Settings`, that plugin -should be initialized first. +See [doc/plugin/HostOS.md](doc/plugin/HostOS.md) for documentation. diff --git a/doc/plugin/HostOS.md b/doc/plugin/HostOS.md new file mode 100644 index 00000000..47c3ae61 --- /dev/null +++ b/doc/plugin/HostOS.md @@ -0,0 +1,96 @@ +# Kaleidoscope-HostOS + +The `HostOS` extension is not all that useful in itself, rather, it is a +building block other plugins and extensions can use to not repeat the same +guesswork and logic. + +The goal is to have a single place that remembers the host OS, whether set by +the end-user in a Sketch, or via a macro, or some other way. This information +can then be reused by other plugins. + +See the [Unicode][plugin:unicode] extension for an example about how to use +`HostOS` in practice. + + [plugin:unicode]: https://github.com/keyboardio/Kaleidoscope-Unicode + +## Using the extension + +The extension provides a `HostOS` singleton object. + +```c++ +#include +#include + +void someFunction(void) { + if (HostOS.os() == kaleidoscope::hostos::LINUX) { + // do something linux-y + } + if (HostOS.os() == kaleidoscope::hostos::OSX) { + // do something OSX-y + } +} + +KALEIDOSCOPE_INIT_PLUGINS(HostOS) + +void setup(void) { + Kaleidoscope.setup (); +} +``` + +## Extension methods + +The extension provides the following methods on the `HostOS` singleton: + +### `.os()` + +> Returns the stored type of the Host OS. + +### `.os(type)` + +> Sets the type of the host OS, overriding any previous value. The type is then +> stored in EEPROM for persistence. + +## Host OS Values + +The OS type (i.e. the return type of `.os()` and the arguments to `.os(type)`) will be one of the following: + + - `kaleidoscope::hostos::LINUX` + - `kaleidoscope::hostos::OSX` + - `kaleidoscope::hostos::WINDOWS` + - `kaleidoscope::hostos::OTHER` + +## Focus commands + +The plugin provides the `FocusHostOSCommand` object, which, when enabled, +provides the `hostos.type` Focus command. + +### `hostos.type [type]` + +> Without argument, returns the current OS type set (a numeric value). +> +> With an argument, it sets the OS type. +> +> This command can be used from the host to reliably set the OS type within the firmware. + +## Dependencies + +* [Kaleidoscope-EEPROM-Settings](https://github.com/keyboardio/Kaleidoscope-EEPROM-Settings) + +## Further reading + +Starting from the [example][plugin:example] is the recommended way of getting +started with the extension. + + [plugin:example]: https://github.com/keyboardio/Kaleidoscope-HostOS/blob/master/examples/HostOS/HostOS.ino + +## Upgrading + +Prior versions of `HostOS` used to include a way to auto-detect the host +operating system. This code was brittle, unreliable, and rather big too. For +these reasons, this functionality was removed. The `autoDetect()` method is now +a no-op, and is deprecated. The `Kaleidoscope/HostOS-select.h` header is +similarly obsolete. Both of these produce deprecation messages now, and will be +removed by 2019-01-14. + +Furthermore, `HostOS` now depends on `Kaleidoscope-EEPROM-Settings`, that plugin +should be initialized first. diff --git a/src/Kaleidoscope-HostOS.h b/src/Kaleidoscope-HostOS.h index 2db78a77..0c483820 100644 --- a/src/Kaleidoscope-HostOS.h +++ b/src/Kaleidoscope-HostOS.h @@ -17,5 +17,5 @@ #pragma once -#include -#include +#include +#include diff --git a/src/Kaleidoscope/HostOS-Focus.cpp b/src/kaleidoscope/plugin/HostOS-Focus.cpp similarity index 94% rename from src/Kaleidoscope/HostOS-Focus.cpp rename to src/kaleidoscope/plugin/HostOS-Focus.cpp index 3b967499..222e1399 100644 --- a/src/Kaleidoscope/HostOS-Focus.cpp +++ b/src/kaleidoscope/plugin/HostOS-Focus.cpp @@ -19,6 +19,7 @@ #include namespace kaleidoscope { +namespace plugin { EventHandlerResult FocusHostOSCommand::onFocusEvent(const char *command) { const char *cmd = PSTR("hostos.type"); @@ -39,6 +40,7 @@ EventHandlerResult FocusHostOSCommand::onFocusEvent(const char *command) { return EventHandlerResult::EVENT_CONSUMED; } +} } -kaleidoscope::FocusHostOSCommand FocusHostOSCommand; +kaleidoscope::plugin::FocusHostOSCommand FocusHostOSCommand; diff --git a/src/Kaleidoscope/HostOS-Focus.h b/src/kaleidoscope/plugin/HostOS-Focus.h similarity index 91% rename from src/Kaleidoscope/HostOS-Focus.h rename to src/kaleidoscope/plugin/HostOS-Focus.h index 1d93752e..87a5f452 100644 --- a/src/Kaleidoscope/HostOS-Focus.h +++ b/src/kaleidoscope/plugin/HostOS-Focus.h @@ -20,13 +20,14 @@ #include namespace kaleidoscope { +namespace plugin { class FocusHostOSCommand : public kaleidoscope::Plugin { public: FocusHostOSCommand() {} EventHandlerResult onFocusEvent(const char *command); }; - +} } -extern kaleidoscope::FocusHostOSCommand FocusHostOSCommand; +extern kaleidoscope::plugin::FocusHostOSCommand FocusHostOSCommand; diff --git a/src/Kaleidoscope/HostOS.cpp b/src/kaleidoscope/plugin/HostOS.cpp similarity index 92% rename from src/Kaleidoscope/HostOS.cpp rename to src/kaleidoscope/plugin/HostOS.cpp index ac85faf1..d1d11206 100644 --- a/src/Kaleidoscope/HostOS.cpp +++ b/src/kaleidoscope/plugin/HostOS.cpp @@ -15,12 +15,13 @@ * this program. If not, see . */ -#include +#include #include #include namespace kaleidoscope { +namespace plugin { EventHandlerResult HostOS::onSetup(void) { if (is_configured_) @@ -44,6 +45,7 @@ void HostOS::os(hostos::Type new_os) { EEPROM.update(eeprom_slice_, os_); } +} } -kaleidoscope::HostOS HostOS; +kaleidoscope::plugin::HostOS HostOS; diff --git a/src/Kaleidoscope/HostOS.h b/src/kaleidoscope/plugin/HostOS.h similarity index 93% rename from src/Kaleidoscope/HostOS.h rename to src/kaleidoscope/plugin/HostOS.h index af592e95..0668b83e 100644 --- a/src/Kaleidoscope/HostOS.h +++ b/src/kaleidoscope/plugin/HostOS.h @@ -20,6 +20,7 @@ #include namespace kaleidoscope { +namespace plugin { namespace hostos { typedef enum { @@ -57,7 +58,9 @@ class HostOS : public kaleidoscope::Plugin { uint16_t eeprom_slice_; bool is_configured_ = false; }; +} +namespace hostos = plugin::hostos; } -extern kaleidoscope::HostOS HostOS; +extern kaleidoscope::plugin::HostOS HostOS;