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 <algernon@keyboard.io>
pull/389/head
Gergely Nagy 6 years ago
parent 481fca0d4e
commit 06cbe188f5
No known key found for this signature in database
GPG Key ID: AC1E90BAC433F68F

@ -5,117 +5,4 @@
[travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-Unicode.svg?branch=master [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-Unicode.svg?branch=master
[travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-Unicode [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-Unicode
The `Unicode` extension makes it easier to write plugins that input Unicode See [doc/plugin/Unicode.md](doc/plugin/Unicode.md) for documentation.
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 <Kaleidoscope.h>
#include <Kaleidoscope-EEPROM-Settings.h>
#include <Kaleidoscope-HostOS.h>
#include <Kaleidoscope-Unicode.h>
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

@ -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 <Kaleidoscope.h>
#include <Kaleidoscope-EEPROM-Settings.h>
#include <Kaleidoscope-HostOS.h>
#include <Kaleidoscope-Unicode.h>
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

@ -17,4 +17,4 @@
#pragma once #pragma once
#include <Kaleidoscope/Unicode.h> #include <kaleidoscope/plugin/Unicode.h>

@ -19,6 +19,7 @@
#include "kaleidoscope/hid.h" #include "kaleidoscope/hid.h"
namespace kaleidoscope { namespace kaleidoscope {
namespace plugin {
void Unicode::start(void) { void Unicode::start(void) {
switch (::HostOS.os()) { switch (::HostOS.os()) {
@ -129,6 +130,7 @@ void Unicode::type(uint32_t unicode) {
end(); end();
} }
}
} }
__attribute__((weak)) Key hexToKey(uint8_t hex) { __attribute__((weak)) Key hexToKey(uint8_t hex) {
@ -188,4 +190,4 @@ __attribute__((weak)) void unicodeCustomEnd(void) {
__attribute__((weak)) void unicodeCustomInput(void) { __attribute__((weak)) void unicodeCustomInput(void) {
} }
kaleidoscope::Unicode Unicode; kaleidoscope::plugin::Unicode Unicode;

@ -21,6 +21,7 @@
#include <Kaleidoscope-HostOS.h> #include <Kaleidoscope-HostOS.h>
namespace kaleidoscope { namespace kaleidoscope {
namespace plugin {
class Unicode : public kaleidoscope::Plugin { class Unicode : public kaleidoscope::Plugin {
public: public:
Unicode(void) {} Unicode(void) {}
@ -33,6 +34,7 @@ class Unicode : public kaleidoscope::Plugin {
static void typeCode(uint32_t unicode); static void typeCode(uint32_t unicode);
}; };
} }
}
Key hexToKey(uint8_t hex); Key hexToKey(uint8_t hex);
Key hexToKeysWithNumpad(uint8_t hex); Key hexToKeysWithNumpad(uint8_t hex);
@ -41,4 +43,4 @@ void unicodeCustomStart(void);
void unicodeCustomEnd(void); void unicodeCustomEnd(void);
void unicodeCustomInput(void); void unicodeCustomInput(void);
extern kaleidoscope::Unicode Unicode; extern kaleidoscope::plugin::Unicode Unicode;
Loading…
Cancel
Save