From 06cbe188f598a8566af4018934a200a744520306 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Sat, 13 Oct 2018 15:36:55 +0200 Subject: [PATCH] Rearrange the file layout in preparation of becoming a monorepo Move the documentation to `doc/plugin/Unicode.md`, sources under `src/kaleidoscope/plugin/` (appropriately namespaced). This is in preparation of merging plugins into a single monorepo. Signed-off-by: Gergely Nagy --- README.md | 115 +---------------- doc/plugin/Unicode.md | 116 ++++++++++++++++++ src/Kaleidoscope-Unicode.h | 2 +- .../plugin}/Unicode.cpp | 4 +- .../plugin}/Unicode.h | 4 +- 5 files changed, 124 insertions(+), 117 deletions(-) create mode 100644 doc/plugin/Unicode.md rename src/{Kaleidoscope => kaleidoscope/plugin}/Unicode.cpp (98%) rename src/{Kaleidoscope => kaleidoscope/plugin}/Unicode.h (94%) diff --git a/README.md b/README.md index 9f676895..da331dfd 100644 --- a/README.md +++ b/README.md @@ -5,117 +5,4 @@ [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-Unicode.svg?branch=master [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-Unicode -The `Unicode` extension makes it easier to write plugins that input Unicode -symbols on the host. Because inputting Unicode varies from OS to OS, this helper -library was made to hide most of the differences. All one has to do, is set up -the `HostOS` singleton properly, and the `Unicode` library will handle the rest, -by providing an easy interface for inputting Unicode symbols by their 32-bit -codepoints. - -## Using the extension - -Using the extension is as simple as including the header, registering it with -`Kaleidoscope.use()`, and then using any of the methods provided by the -`Unicode` singleton object. - -```c++ -#include -#include -#include -#include - -KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings, HostOS, Unicode); - -void setup() { - Kaleidoscope.setup(); - - Unicode.type(0x2328); -} -``` - -## Extension methods - -The extension provides a number of methods on the `Unicode` object, but also has -symbols that can be [overridden](#overrideable-methods), to add custom -functionality. - -### `.type(code_point)` - -> Starts the Unicode input method using the [`.start()`](#start) method, inputs -> the `code_point` using [`.typeCode()`](#typeCode), and finishes up with -> the [`.end()`](#end) method. For each hexadecimal digit sent to the host, -> the [`.input()`](#input) method will also be called. -> -> This method is most useful when one knows the code point of the Unicode symbol -> to enter ahead of time, when the code point does not depend on anything else. - -### `.typeCode(code_point)` - -> Inputs the hex codes for `code_point`, and the hex codes only. Use when the -> input method is to be started and ended separately. -> -> For example, a macro that starts Unicode input, and switches to a layer full -> of macros that send the hex codes is one scenario where this function is of -> use. - -### `.start()` - -> Starts the Unicode input method. The way it starts it, depends on the host -> operating system. - -### `.input()` - -> If the host operating system requires keys being held during the Unicode -> input, this function will hold them for us. - -### `.end()` - -> Finishes the Unicode input method, in an OS-specific way. - -## Overrideable methods - -### `hexToKey(hex_digit)` - -> A function that returns a `Key` struct, given a 8-bit hex digit. For most -> uses, the built-in version of this function is sufficient, but if the keymap -> on the OS-side has any of the hexadecimal symbols on other scancodes than -> QWERTY, this function should be overridden to use the correct scan codes. - -### `unicodeCustomStart()` - -> If the host OS type is set to `kaleidoscope::hostos::Custom`, then this function will -> be called whenever the [`.start()`](#start) method is called. The default -> implementation does nothing, and should be overridden to implement the custom -> magic needed to enter unicode input mode. - -### `unicodeCustomInput()` - -> If the host OS type is set to `kaleidoscope::hostos::Custom`, then this function will -> be called whenever the [`.input()`](#input) method is called. The default -> implementation does nothing, and should be overridden to implement the custom -> magic needed while inputting the hex code itself (such as holding additional -> keys). - -### `unicodeCustomEnd()` - -> If the host OS type is set to `kaleidoscope::hostos::Custom`, then this function will -> be called whenever the [`.end()`](#end) method is called. The default -> implementation does nothing, and should be overridden to implement the custom -> magic needed to leave unicode input mode. - -## Dependencies - -* [Kaleidoscope-HostOS](https://github.com/keyboardio/Kaleidoscope-HostOS) - -## Other Configuration - -On OS X/macOS, you'll need to change the input method to be "Unicode Hex Input". -You can do this by going to System Preferences > Keyboard > Input Sources, clicking -the `+` button, selecting it from the list, then setting it as the active input method. - -## 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-Unicode/blob/master/examples/Unicode/Unicode.ino +See [doc/plugin/Unicode.md](doc/plugin/Unicode.md) for documentation. diff --git a/doc/plugin/Unicode.md b/doc/plugin/Unicode.md new file mode 100644 index 00000000..fec9ccf1 --- /dev/null +++ b/doc/plugin/Unicode.md @@ -0,0 +1,116 @@ +# Kaleidoscope-Unicode + +The `Unicode` extension makes it easier to write plugins that input Unicode +symbols on the host. Because inputting Unicode varies from OS to OS, this helper +library was made to hide most of the differences. All one has to do, is set up +the `HostOS` singleton properly, and the `Unicode` library will handle the rest, +by providing an easy interface for inputting Unicode symbols by their 32-bit +codepoints. + +## Using the extension + +Using the extension is as simple as including the header, registering it with +`Kaleidoscope.use()`, and then using any of the methods provided by the +`Unicode` singleton object. + +```c++ +#include +#include +#include +#include + +KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings, HostOS, Unicode); + +void setup() { + Kaleidoscope.setup(); + + Unicode.type(0x2328); +} +``` + +## Extension methods + +The extension provides a number of methods on the `Unicode` object, but also has +symbols that can be [overridden](#overrideable-methods), to add custom +functionality. + +### `.type(code_point)` + +> Starts the Unicode input method using the [`.start()`](#start) method, inputs +> the `code_point` using [`.typeCode()`](#typeCode), and finishes up with +> the [`.end()`](#end) method. For each hexadecimal digit sent to the host, +> the [`.input()`](#input) method will also be called. +> +> This method is most useful when one knows the code point of the Unicode symbol +> to enter ahead of time, when the code point does not depend on anything else. + +### `.typeCode(code_point)` + +> Inputs the hex codes for `code_point`, and the hex codes only. Use when the +> input method is to be started and ended separately. +> +> For example, a macro that starts Unicode input, and switches to a layer full +> of macros that send the hex codes is one scenario where this function is of +> use. + +### `.start()` + +> Starts the Unicode input method. The way it starts it, depends on the host +> operating system. + +### `.input()` + +> If the host operating system requires keys being held during the Unicode +> input, this function will hold them for us. + +### `.end()` + +> Finishes the Unicode input method, in an OS-specific way. + +## Overrideable methods + +### `hexToKey(hex_digit)` + +> A function that returns a `Key` struct, given a 8-bit hex digit. For most +> uses, the built-in version of this function is sufficient, but if the keymap +> on the OS-side has any of the hexadecimal symbols on other scancodes than +> QWERTY, this function should be overridden to use the correct scan codes. + +### `unicodeCustomStart()` + +> If the host OS type is set to `kaleidoscope::hostos::Custom`, then this function will +> be called whenever the [`.start()`](#start) method is called. The default +> implementation does nothing, and should be overridden to implement the custom +> magic needed to enter unicode input mode. + +### `unicodeCustomInput()` + +> If the host OS type is set to `kaleidoscope::hostos::Custom`, then this function will +> be called whenever the [`.input()`](#input) method is called. The default +> implementation does nothing, and should be overridden to implement the custom +> magic needed while inputting the hex code itself (such as holding additional +> keys). + +### `unicodeCustomEnd()` + +> If the host OS type is set to `kaleidoscope::hostos::Custom`, then this function will +> be called whenever the [`.end()`](#end) method is called. The default +> implementation does nothing, and should be overridden to implement the custom +> magic needed to leave unicode input mode. + +## Dependencies + +* [Kaleidoscope-HostOS](https://github.com/keyboardio/Kaleidoscope-HostOS) + +## Other Configuration + +On OS X/macOS, you'll need to change the input method to be "Unicode Hex Input". +You can do this by going to System Preferences > Keyboard > Input Sources, clicking +the `+` button, selecting it from the list, then setting it as the active input method. + +## 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-Unicode/blob/master/examples/Unicode/Unicode.ino diff --git a/src/Kaleidoscope-Unicode.h b/src/Kaleidoscope-Unicode.h index 17a90ec5..83c71138 100644 --- a/src/Kaleidoscope-Unicode.h +++ b/src/Kaleidoscope-Unicode.h @@ -17,4 +17,4 @@ #pragma once -#include +#include diff --git a/src/Kaleidoscope/Unicode.cpp b/src/kaleidoscope/plugin/Unicode.cpp similarity index 98% rename from src/Kaleidoscope/Unicode.cpp rename to src/kaleidoscope/plugin/Unicode.cpp index ceb0d75e..c79bc8e2 100644 --- a/src/Kaleidoscope/Unicode.cpp +++ b/src/kaleidoscope/plugin/Unicode.cpp @@ -19,6 +19,7 @@ #include "kaleidoscope/hid.h" namespace kaleidoscope { +namespace plugin { void Unicode::start(void) { switch (::HostOS.os()) { @@ -129,6 +130,7 @@ void Unicode::type(uint32_t unicode) { end(); } +} } __attribute__((weak)) Key hexToKey(uint8_t hex) { @@ -188,4 +190,4 @@ __attribute__((weak)) void unicodeCustomEnd(void) { __attribute__((weak)) void unicodeCustomInput(void) { } -kaleidoscope::Unicode Unicode; +kaleidoscope::plugin::Unicode Unicode; diff --git a/src/Kaleidoscope/Unicode.h b/src/kaleidoscope/plugin/Unicode.h similarity index 94% rename from src/Kaleidoscope/Unicode.h rename to src/kaleidoscope/plugin/Unicode.h index dac67393..49a94be0 100644 --- a/src/Kaleidoscope/Unicode.h +++ b/src/kaleidoscope/plugin/Unicode.h @@ -21,6 +21,7 @@ #include namespace kaleidoscope { +namespace plugin { class Unicode : public kaleidoscope::Plugin { public: Unicode(void) {} @@ -33,6 +34,7 @@ class Unicode : public kaleidoscope::Plugin { static void typeCode(uint32_t unicode); }; } +} Key hexToKey(uint8_t hex); Key hexToKeysWithNumpad(uint8_t hex); @@ -41,4 +43,4 @@ void unicodeCustomStart(void); void unicodeCustomEnd(void); void unicodeCustomInput(void); -extern kaleidoscope::Unicode Unicode; +extern kaleidoscope::plugin::Unicode Unicode;