You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
103 lines
3.6 KiB
103 lines
3.6 KiB
8 years ago
|
# Akela-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
|
||
|
|
`Keyboardio.use()`, and then using any of the methods provided by the `Unicode`
|
||
|
|
singleton object.
|
||
|
|
|
||
|
|
```c++
|
||
|
|
#include <Akela-Unicode.h>
|
||
|
|
|
||
|
|
void setup (void) {
|
||
|
|
Keyboardio.setup (KEYMAP_SIZE);
|
||
|
|
Keyboardio.use (&Unicode, NULL);
|
||
|
|
|
||
|
|
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(codePoint)`
|
||
|
|
|
||
|
|
> Starts the Unicode input method using the [`.start()`](#start) method, inputs
|
||
|
|
> the `codePoint` 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(codePoint)`
|
||
|
|
|
||
|
|
> Inputs the hex codes for `codePoint`, 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(hexDigit)`
|
||
|
|
|
||
|
|
> 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 `Akela::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 `Akela::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 `Akela::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.
|
||
|
|
|
||
|
|
## Further reading
|
||
|
|
|
||
|
|
Starting from the [example][plugin:example] is the recommended way of getting
|
||
|
|
started with the plugin.
|
||
|
|
|
||
|
|
[plugin:example]: https://github.com/Akela-Plugins/Akela-Unicode/blob/master/examples/Unicode/Unicode.ino
|