Gergely Nagy
980c58da36
|
8 years ago | |
---|---|---|
examples/Unicode | 8 years ago | |
src | 8 years ago | |
.gitignore | 8 years ago | |
COPYING | 8 years ago | |
README.md | 8 years ago | |
library.properties | 8 years ago |
README.md
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.
#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, to add custom
functionality.
.type(codePoint)
Starts the Unicode input method using the
.start()
method, inputs thecodePoint
using.typeCode()
, and finishes up with the.end()
method. For each hexadecimal digit sent to the host, the.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()
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()
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()
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 is the recommended way of getting started with the plugin.