From c78531dbc017f89a796e3123776eda75e8bd6252 Mon Sep 17 00:00:00 2001 From: Marc Durdin Date: Mon, 4 May 2026 17:35:20 +0200 Subject: [PATCH] refactor(core): clean up API documentation Move all Keyman Core header API documentation to javadoc-style so that we can get inline documentation and simplify the readability of the header files. Update api-header-extractor to support minimal javadoc formatting of the comments. Test-bot: skip --- core/docs/api/actions.md | 225 ++ core/docs/api/background.md | 307 +-- core/docs/api/building.md | 24 +- core/docs/api/changes.md | 29 +- core/docs/api/context.md | 389 ++++ core/docs/api/index.md | 24 +- core/docs/api/keyboards.md | 640 +++--- core/docs/api/keyhandling.md | 69 +- core/docs/api/options.md | 184 +- core/docs/api/processor.md | 169 +- core/docs/api/state.md | 225 +- core/docs/api/virtual-keys.md | 386 ++++ core/include/keyman/keyman_core_api.h | 2034 +++++++---------- core/include/keyman/keyman_core_api_actions.h | 170 +- core/include/keyman/keyman_core_api_context.h | 495 ++-- core/include/keyman/keyman_core_api_debug.h | 59 +- core/include/keyman/keyman_core_api_vkeys.h | 55 +- core/tools/api-header-extractor/build.sh | 10 +- .../api-header-extractor/package-lock.json | 30 + core/tools/api-header-extractor/package.json | 5 +- core/tools/api-header-extractor/src/index.ts | 236 +- core/tools/api-header-extractor/tsconfig.json | 1 + 22 files changed, 3177 insertions(+), 2589 deletions(-) create mode 100644 core/docs/api/actions.md create mode 100644 core/docs/api/context.md create mode 100644 core/docs/api/virtual-keys.md create mode 100644 core/tools/api-header-extractor/package-lock.json diff --git a/core/docs/api/actions.md b/core/docs/api/actions.md new file mode 100644 index 0000000000..11f24a9009 --- /dev/null +++ b/core/docs/api/actions.md @@ -0,0 +1,225 @@ +--- +title: Actions - Keyman Core API (internal) +--- + +As of version 17.0, Actions APIs are now available only to the keyboard +debugger, IMX, and Core unit tests. Do not use these APIs for other cases. +Instead, use [km_core_state_get_actions]. + +typedef struct { + uint8_t expected_type; // km_core_backspace_type + uintptr_t expected_value; // used mainly in unit tests +} km_core_backspace_item; + +enum km_core_backspace_type { + KM_CORE_BT_UNKNOWN = 0, // Used at beginning of context; user-initiated backspace + KM_CORE_BT_CHAR = 1, // Deleting a character prior to insertion point + KM_CORE_BT_MARKER = 2, // Deleting a marker prior to insertion point + KM_CORE_BT_MAX_TYPE_ID +}; + + +# km_core_action_item struct {#km_core_action_item} + +This provides the results of processing a key event to the Platform layer and +should be processed by the Platform layer to issue commands to the os text +services framework to transform the text store in the Client Application, among +other actions. + +This struct is deprecated; instead use [km_core_actions]. + +```c +typedef struct { + uint8_t type; + uint8_t _reserved[sizeof(void*)-sizeof(uint8_t)]; + union { + uint32_t marker; // MARKER type + km_core_option_item const * option; // OPT types + km_core_usv character; // CHAR type + uint8_t capsLock; // CAPSLOCK type, 1 to turn on, 0 to turn off; re name see #9833 + km_core_backspace_item backspace; // BACKSPACE type + }; +} km_core_action_item; +enum km_core_action_type { + KM_CORE_IT_END = 0, // Marks end of action items list. + KM_CORE_IT_CHAR = 1, // A Unicode character has been generated. + KM_CORE_IT_MARKER = 2, // Correlates to kmn's "deadkey" markers. + KM_CORE_IT_ALERT = 3, // The keyboard has triggered a alert/beep/bell. + KM_CORE_IT_BACK = 4, // Delete the codepoint preceding the insertion point. + KM_CORE_IT_PERSIST_OPT = 5, // The indicated option needs to be stored. + KM_CORE_IT_EMIT_KEYSTROKE = 6, // Emit the current keystroke to the application + KM_CORE_IT_INVALIDATE_CONTEXT = 7, + KM_CORE_IT_CAPSLOCK = 8, // Enable or disable capsLock + KM_CORE_IT_MAX_TYPE_ID +}; +``` + +# km_core_state_action_items function {#km_core_state_action_items} + +Get the list of action items generated by the last call to +`km_core_process_event`. + + +## Parameters + +### state +A pointer to the opaque `km_core_state` object to be +queried. + +### num_items +A pointer to a result variable: The number of items in the +action item list including the `KM_CORE_IT_END` +terminator. May be null if not that information is +required. + +## Returns +A pointer to a `km_core_action_item` list, of `*num_items` in +length. This data becomes invalid when the state object is +destroyed, or after a call to `km_core_process_event`. Do not +modify the contents of this data. The returned array is terminated +with a `KM_CORE_IT_END` entry. + +```c +KMN_API +km_core_action_item const * +km_core_state_action_items( + km_core_state const *state, + size_t *num_items +); +``` + +# km_core_state_queue_action_items function {#km_core_state_queue_action_items} + +Queue actions for the current keyboard processor state; normally +used in IMX callbacks called during `km_core_process_event`. + + +## Parameters + +### state +A pointer to the opaque `km_core_state` object to be +queried. + +### action_items +The action items to be added to the core queue. Must be +terminated with a `KM_CORE_IT_END` entry. + +## Returns +One of the following values: + +`KM_CORE_STATUS_OK` +: On success. + +`KM_CORE_STATUS_INVALID_ARGUMENT` +: In the event the `state` or `action_items` pointer are null. + +```c +KMN_API +km_core_status +km_core_state_queue_action_items( + km_core_state *state, + km_core_action_item const *action_items +); +``` + +# km_core_process_queued_actions function {#km_core_process_queued_actions} + +Process the keyboard processors queued actions for the opaque state object. +Updates the state object as appropriate and fills out its action list. +The client can add actions externally via the +`km_core_state_queue_action_items` and then request the processing of the +actions with this method. + +The state action list will be cleared at the start of this call; options and context in +the state may also be modified. + + +## Parameters + +### state +A pointer to the opaque state object. + +## Returns +One of the following values: + +`KM_CORE_STATUS_OK` +: On success. + +`KM_CORE_STATUS_NO_MEM` +: In the event memory is unavailable to allocate internal buffers. + +`KM_CORE_STATUS_INVALID_ARGUMENT` +: In the event the `state` pointer is null + +```c +KMN_API +km_core_status +km_core_process_queued_actions( + km_core_state *state +); +/* + +[km_core_cu]: background#km_core_cu "km_core_cu type" +[km_core_usv]: background#km_core_usv "km_core_usv type" +[km_core_virtual_key]: background#km_core_virtual_key "km_core_virtual_key type" +[km_core_status]: background#km_core_status "km_core_status type" +[km_core_keyboard]: background#km_core_keyboard "km_core_keyboard struct" +[km_core_state]: background#km_core_state "km_core_state struct" +[km_core_options]: background#km_core_options "km_core_options struct" +[km_core_keyboard_imx_platform]: background#km_core_keyboard_imx_platform "km_core_keyboard_imx_platform callback function" +[km_core_status_codes]: background#km_core_status_codes "km_core_status_codes enum" +[km_core_attr]: background#km_core_attr "km_core_attr struct" +[km_core_tech_value]: background#km_core_tech_value "km_core_tech_value enum" +[km_core_get_engine_attrs]: background#km_core_get_engine_attrs "km_core_get_engine_attrs function" +[km_core_bool]: background#km_core_bool "km_core_bool enum" +[km_core_caps_state]: state#km_core_caps_state "km_core_caps_state enum" +[km_core_actions]: state#km_core_actions "km_core_actions struct" +[km_core_state_get_actions]: state#km_core_state_get_actions "km_core_state_get_actions function" +[km_core_context_status]: state#km_core_context_status "km_core_context_status enum" +[km_core_state_context_set_if_needed]: state#km_core_state_context_set_if_needed "km_core_state_context_set_if_needed function" +[km_core_state_context_clear]: state#km_core_state_context_clear "km_core_state_context_clear function" +[km_core_option_scope]: options#km_core_option_scope "km_core_option_scope enum" +[km_core_option_item]: options#km_core_option_item "km_core_option_item struct" +[km_core_options_list_size]: options#km_core_options_list_size "km_core_options_list_size function" +[km_core_state_option_lookup]: options#km_core_state_option_lookup "km_core_state_option_lookup function" +[km_core_state_options_update]: options#km_core_state_options_update "km_core_state_options_update function" +[km_core_keyboard_attrs]: keyboards#km_core_keyboard_attrs "km_core_keyboard_attrs struct" +[km_core_keyboard_key]: keyboards#km_core_keyboard_key "km_core_keyboard_key struct" +[km_core_keyboard_imx]: keyboards#km_core_keyboard_imx "km_core_keyboard_imx struct" +[km_core_keyboard_load_from_blob]: keyboards#km_core_keyboard_load_from_blob "km_core_keyboard_load_from_blob function" +[km_core_keyboard_dispose]: keyboards#km_core_keyboard_dispose "km_core_keyboard_dispose function" +[km_core_keyboard_get_attrs]: keyboards#km_core_keyboard_get_attrs "km_core_keyboard_get_attrs function" +[km_core_keyboard_get_key_list]: keyboards#km_core_keyboard_get_key_list "km_core_keyboard_get_key_list function" +[km_core_keyboard_key_list_dispose]: keyboards#km_core_keyboard_key_list_dispose "km_core_keyboard_key_list_dispose function" +[km_core_keyboard_get_imx_list]: keyboards#km_core_keyboard_get_imx_list "km_core_keyboard_get_imx_list function" +[km_core_keyboard_imx_list_dispose]: keyboards#km_core_keyboard_imx_list_dispose "km_core_keyboard_imx_list_dispose function" +[km_core_state_imx_register_callback]: keyboards#km_core_state_imx_register_callback "km_core_state_imx_register_callback function" +[km_core_state_imx_deregister_callback]: keyboards#km_core_state_imx_deregister_callback "km_core_state_imx_deregister_callback function" +[km_core_state_create]: keyboards#km_core_state_create "km_core_state_create function" +[km_core_state_clone]: keyboards#km_core_state_clone "km_core_state_clone function" +[km_core_state_dispose]: keyboards#km_core_state_dispose "km_core_state_dispose function" +[km_core_debug_context_type]: keyboards#km_core_debug_context_type "km_core_debug_context_type enum" +[km_core_state_context_debug]: keyboards#km_core_state_context_debug "km_core_state_context_debug function" +[km_core_cu_dispose]: keyboards#km_core_cu_dispose "km_core_cu_dispose function" +[km_core_event_flags]: processor#km_core_event_flags "km_core_event_flags enum" +[km_core_process_event]: processor#km_core_process_event "km_core_process_event function" +[km_core_event]: processor#km_core_event "km_core_event function" +[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" +[km_core_action_item]: actions#km_core_action_item "km_core_action_item struct" +[km_core_state_action_items]: actions#km_core_state_action_items "km_core_state_action_items function" +[km_core_state_queue_action_items]: actions#km_core_state_queue_action_items "km_core_state_queue_action_items function" +[km_core_process_queued_actions]: actions#km_core_process_queued_actions "km_core_process_queued_actions function" +[km_core_context_type]: context#km_core_context_type "km_core_context_type enum" +[km_core_context_item]: context#km_core_context_item "km_core_context_item struct" +[KM_CORE_CONTEXT_ITEM_END]: context#KM_CORE_CONTEXT_ITEM_END "KM_CORE_CONTEXT_ITEM_END macro" +[km_core_state_get_intermediate_context]: context#km_core_state_get_intermediate_context "km_core_state_get_intermediate_context function" +[km_core_context_items_dispose]: context#km_core_context_items_dispose "km_core_context_items_dispose function" +[km_core_state_context]: context#km_core_state_context "km_core_state_context function" +[km_core_state_app_context]: context#km_core_state_app_context "km_core_state_app_context function" +[km_core_context_set]: context#km_core_context_set "km_core_context_set function" +[km_core_context_clear]: context#km_core_context_clear "km_core_context_clear function" +[km_core_context_item_list_size]: context#km_core_context_item_list_size "km_core_context_item_list_size function" +[km_core_context_get]: context#km_core_context_get "km_core_context_get function" +[km_core_context_length]: context#km_core_context_length "km_core_context_length function" +[km_core_modifier_state]: virtual-keys#km_core_modifier_state "km_core_modifier_state enum" +[km_core_virtual_key_value]: virtual-keys#km_core_virtual_key_value "km_core_virtual_key_value " \ No newline at end of file diff --git a/core/docs/api/background.md b/core/docs/api/background.md index 72a9918814..363d41d4fd 100644 --- a/core/docs/api/background.md +++ b/core/docs/api/background.md @@ -81,302 +81,205 @@ interface. ------------------------------------------------------------------------------- -# Common functions, types, and macros -## Basic types - -Fundamental types for representing data passed across the API. - -### km_core_cu type {#km_core_cu} - -`uint16_t/char16_t` +# km_core_cu type {#km_core_cu} Represents a UTF16 codepoint, most strings are passed as UTF16. -### km_core_usv type {#km_core_usv} +```c +typedef uint16_t/char16_t km_core_cu; +``` -`uint32_t/char32_t` +```c +``` -An integral type capable of holding a single Unicode Scalar Value, a decoded UTF -codepoint. +# km_core_usv type {#km_core_usv} -### km_core_virtual_key type {#km_core_virtual_key} +An integral type capable of holding a single Unicode Scalar Value, a decoded +UTF codepoint. -`uint16_t` +```c +typedef uint32_t/char32_t km_core_usv; +``` + +```c +``` + +# km_core_virtual_key type {#km_core_virtual_key} An integral type capable of holding a platform specific virtual key code. -### km_core_status type {#km_core_status} +```c +typedef uint16_t km_core_virtual_key; +``` -`uint32_t` +# km_core_status type {#km_core_status} -An integral 32 bit wide type capable of holding any valid status code as defined -by the `enum` [km_core_status_codes]. +An integral 32 bit wide type capable of holding any valid status code as +defined by the `enum` [km_core_status_codes]. -### km_core_modifier_state type {#km_core_modifier_state} +```c +typedef uint32_t km_core_status; +``` -`uint16_t` - -An integral type bitmask representing the state of each modifier key. - - - -## Resource types - -Opaque types for representing resources provided or created by the keyboard -processor implementation. - -### km_core_keyboard struct {#km_core_keyboard} +# km_core_keyboard struct {#km_core_keyboard} Represents a keyboard loaded from disk, that can be executed by the keyboard -processor to consume events, update state associated with an insertion point and -produce action items. A keyboard object may be referenced by any number of state -objects but must be disposed of after all state objects referencing it have -first been disposed of. +processor to consume events, update state associated with an insertion point +and produce action items. A keyboard object may be referenced by any number +of state objects but must be disposed of after all state objects referencing +it have first been disposed of. -### km_core_state struct {#km_core_state} +```c +typedef struct km_core_keyboard km_core_keyboard; +``` -Represents all state associated with an insertion point using a keyboard. This -tracks context, and current action items resulting from a processed keyboard -event. There can be many state objects using the same keyboard. A state object -may not live longer than the keyboard it manages state for. +# km_core_state struct {#km_core_state} -### km_core_options struct {#km_core_options} +Represents all state associated with an insertion point using a keyboard. +This tracks context, and current action items resulting from a processed +keyboard event. There can be many state objects using the same keyboard. A +state object may not live longer than the keyboard it manages state for. + +```c +typedef struct km_core_state km_core_state; +``` + +# km_core_options struct {#km_core_options} Represents a set of option items for environmental state and keyboard state. - - - - -------------------------------------------------------------------------------- +# km_core_keyboard_imx_platform callback function {#km_core_keyboard_imx_platform} + +Callback function used to to access Input Method eXtension library functions +from Keyman Core + +```c +typedef uint8_t (*km_core_keyboard_imx_platform)(km_core_state*, uint32_t, void*); +``` # km_core_status_codes enum {#km_core_status_codes} -## Description - -An error code mechanism similar to COM’s `HRESULT` scheme (unlike COM, any +An error code mechanism similar to COM's `HRESULT` scheme (unlike COM, any non-zero value is an error). -## Specification - ```c enum km_core_status_codes { + /** Success code. Call completed as documented. */ KM_CORE_STATUS_OK = 0, + /** The call failed to allocate memory during its execution, causing it to fail. */ KM_CORE_STATUS_NO_MEM = 1, + /** The call performed an I/O operation which failed, causing it to fail. */ KM_CORE_STATUS_IO_ERROR = 2, + /** The call detected one of its parameters was invalid or unsafe. */ KM_CORE_STATUS_INVALID_ARGUMENT = 3, + /** The provided key or index into a collection object was not present. */ KM_CORE_STATUS_KEY_ERROR = 4, + /** The provided buffer did not contain enough space to fully encode or copy + * the result of this call. */ KM_CORE_STATUS_INSUFFICENT_BUFFER = 5, + /** A malformed or partial UTF sequence prevented complete decoding of a + * unicode string. */ KM_CORE_STATUS_INVALID_UTF = 6, + /** An attempt to decode a keyboard file failed. */ KM_CORE_STATUS_INVALID_KEYBOARD = 7, KM_CORE_STATUS_NOT_IMPLEMENTED = 8, + /** This allows encapsulating a platform error code: the remaining 31 low bits + * are the error code returned by the OS for cases where the failure mode is + * platform specific. For HRESULT codes this only permits failure codes to be + * passed and not success codes. */ KM_CORE_STATUS_OS_ERROR = 0x80000000 }; - ``` -## Values - -`KM_CORE_STATUS_OK` - -: Success code. Call completed as documented. - -`KM_CORE_STATUS_NO_MEM` - -: The call failed to allocate memory during its execution, causing it to fail. - -`KM_CORE_STATUS_IO_ERROR` - -: The call performed an I/O operation which failed, causing it to fail. - -`KM_CORE_STATUS_INVALID_ARGUMENT` - -: The call detected one of its parameters was invalid or unsafe. - -`KM_CORE_STATUS_KEY_ERROR` - -: The provided key or index into a collection object was not present. - -`KM_CORE_STATUS_INSUFFICENT_BUFFER` - -: The provided buffer did not contain enough space to fully encode or copy the -result of this call. - -`KM_CORE_STATUS_INVALID_UTF` - -: A malformed or partial UTF sequence prevented complete decoding of a unicode -string. - -`KM_CORE_STATUS_INVALID_KEYBOARD` - -: An attempt to decode a keyboard file failed. - -`KM_CORE_STATUS_OS_ERROR` - -: This allows encapsulating a platform error code: the remaining 31 low bits are -the error code returned by the OS for cases where the failure mode is platform -specific. For HRESULT codes this only permits failure codes to be passed and not -success codes. - -------------------------------------------------------------------------------- - # km_core_attr struct {#km_core_attr} -## Description - A structure describing information about Keyman Core implementing this API. -## Specification - ```c - typedef struct { + /** Maximum context size supported by processor in code points. */ size_t max_context; + /** Current API number supported. */ uint16_t current; + /** Implementation number of current API. */ uint16_t revision; + /** current - age == Oldest API number supported. */ uint16_t age; + /** A bit field of [km_core_tech_value] values, specifiying which Keyboard + * technologies the engine supports. */ uint16_t technology; + /** A UTF-8 encoded string identifying the implementer of the processor. */ char const *vendor; } km_core_attr; - ``` -## Members - -`max_context` -: Maximum context size supported by processor. - -`current` -: Current API number supported. - -`revision` -: Implementation number of current API. - -`age` -: current - age == Oldest API number supported. - -`technology` -: A bit field of [km_core_tech_value] values, -specifiying which Keyboard technologies the engine supports. - -`vendor` -: A UTF-8 encoded string identifying the implementer of the processor. - -------------------------------------------------------------------------------- # km_core_tech_value enum {#km_core_tech_value} -## Description - Values for a bit field indicating which keyboarding technologies a keyboard processor supports. -## Specification - ```c - enum km_core_tech_value { + /** The keyboard processor implementation does not disclose which technologies + * it implements. */ KM_CORE_TECH_UNSPECIFIED = 0, + /** The keyboard processor implements a simple en-US keyboard for the purposes + * of testing the API. */ KM_CORE_TECH_MOCK = 1 << 0, + /** The keyboard processor implements a Keyman KMX compatible engine. */ KM_CORE_TECH_KMX = 1 << 1, + /** The keyboard processor implements a LDML capable processing engine. */ KM_CORE_TECH_LDML = 1 << 2 }; - ``` -## Values -`KM_CORE_TECH_UNSPECIFIED` -: The keyboard processor implementation does not disclose which technologies it -implements. +# km_core_get_engine_attrs function {#km_core_get_engine_attrs} -`KM_CORE_TECH_MOCK` -: The keyboard processor implements a simple en-US keyboard for the purposes of -testing the API. +Get access processors attributes describing version and technology +implemented. -`KM_CORE_TECH_UNSPECIFIED` -: The keyboard processor implements a Keyman KMX compatible engine. -`KM_CORE_TECH_UNSPECIFIED` -: The keyboard processor implements a LDML capable processing engine. +## Parameters -------------------------------------------------------------------------------- +### state +An opaque pointer to a [km_core_state]. -# km_core_get_engine_attrs() {#km_core_get_engine_attrs} -## Description - -Get access processors attributes describing version and technology implemented. - -## Specification +## Returns +A pointer to a [km_core_attr] structure. Do not modify the contents +of this structure. ```c KMN_API km_core_attr const * -km_core_get_engine_attrs(km_core_state const *state); - +km_core_get_engine_attrs( + km_core_state const *state +); ``` -## Parameters - -`state` -: An opaque pointer to a [km_core_state]. - -## Returns -A pointer to a [km_core_attr] structure. Do not modify the contents of this -structure. - -------------------------------------------------------------------------------- - # km_core_bool enum {#km_core_bool} -## Description - Defines a boolean state. -## Specification ```c typedef enum { KM_CORE_FALSE = 0, KM_CORE_TRUE = 1 } km_core_bool; - ``` -------------------------------------------------------------------------------- - [km_core_cu]: background#km_core_cu "km_core_cu type" [km_core_usv]: background#km_core_usv "km_core_usv type" [km_core_virtual_key]: background#km_core_virtual_key "km_core_virtual_key type" [km_core_status]: background#km_core_status "km_core_status type" -[km_core_modifier_state]: background#km_core_modifier_state "km_core_modifier_state type" [km_core_keyboard]: background#km_core_keyboard "km_core_keyboard struct" [km_core_state]: background#km_core_state "km_core_state struct" [km_core_options]: background#km_core_options "km_core_options struct" +[km_core_keyboard_imx_platform]: background#km_core_keyboard_imx_platform "km_core_keyboard_imx_platform callback function" [km_core_status_codes]: background#km_core_status_codes "km_core_status_codes enum" [km_core_attr]: background#km_core_attr "km_core_attr struct" [km_core_tech_value]: background#km_core_tech_value "km_core_tech_value enum" @@ -391,6 +294,7 @@ typedef enum { KM_CORE_FALSE = 0, KM_CORE_TRUE = 1 } km_core_bool; [km_core_option_scope]: options#km_core_option_scope "km_core_option_scope enum" [km_core_option_item]: options#km_core_option_item "km_core_option_item struct" [km_core_options_list_size]: options#km_core_options_list_size "km_core_options_list_size function" +[km_core_state_option_lookup]: options#km_core_state_option_lookup "km_core_state_option_lookup function" [km_core_state_options_update]: options#km_core_state_options_update "km_core_state_options_update function" [km_core_keyboard_attrs]: keyboards#km_core_keyboard_attrs "km_core_keyboard_attrs struct" [km_core_keyboard_key]: keyboards#km_core_keyboard_key "km_core_keyboard_key struct" @@ -400,6 +304,7 @@ typedef enum { KM_CORE_FALSE = 0, KM_CORE_TRUE = 1 } km_core_bool; [km_core_keyboard_get_attrs]: keyboards#km_core_keyboard_get_attrs "km_core_keyboard_get_attrs function" [km_core_keyboard_get_key_list]: keyboards#km_core_keyboard_get_key_list "km_core_keyboard_get_key_list function" [km_core_keyboard_key_list_dispose]: keyboards#km_core_keyboard_key_list_dispose "km_core_keyboard_key_list_dispose function" +[km_core_keyboard_get_imx_list]: keyboards#km_core_keyboard_get_imx_list "km_core_keyboard_get_imx_list function" [km_core_keyboard_imx_list_dispose]: keyboards#km_core_keyboard_imx_list_dispose "km_core_keyboard_imx_list_dispose function" [km_core_state_imx_register_callback]: keyboards#km_core_state_imx_register_callback "km_core_state_imx_register_callback function" [km_core_state_imx_deregister_callback]: keyboards#km_core_state_imx_deregister_callback "km_core_state_imx_deregister_callback function" @@ -412,4 +317,22 @@ typedef enum { KM_CORE_FALSE = 0, KM_CORE_TRUE = 1 } km_core_bool; [km_core_event_flags]: processor#km_core_event_flags "km_core_event_flags enum" [km_core_process_event]: processor#km_core_process_event "km_core_process_event function" [km_core_event]: processor#km_core_event "km_core_event function" -[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" \ No newline at end of file +[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" +[km_core_action_item]: actions#km_core_action_item "km_core_action_item struct" +[km_core_state_action_items]: actions#km_core_state_action_items "km_core_state_action_items function" +[km_core_state_queue_action_items]: actions#km_core_state_queue_action_items "km_core_state_queue_action_items function" +[km_core_process_queued_actions]: actions#km_core_process_queued_actions "km_core_process_queued_actions function" +[km_core_context_type]: context#km_core_context_type "km_core_context_type enum" +[km_core_context_item]: context#km_core_context_item "km_core_context_item struct" +[KM_CORE_CONTEXT_ITEM_END]: context#KM_CORE_CONTEXT_ITEM_END "KM_CORE_CONTEXT_ITEM_END macro" +[km_core_state_get_intermediate_context]: context#km_core_state_get_intermediate_context "km_core_state_get_intermediate_context function" +[km_core_context_items_dispose]: context#km_core_context_items_dispose "km_core_context_items_dispose function" +[km_core_state_context]: context#km_core_state_context "km_core_state_context function" +[km_core_state_app_context]: context#km_core_state_app_context "km_core_state_app_context function" +[km_core_context_set]: context#km_core_context_set "km_core_context_set function" +[km_core_context_clear]: context#km_core_context_clear "km_core_context_clear function" +[km_core_context_item_list_size]: context#km_core_context_item_list_size "km_core_context_item_list_size function" +[km_core_context_get]: context#km_core_context_get "km_core_context_get function" +[km_core_context_length]: context#km_core_context_length "km_core_context_length function" +[km_core_modifier_state]: virtual-keys#km_core_modifier_state "km_core_modifier_state enum" +[km_core_virtual_key_value]: virtual-keys#km_core_virtual_key_value "km_core_virtual_key_value " \ No newline at end of file diff --git a/core/docs/api/building.md b/core/docs/api/building.md index 5a67ab686b..f42cbf3e85 100644 --- a/core/docs/api/building.md +++ b/core/docs/api/building.md @@ -67,10 +67,10 @@ Install kmc from the NPM package. [km_core_usv]: background#km_core_usv "km_core_usv type" [km_core_virtual_key]: background#km_core_virtual_key "km_core_virtual_key type" [km_core_status]: background#km_core_status "km_core_status type" -[km_core_modifier_state]: background#km_core_modifier_state "km_core_modifier_state type" [km_core_keyboard]: background#km_core_keyboard "km_core_keyboard struct" [km_core_state]: background#km_core_state "km_core_state struct" [km_core_options]: background#km_core_options "km_core_options struct" +[km_core_keyboard_imx_platform]: background#km_core_keyboard_imx_platform "km_core_keyboard_imx_platform callback function" [km_core_status_codes]: background#km_core_status_codes "km_core_status_codes enum" [km_core_attr]: background#km_core_attr "km_core_attr struct" [km_core_tech_value]: background#km_core_tech_value "km_core_tech_value enum" @@ -85,6 +85,7 @@ Install kmc from the NPM package. [km_core_option_scope]: options#km_core_option_scope "km_core_option_scope enum" [km_core_option_item]: options#km_core_option_item "km_core_option_item struct" [km_core_options_list_size]: options#km_core_options_list_size "km_core_options_list_size function" +[km_core_state_option_lookup]: options#km_core_state_option_lookup "km_core_state_option_lookup function" [km_core_state_options_update]: options#km_core_state_options_update "km_core_state_options_update function" [km_core_keyboard_attrs]: keyboards#km_core_keyboard_attrs "km_core_keyboard_attrs struct" [km_core_keyboard_key]: keyboards#km_core_keyboard_key "km_core_keyboard_key struct" @@ -94,6 +95,7 @@ Install kmc from the NPM package. [km_core_keyboard_get_attrs]: keyboards#km_core_keyboard_get_attrs "km_core_keyboard_get_attrs function" [km_core_keyboard_get_key_list]: keyboards#km_core_keyboard_get_key_list "km_core_keyboard_get_key_list function" [km_core_keyboard_key_list_dispose]: keyboards#km_core_keyboard_key_list_dispose "km_core_keyboard_key_list_dispose function" +[km_core_keyboard_get_imx_list]: keyboards#km_core_keyboard_get_imx_list "km_core_keyboard_get_imx_list function" [km_core_keyboard_imx_list_dispose]: keyboards#km_core_keyboard_imx_list_dispose "km_core_keyboard_imx_list_dispose function" [km_core_state_imx_register_callback]: keyboards#km_core_state_imx_register_callback "km_core_state_imx_register_callback function" [km_core_state_imx_deregister_callback]: keyboards#km_core_state_imx_deregister_callback "km_core_state_imx_deregister_callback function" @@ -106,4 +108,22 @@ Install kmc from the NPM package. [km_core_event_flags]: processor#km_core_event_flags "km_core_event_flags enum" [km_core_process_event]: processor#km_core_process_event "km_core_process_event function" [km_core_event]: processor#km_core_event "km_core_event function" -[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" \ No newline at end of file +[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" +[km_core_action_item]: actions#km_core_action_item "km_core_action_item struct" +[km_core_state_action_items]: actions#km_core_state_action_items "km_core_state_action_items function" +[km_core_state_queue_action_items]: actions#km_core_state_queue_action_items "km_core_state_queue_action_items function" +[km_core_process_queued_actions]: actions#km_core_process_queued_actions "km_core_process_queued_actions function" +[km_core_context_type]: context#km_core_context_type "km_core_context_type enum" +[km_core_context_item]: context#km_core_context_item "km_core_context_item struct" +[KM_CORE_CONTEXT_ITEM_END]: context#KM_CORE_CONTEXT_ITEM_END "KM_CORE_CONTEXT_ITEM_END macro" +[km_core_state_get_intermediate_context]: context#km_core_state_get_intermediate_context "km_core_state_get_intermediate_context function" +[km_core_context_items_dispose]: context#km_core_context_items_dispose "km_core_context_items_dispose function" +[km_core_state_context]: context#km_core_state_context "km_core_state_context function" +[km_core_state_app_context]: context#km_core_state_app_context "km_core_state_app_context function" +[km_core_context_set]: context#km_core_context_set "km_core_context_set function" +[km_core_context_clear]: context#km_core_context_clear "km_core_context_clear function" +[km_core_context_item_list_size]: context#km_core_context_item_list_size "km_core_context_item_list_size function" +[km_core_context_get]: context#km_core_context_get "km_core_context_get function" +[km_core_context_length]: context#km_core_context_length "km_core_context_length function" +[km_core_modifier_state]: virtual-keys#km_core_modifier_state "km_core_modifier_state enum" +[km_core_virtual_key_value]: virtual-keys#km_core_virtual_key_value "km_core_virtual_key_value " \ No newline at end of file diff --git a/core/docs/api/changes.md b/core/docs/api/changes.md index 4b97e83211..9059eef8a8 100644 --- a/core/docs/api/changes.md +++ b/core/docs/api/changes.md @@ -9,13 +9,6 @@ title: Changes - Keyman Core API `km_core_state_options_to_json` and `km_core_state_to_json`, have been removed. -## Changes between 17.0 and 18.0 - -* Replaced `km_core_keyboard_load` with `km_core_keyboard_load_from_blob`. - Keyboard loading is now done in the engine, and the content of the - keyboard passed to Core as a blob. -* Deprecated `km_core_keyboard_attrs.folder_path` - ## Changes between 16.0 and 17.0 * The namespace identifier has changed from `km_kbp_` to `km_core_`. @@ -34,10 +27,10 @@ title: Changes - Keyman Core API [km_core_usv]: background#km_core_usv "km_core_usv type" [km_core_virtual_key]: background#km_core_virtual_key "km_core_virtual_key type" [km_core_status]: background#km_core_status "km_core_status type" -[km_core_modifier_state]: background#km_core_modifier_state "km_core_modifier_state type" [km_core_keyboard]: background#km_core_keyboard "km_core_keyboard struct" [km_core_state]: background#km_core_state "km_core_state struct" [km_core_options]: background#km_core_options "km_core_options struct" +[km_core_keyboard_imx_platform]: background#km_core_keyboard_imx_platform "km_core_keyboard_imx_platform callback function" [km_core_status_codes]: background#km_core_status_codes "km_core_status_codes enum" [km_core_attr]: background#km_core_attr "km_core_attr struct" [km_core_tech_value]: background#km_core_tech_value "km_core_tech_value enum" @@ -52,6 +45,7 @@ title: Changes - Keyman Core API [km_core_option_scope]: options#km_core_option_scope "km_core_option_scope enum" [km_core_option_item]: options#km_core_option_item "km_core_option_item struct" [km_core_options_list_size]: options#km_core_options_list_size "km_core_options_list_size function" +[km_core_state_option_lookup]: options#km_core_state_option_lookup "km_core_state_option_lookup function" [km_core_state_options_update]: options#km_core_state_options_update "km_core_state_options_update function" [km_core_keyboard_attrs]: keyboards#km_core_keyboard_attrs "km_core_keyboard_attrs struct" [km_core_keyboard_key]: keyboards#km_core_keyboard_key "km_core_keyboard_key struct" @@ -61,6 +55,7 @@ title: Changes - Keyman Core API [km_core_keyboard_get_attrs]: keyboards#km_core_keyboard_get_attrs "km_core_keyboard_get_attrs function" [km_core_keyboard_get_key_list]: keyboards#km_core_keyboard_get_key_list "km_core_keyboard_get_key_list function" [km_core_keyboard_key_list_dispose]: keyboards#km_core_keyboard_key_list_dispose "km_core_keyboard_key_list_dispose function" +[km_core_keyboard_get_imx_list]: keyboards#km_core_keyboard_get_imx_list "km_core_keyboard_get_imx_list function" [km_core_keyboard_imx_list_dispose]: keyboards#km_core_keyboard_imx_list_dispose "km_core_keyboard_imx_list_dispose function" [km_core_state_imx_register_callback]: keyboards#km_core_state_imx_register_callback "km_core_state_imx_register_callback function" [km_core_state_imx_deregister_callback]: keyboards#km_core_state_imx_deregister_callback "km_core_state_imx_deregister_callback function" @@ -74,3 +69,21 @@ title: Changes - Keyman Core API [km_core_process_event]: processor#km_core_process_event "km_core_process_event function" [km_core_event]: processor#km_core_event "km_core_event function" [km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" +[km_core_action_item]: actions#km_core_action_item "km_core_action_item struct" +[km_core_state_action_items]: actions#km_core_state_action_items "km_core_state_action_items function" +[km_core_state_queue_action_items]: actions#km_core_state_queue_action_items "km_core_state_queue_action_items function" +[km_core_process_queued_actions]: actions#km_core_process_queued_actions "km_core_process_queued_actions function" +[km_core_context_type]: context#km_core_context_type "km_core_context_type enum" +[km_core_context_item]: context#km_core_context_item "km_core_context_item struct" +[KM_CORE_CONTEXT_ITEM_END]: context#KM_CORE_CONTEXT_ITEM_END "KM_CORE_CONTEXT_ITEM_END macro" +[km_core_state_get_intermediate_context]: context#km_core_state_get_intermediate_context "km_core_state_get_intermediate_context function" +[km_core_context_items_dispose]: context#km_core_context_items_dispose "km_core_context_items_dispose function" +[km_core_state_context]: context#km_core_state_context "km_core_state_context function" +[km_core_state_app_context]: context#km_core_state_app_context "km_core_state_app_context function" +[km_core_context_set]: context#km_core_context_set "km_core_context_set function" +[km_core_context_clear]: context#km_core_context_clear "km_core_context_clear function" +[km_core_context_item_list_size]: context#km_core_context_item_list_size "km_core_context_item_list_size function" +[km_core_context_get]: context#km_core_context_get "km_core_context_get function" +[km_core_context_length]: context#km_core_context_length "km_core_context_length function" +[km_core_modifier_state]: virtual-keys#km_core_modifier_state "km_core_modifier_state enum" +[km_core_virtual_key_value]: virtual-keys#km_core_virtual_key_value "km_core_virtual_key_value " \ No newline at end of file diff --git a/core/docs/api/context.md b/core/docs/api/context.md new file mode 100644 index 0000000000..3896d66847 --- /dev/null +++ b/core/docs/api/context.md @@ -0,0 +1,389 @@ +--- +title: Internal Context - Keyman Core API +--- + +As of version 17.0, Context APIs are now available only to the keyboard +debugger, IMX, and Core unit tests. Do not use these APIs for other cases. +Instead, use [`km_core_state_context_set_if_needed`]. + +---------------------------------------------------------------------------------- + +The context is the text prior to the insertion point (caret, cursor). The +context is constructed by the Platform layer, typically by interrogating the +Client Application. The context will be updated by the engine for keystroke +events. If the Platform layer code caches the context, the context should be +reset when a context state change is detected. Context state changes can occur +when the user uses the mouse to move the insertion point, uses cursor keys, +switches applications or input fields, or presses hotkeys such as Ctrl+N to +start a new document. The full set of context state change triggers is up to the +Platform layer. + +Context can also contain positional Markers (also known as 'deadkeys' in kmn +keyboards), which are transitory state flags that are erased whenever a context +state change is detected. Markers are always controlled by the Engine. + +Contexts are always owned by their state. They may be set to a list of +context_items or interrogated for their current list of context items. + +Core maintains and caches the context. Engine can update the context with +[`km_core_state_context_set_if_needed`] and [`km_core_state_context_clear`]. +These two functions are available in keyman_core_api.h. + +The Keyboard Debugger in Keyman Developer, and IMX in Keyman for Windows, make +use of the context functionality in this header, but these functions should not +be used in other places. + +------------------------------------------------------------------------------- + + +# km_core_context_type enum {#km_core_context_type} + +[`km_core_context_item`].type values which identify which data value (if any) +the context item carries. + +```c +enum km_core_context_type { + /** A [`km_core_context_item`](#km_core_context_item) of this type marks the + * end of an array of context items. */ + KM_CORE_CT_END, + /** The context item contains a Unicode Scalar Value which must be accessed + * through the [`km_core_context_item.character`](#km_core_context_item) + * union member. */ + KM_CORE_CT_CHAR, + /** The context item contains a positional marker which must be accessed + * through the [`km_core_context_item.marker`](#km_core_context_item) union + * member. */ + KM_CORE_CT_MARKER +}; +``` + +# km_core_context_item struct {#km_core_context_item} + +A tagged union representing an element of context which can be either a +Unicode character or a positional marker. + +```c +typedef struct { + /** Identifies the union member to access. A value of enum + * [`km_core_context_type`] values. */ + uint8_t type; + /** Space reserved for alignment purposes and possible future use. */ + uint8_t _reserved[3]; + union { + /** A Unicode Scalar Value. */ + km_core_usv character; + /** A marker value, only meaningful to an engine. */ + uint32_t marker; + }; +} km_core_context_item; +``` + +# KM_CORE_CONTEXT_ITEM_END macro {#KM_CORE_CONTEXT_ITEM_END} + +Convenience macro to declare a terminating entry in a +[`km_core_context_item`] item array. + +```c +#define KM_CORE_CONTEXT_ITEM_END {KM_CORE_CT_END, {0,}, {0,}} +``` + +# km_core_state_get_intermediate_context function {#km_core_state_get_intermediate_context} + +Get access to the state object's keyboard processor's intermediate context. +This context is used during an IMX callback, part way through processing a +keystroke. + + +## Parameters + +### stat +e A pointer to the opaque state object to be queried. + +### context_items +A pointer to a variable to receive a context item +array. Must be disposed of by a call to +[`km_core_context_items_dispose`]. + +## Returns +`KM_CORE_STATUS_OK` on success + +```c +KMN_API +km_core_status +km_core_state_get_intermediate_context( + km_core_state *state, + km_core_context_item ** context_items +); +``` + +# km_core_context_items_dispose function {#km_core_context_items_dispose} + +Free the allocated memory belonging to a `km_core_context_item` array +previously returned by `km_core_state_get_intermediate_context` (internally, +also `context_items_from_utf16` and `km_core_context_get`) + + +## Parameters + +### context_items +A pointer to the start of the `km_core_context_item` +array to be disposed of. + +```c +KMN_API +void +km_core_context_items_dispose( + km_core_context_item *context_items +); +``` + +# km_core_state_context function {#km_core_state_context} + +Get access to the state object's cached context. + + +## Parameters + +### state +A pointer to the opaque state object to be queried. + +## Returns +A pointer to an opaque context object. This pointer is valid for +the lifetime of the state object. If null is passed in, then null +is returned. + +```c +KMN_API +km_core_context * +km_core_state_context( + km_core_state const *state +); +``` + +# km_core_state_app_context function {#km_core_state_app_context} + +Get access to the state object's application context. + + +## Parameters + +### state +A pointer to the opaque state object to be queried. + +## Returns +A pointer to an opaque context object. This pointer is valid for +the lifetime of the state object. If null is passed in, then null +is returned. + +```c +KMN_API +km_core_context * +km_core_state_app_context( + km_core_state const *state +); +``` + +# km_core_context_set function {#km_core_context_set} + +Replace the contents of the current context with a new sequence of +`km_core_context_item` entries. + + +## Parameters + +### context +A pointer to an opaque context object + +### context_items +A pointer to the start of the `km_core_context_item` +array containing the new context. It must be +terminated with an item of type `KM_CORE_CT_END`. + +## Returns +One of the following values: + +`KM_CORE_STATUS_OK` +: On success. + +`KM_CORE_STATUS_INVALID_ARGUMENT` +: If non-optional parameters are null. + +`KM_CORE_STATUS_NO_MEM` +: In the event not enough memory can be allocated to grow the context +buffer internally. + +```c +KMN_API +km_core_status +km_core_context_set( + km_core_context *context, + km_core_context_item const *context_items +); +``` + +# km_core_context_clear function {#km_core_context_clear} + +Removes all context_items from the internal array. If `context` is null, has +no effect. + + +## Parameters + +### context +A pointer to an opaque context object + +```c +KMN_API +void +km_core_context_clear( + km_core_context * +); +``` + +# km_core_context_item_list_size function {#km_core_context_item_list_size} + +Return the length of a terminated `km_core_context_item` array. + + +## Parameters + +### context_items +A pointer to a `KM_CORE_CT_END` terminated array of +`km_core_context_item` values. + +## Returns +The number of items in the list, not including terminating item, or +0 if `context_items` is null. + +```c +KMN_API +size_t +km_core_context_item_list_size( + km_core_context_item const *context_items +); +``` + +# km_core_context_get function {#km_core_context_get} + +Copies all items in the context into a new array and returns the new array. +This must be disposed of by caller using `km_core_context_items_dispose`. + + +## Parameters + +### context +A pointer to an opaque context object + +### out +Pointer to the result variable: A pointer to the start of +the `km_core_context_item` array containing a copy of the +context. Terminated with a type of `KM_CORE_CT_END`. Must be +disposed of with `km_core_context_items_dispose`. + +## Returns +One of the following values: + +`KM_CORE_STATUS_OK` +: On success. + +`KM_CORE_STATUS_INVALID_ARGUMENT` +: If non-optional parameters are null. + +`KM_CORE_STATUS_NO_MEM` +: In the event not enough memory can be allocated for the output buffer. + +```c +KMN_API +km_core_status +km_core_context_get( + km_core_context const *context, + km_core_context_item **out +); +``` + +# km_core_context_length function {#km_core_context_length} + +Return the number of items in the context. + + +## Parameters + +### context +A pointer to an opaque context object + +## Returns +The number of items in the context, and will return 0 if passed a +null `context` pointer. + +```c +KMN_API +size_t +km_core_context_length( + km_core_context *context +); +/* + +[km_core_cu]: background#km_core_cu "km_core_cu type" +[km_core_usv]: background#km_core_usv "km_core_usv type" +[km_core_virtual_key]: background#km_core_virtual_key "km_core_virtual_key type" +[km_core_status]: background#km_core_status "km_core_status type" +[km_core_keyboard]: background#km_core_keyboard "km_core_keyboard struct" +[km_core_state]: background#km_core_state "km_core_state struct" +[km_core_options]: background#km_core_options "km_core_options struct" +[km_core_keyboard_imx_platform]: background#km_core_keyboard_imx_platform "km_core_keyboard_imx_platform callback function" +[km_core_status_codes]: background#km_core_status_codes "km_core_status_codes enum" +[km_core_attr]: background#km_core_attr "km_core_attr struct" +[km_core_tech_value]: background#km_core_tech_value "km_core_tech_value enum" +[km_core_get_engine_attrs]: background#km_core_get_engine_attrs "km_core_get_engine_attrs function" +[km_core_bool]: background#km_core_bool "km_core_bool enum" +[km_core_caps_state]: state#km_core_caps_state "km_core_caps_state enum" +[km_core_actions]: state#km_core_actions "km_core_actions struct" +[km_core_state_get_actions]: state#km_core_state_get_actions "km_core_state_get_actions function" +[km_core_context_status]: state#km_core_context_status "km_core_context_status enum" +[km_core_state_context_set_if_needed]: state#km_core_state_context_set_if_needed "km_core_state_context_set_if_needed function" +[km_core_state_context_clear]: state#km_core_state_context_clear "km_core_state_context_clear function" +[km_core_option_scope]: options#km_core_option_scope "km_core_option_scope enum" +[km_core_option_item]: options#km_core_option_item "km_core_option_item struct" +[km_core_options_list_size]: options#km_core_options_list_size "km_core_options_list_size function" +[km_core_state_option_lookup]: options#km_core_state_option_lookup "km_core_state_option_lookup function" +[km_core_state_options_update]: options#km_core_state_options_update "km_core_state_options_update function" +[km_core_keyboard_attrs]: keyboards#km_core_keyboard_attrs "km_core_keyboard_attrs struct" +[km_core_keyboard_key]: keyboards#km_core_keyboard_key "km_core_keyboard_key struct" +[km_core_keyboard_imx]: keyboards#km_core_keyboard_imx "km_core_keyboard_imx struct" +[km_core_keyboard_load_from_blob]: keyboards#km_core_keyboard_load_from_blob "km_core_keyboard_load_from_blob function" +[km_core_keyboard_dispose]: keyboards#km_core_keyboard_dispose "km_core_keyboard_dispose function" +[km_core_keyboard_get_attrs]: keyboards#km_core_keyboard_get_attrs "km_core_keyboard_get_attrs function" +[km_core_keyboard_get_key_list]: keyboards#km_core_keyboard_get_key_list "km_core_keyboard_get_key_list function" +[km_core_keyboard_key_list_dispose]: keyboards#km_core_keyboard_key_list_dispose "km_core_keyboard_key_list_dispose function" +[km_core_keyboard_get_imx_list]: keyboards#km_core_keyboard_get_imx_list "km_core_keyboard_get_imx_list function" +[km_core_keyboard_imx_list_dispose]: keyboards#km_core_keyboard_imx_list_dispose "km_core_keyboard_imx_list_dispose function" +[km_core_state_imx_register_callback]: keyboards#km_core_state_imx_register_callback "km_core_state_imx_register_callback function" +[km_core_state_imx_deregister_callback]: keyboards#km_core_state_imx_deregister_callback "km_core_state_imx_deregister_callback function" +[km_core_state_create]: keyboards#km_core_state_create "km_core_state_create function" +[km_core_state_clone]: keyboards#km_core_state_clone "km_core_state_clone function" +[km_core_state_dispose]: keyboards#km_core_state_dispose "km_core_state_dispose function" +[km_core_debug_context_type]: keyboards#km_core_debug_context_type "km_core_debug_context_type enum" +[km_core_state_context_debug]: keyboards#km_core_state_context_debug "km_core_state_context_debug function" +[km_core_cu_dispose]: keyboards#km_core_cu_dispose "km_core_cu_dispose function" +[km_core_event_flags]: processor#km_core_event_flags "km_core_event_flags enum" +[km_core_process_event]: processor#km_core_process_event "km_core_process_event function" +[km_core_event]: processor#km_core_event "km_core_event function" +[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" +[km_core_action_item]: actions#km_core_action_item "km_core_action_item struct" +[km_core_state_action_items]: actions#km_core_state_action_items "km_core_state_action_items function" +[km_core_state_queue_action_items]: actions#km_core_state_queue_action_items "km_core_state_queue_action_items function" +[km_core_process_queued_actions]: actions#km_core_process_queued_actions "km_core_process_queued_actions function" +[km_core_context_type]: context#km_core_context_type "km_core_context_type enum" +[km_core_context_item]: context#km_core_context_item "km_core_context_item struct" +[KM_CORE_CONTEXT_ITEM_END]: context#KM_CORE_CONTEXT_ITEM_END "KM_CORE_CONTEXT_ITEM_END macro" +[km_core_state_get_intermediate_context]: context#km_core_state_get_intermediate_context "km_core_state_get_intermediate_context function" +[km_core_context_items_dispose]: context#km_core_context_items_dispose "km_core_context_items_dispose function" +[km_core_state_context]: context#km_core_state_context "km_core_state_context function" +[km_core_state_app_context]: context#km_core_state_app_context "km_core_state_app_context function" +[km_core_context_set]: context#km_core_context_set "km_core_context_set function" +[km_core_context_clear]: context#km_core_context_clear "km_core_context_clear function" +[km_core_context_item_list_size]: context#km_core_context_item_list_size "km_core_context_item_list_size function" +[km_core_context_get]: context#km_core_context_get "km_core_context_get function" +[km_core_context_length]: context#km_core_context_length "km_core_context_length function" +[km_core_modifier_state]: virtual-keys#km_core_modifier_state "km_core_modifier_state enum" +[km_core_virtual_key_value]: virtual-keys#km_core_virtual_key_value "km_core_virtual_key_value " \ No newline at end of file diff --git a/core/docs/api/index.md b/core/docs/api/index.md index 03fdd0cfdc..500df85d40 100644 --- a/core/docs/api/index.md +++ b/core/docs/api/index.md @@ -81,10 +81,10 @@ Caps Lock. [km_core_usv]: background#km_core_usv "km_core_usv type" [km_core_virtual_key]: background#km_core_virtual_key "km_core_virtual_key type" [km_core_status]: background#km_core_status "km_core_status type" -[km_core_modifier_state]: background#km_core_modifier_state "km_core_modifier_state type" [km_core_keyboard]: background#km_core_keyboard "km_core_keyboard struct" [km_core_state]: background#km_core_state "km_core_state struct" [km_core_options]: background#km_core_options "km_core_options struct" +[km_core_keyboard_imx_platform]: background#km_core_keyboard_imx_platform "km_core_keyboard_imx_platform callback function" [km_core_status_codes]: background#km_core_status_codes "km_core_status_codes enum" [km_core_attr]: background#km_core_attr "km_core_attr struct" [km_core_tech_value]: background#km_core_tech_value "km_core_tech_value enum" @@ -99,6 +99,7 @@ Caps Lock. [km_core_option_scope]: options#km_core_option_scope "km_core_option_scope enum" [km_core_option_item]: options#km_core_option_item "km_core_option_item struct" [km_core_options_list_size]: options#km_core_options_list_size "km_core_options_list_size function" +[km_core_state_option_lookup]: options#km_core_state_option_lookup "km_core_state_option_lookup function" [km_core_state_options_update]: options#km_core_state_options_update "km_core_state_options_update function" [km_core_keyboard_attrs]: keyboards#km_core_keyboard_attrs "km_core_keyboard_attrs struct" [km_core_keyboard_key]: keyboards#km_core_keyboard_key "km_core_keyboard_key struct" @@ -108,6 +109,7 @@ Caps Lock. [km_core_keyboard_get_attrs]: keyboards#km_core_keyboard_get_attrs "km_core_keyboard_get_attrs function" [km_core_keyboard_get_key_list]: keyboards#km_core_keyboard_get_key_list "km_core_keyboard_get_key_list function" [km_core_keyboard_key_list_dispose]: keyboards#km_core_keyboard_key_list_dispose "km_core_keyboard_key_list_dispose function" +[km_core_keyboard_get_imx_list]: keyboards#km_core_keyboard_get_imx_list "km_core_keyboard_get_imx_list function" [km_core_keyboard_imx_list_dispose]: keyboards#km_core_keyboard_imx_list_dispose "km_core_keyboard_imx_list_dispose function" [km_core_state_imx_register_callback]: keyboards#km_core_state_imx_register_callback "km_core_state_imx_register_callback function" [km_core_state_imx_deregister_callback]: keyboards#km_core_state_imx_deregister_callback "km_core_state_imx_deregister_callback function" @@ -120,4 +122,22 @@ Caps Lock. [km_core_event_flags]: processor#km_core_event_flags "km_core_event_flags enum" [km_core_process_event]: processor#km_core_process_event "km_core_process_event function" [km_core_event]: processor#km_core_event "km_core_event function" -[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" \ No newline at end of file +[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" +[km_core_action_item]: actions#km_core_action_item "km_core_action_item struct" +[km_core_state_action_items]: actions#km_core_state_action_items "km_core_state_action_items function" +[km_core_state_queue_action_items]: actions#km_core_state_queue_action_items "km_core_state_queue_action_items function" +[km_core_process_queued_actions]: actions#km_core_process_queued_actions "km_core_process_queued_actions function" +[km_core_context_type]: context#km_core_context_type "km_core_context_type enum" +[km_core_context_item]: context#km_core_context_item "km_core_context_item struct" +[KM_CORE_CONTEXT_ITEM_END]: context#KM_CORE_CONTEXT_ITEM_END "KM_CORE_CONTEXT_ITEM_END macro" +[km_core_state_get_intermediate_context]: context#km_core_state_get_intermediate_context "km_core_state_get_intermediate_context function" +[km_core_context_items_dispose]: context#km_core_context_items_dispose "km_core_context_items_dispose function" +[km_core_state_context]: context#km_core_state_context "km_core_state_context function" +[km_core_state_app_context]: context#km_core_state_app_context "km_core_state_app_context function" +[km_core_context_set]: context#km_core_context_set "km_core_context_set function" +[km_core_context_clear]: context#km_core_context_clear "km_core_context_clear function" +[km_core_context_item_list_size]: context#km_core_context_item_list_size "km_core_context_item_list_size function" +[km_core_context_get]: context#km_core_context_get "km_core_context_get function" +[km_core_context_length]: context#km_core_context_length "km_core_context_length function" +[km_core_modifier_state]: virtual-keys#km_core_modifier_state "km_core_modifier_state enum" +[km_core_virtual_key_value]: virtual-keys#km_core_virtual_key_value "km_core_virtual_key_value " \ No newline at end of file diff --git a/core/docs/api/keyboards.md b/core/docs/api/keyboards.md index 8aafd94f7f..abfa327b6b 100644 --- a/core/docs/api/keyboards.md +++ b/core/docs/api/keyboards.md @@ -9,138 +9,79 @@ of state objects. ------------------------------------------------------------------------------- -# km_core_keyboard_attrs struct {#km_core_keyboard_attrs} -## Description +# km_core_keyboard_attrs struct {#km_core_keyboard_attrs} Provides read-only information about a keyboard. -## Specification ```c typedef struct { + /** Processor specific version string. */ km_core_cu const * version_string; + /** Keyman keyboard ID string. */ km_core_cu const * id; - - // TODO-web-core: Deprecate this field (#12497) - // KMN_DEPRECATED - km_core_path_name folder_path; - + /** Set of default values for any options included in the keyboard. */ km_core_option_item const * default_options; } km_core_keyboard_attrs; - ``` -## Members - -`version_string` -: Processor specific version string. - -`id` -: Keyman keyboard ID string. - -`folder_path` -: Path to the unpacked folder containing the keyboard and associated resources (deprecated). - -`default_options` -: Set of default values for any options included in the keyboard. - -------------------------------------------------------------------------------- # km_core_keyboard_key struct {#km_core_keyboard_key} -## Description - Describes a single key and modifier combination that a keyboard handles, for use by the Platform layer. This is used when the Platform layer must know in advance which keys are used by a given keyboard. -## Specification - ```c typedef struct { + /** A virtual key. */ km_core_virtual_key key; + /** A [km_core_modifier_state] bitmask. */ uint32_t modifier_flag; } km_core_keyboard_key; - #define KM_CORE_KEYBOARD_KEY_LIST_END { 0, 0 } - ``` -## Members - -`key` -: A virtual key. - -`modifier_flag` -: A [km_core_modifier_state] bitmask. - -------------------------------------------------------------------------------- - # km_core_keyboard_imx struct {#km_core_keyboard_imx} -## Description - Describes a single Input Method eXtension library and entry point. -## Specification - ```c typedef struct { + /** The fully-qualified path and filename of the dynamically loaded library + * file. */ km_core_cu const * library_name; + /** The entry point for the IMX. */ km_core_cu const * function_name; + /** unique identifier used to call this function */ uint32_t imx_id; } km_core_keyboard_imx; - #define KM_CORE_KEYBOARD_IMX_END { 0, 0, 0 } - ``` -## Members -`library_name` -: The fully-qualified path and filename of the dynamically loaded library file. +# km_core_keyboard_load_from_blob function {#km_core_keyboard_load_from_blob} -`function_name` -: The entry point for the IMX. +Parse and load keyboard from the supplied blob and a pointer to the loaded +keyboard into the out paramter. -`imx_id` -: unique identifier used to call this function - -------------------------------------------------------------------------------- - -# km_core_keyboard_load_from_blob() {#km_core_keyboard_load_from_blob} - -## Description - -Parse and load keyboard from the supplied blob and a pointer to the loaded keyboard -into the out paramter. - -## Specification - -```c -KMN_API -km_core_status km_core_keyboard_load_from_blob(const km_core_path_name kb_name, - const void* blob, - const size_t blob_size, - km_core_keyboard** keyboard); - -``` ## Parameters -`kb_name` -: a string with the name of the keyboard. +### kb_name +a string with the name of the keyboard. -`blob` -: a byte array containing the content of a KMX/KMX+ file. +### blob +a byte array containing the content of a KMX/KMX+ file. -`blob_size` -: a size_t variable with the size of the blob in bytes. +### blob_size +a size_t variable with the size of the blob in bytes. -`keyboard` -: A pointer to result variable: A pointer to the opaque keyboard - object returned by the Processor. This memory must be freed with a - call to [km_core_keyboard_dispose]. +### keyboard +A pointer to result variable: A pointer to the opaque +keyboard object returned by the Processor. This memory +must be freed with a call to [km_core_keyboard_dispose]. ## Returns +One of the following values: `KM_CORE_STATUS_OK` : On success. @@ -157,54 +98,53 @@ km_core_status km_core_keyboard_load_from_blob(const km_core_path_name kb_name, `KM_CORE_STATUS_OS_ERROR` : Bit 31 (high bit) set, bits 0-30 are an OS-specific error code. -------------------------------------------------------------------------------- +```c +KMN_API +km_core_status km_core_keyboard_load_from_blob( + const km_core_path_name kb_name, + const void* blob, + const size_t blob_size, + km_core_keyboard** keyboard +); +``` -# km_core_keyboard_dispose() {#km_core_keyboard_dispose} - -## Description +# km_core_keyboard_dispose function {#km_core_keyboard_dispose} Free the allocated memory belonging to an opaque keyboard object previously returned by [km_core_keyboard_load_from_blob]. -## Specification + +## Parameters + +### keyboard +A pointer to the opaque keyboard object to be disposed of. ```c KMN_API void -km_core_keyboard_dispose(km_core_keyboard *keyboard); - +km_core_keyboard_dispose( + km_core_keyboard const* keyboard +); ``` -## Parameters -`keyboard` -: A pointer to the opaque keyboard object to be disposed of. -------------------------------------------------------------------------------- +# km_core_keyboard_get_attrs function {#km_core_keyboard_get_attrs} -# km_core_keyboard_get_attrs() {#km_core_keyboard_get_attrs} +Returns the const internal attributes of the keyboard. This structure is +valid for the lifetime of the opaque keyboard object. Do not modify the +returned data. -## Description -Returns the const internal attributes of the keyboard. This structure is valid -for the lifetime of the opaque keyboard object. Do not modify the returned data. - -## Specification - -```c -KMN_API -km_core_status -km_core_keyboard_get_attrs(km_core_keyboard const *keyboard, - km_core_keyboard_attrs const **out); - -``` ## Parameters -`keyboard` -: A pointer to the opaque keyboard object to be queried. +### keyboard +A pointer to the opaque keyboard object to be queried. -`out` -: A pointer to the result: A pointer to a [km_core_keyboard_attrs] structure. +### out +A pointer to the result: A pointer to a +[km_core_keyboard_attrs] structure. ## Returns +One of the following values: `KM_CORE_STATUS_OK` : On success. @@ -212,34 +152,33 @@ km_core_keyboard_get_attrs(km_core_keyboard const *keyboard, `KM_CORE_STATUS_INVALID_ARGUMENT` : If non-optional parameters are null. -------------------------------------------------------------------------------- - -# km_core_keyboard_get_key_list() {#km_core_keyboard_get_key_list} - -## Description - -Returns the unordered full set of modifier+virtual keys that are handled by the -keyboard. The matching dispose call needs to be called to free the memory. - -## Specification - ```c KMN_API km_core_status -km_core_keyboard_get_key_list(km_core_keyboard const *keyboard, - km_core_keyboard_key **out); - +km_core_keyboard_get_attrs( + km_core_keyboard const *keyboard, + km_core_keyboard_attrs const **out +); ``` + +# km_core_keyboard_get_key_list function {#km_core_keyboard_get_key_list} + +Returns the unordered full set of modifier+virtual keys that are handled by +the keyboard. The matching dispose call needs to be called to free the +memory. + + ## Parameters -`keyboard` -: A pointer to the opaque keyboard object to be queried. +### keyboard +A pointer to the opaque keyboard object to be queried. -`out` -: A pointer to an array of [km_core_keyboard_key] structures, - terminated by `KM_CORE_KEYBOARD_KEY_LIST_END`. +### out +A pointer to an array of [km_core_keyboard_key] structures, +terminated by `KM_CORE_KEYBOARD_KEY_LIST_END`. ## Returns +One of the following values: `KM_CORE_STATUS_OK` : On success. @@ -247,52 +186,52 @@ km_core_keyboard_get_key_list(km_core_keyboard const *keyboard, `KM_CORE_STATUS_INVALID_ARGUMENT` : If non-optional parameters are null. -------------------------------------------------------------------------------- +```c +KMN_API +km_core_status +km_core_keyboard_get_key_list( + km_core_keyboard const *keyboard, + km_core_keyboard_key **out +); +``` -# km_core_keyboard_key_list_dispose() {#km_core_keyboard_key_list_dispose} - -## Description +# km_core_keyboard_key_list_dispose function {#km_core_keyboard_key_list_dispose} Free the allocated memory belonging to a keyboard key list previously returned by [km_core_keyboard_get_key_list]. -## Specification + +## Parameters + +### key_list +A pointer to the keyboard key list to be disposed of. ```c KMN_API -void km_core_keyboard_key_list_dispose(km_core_keyboard_key *key_list); - +void +km_core_keyboard_key_list_dispose( + km_core_keyboard_key *key_list +); ``` -## Parameters -`key_list` -: A pointer to the keyboard key list to be disposed of. - -------------------------------------------------------------------------------- - -# km_core_keyboard_get_imx_list - -## Description +# km_core_keyboard_get_imx_list function {#km_core_keyboard_get_imx_list} Returns the list of IMX libraries and function names that are referenced by -the keyboard. The matching dispose call needs to be called to free the memory. +the keyboard. The matching dispose call needs to be called to free the +memory. -## Specification -```c -KMN_API -km_core_status km_core_keyboard_get_imx_list(km_core_keyboard const *keyboard, km_core_keyboard_imx **imx_list); - -``` ## Parameters -`keyboard` -: A pointer to the keyboard +### keyboard +A pointer to the keyboard -`imx_list` -: A pointer to a variable that will contain a pointer to the IMX list. +### imx_list +A pointer to a variable that will contain a pointer to +the IMX list. ## Returns +One of the following values: `KM_CORE_STATUS_OK` : On success. @@ -300,107 +239,105 @@ km_core_status km_core_keyboard_get_imx_list(km_core_keyboard const *keyboard, k `KM_CORE_STATUS_INVALID_ARGUMENT` : If non-optional parameters are null. -------------------------------------------------------------------------------- - -# km_core_keyboard_imx_list_dispose() {#km_core_keyboard_imx_list_dispose} - -## Description - -Disposes of the IMX list. - -## Specification - -```c -KMN_API -void km_core_keyboard_imx_list_dispose(km_core_keyboard_imx *imx_list); - -``` -## Parameters - -`imx_list` -: A pointer to the IMX list. - -------------------------------------------------------------------------------- - -# km_core_state_imx_register_callback() {#km_core_state_imx_register_callback} - -## Description - -Register the IMX callback endpoint for the client. - -## Specification - -```c -KMN_API -void km_core_state_imx_register_callback(km_core_state *state, km_core_keyboard_imx_platform imx_callback, void *callback_object); - -``` -## Parameters - -`state` -: A pointer to the opaque state object - -`imx_callback` -: pointer to a function that implements the IMX callback - -`callback_object` -: An opaque pointer that can be used to pass context information to the callback function, - usually it is a user-defined data structure. - -------------------------------------------------------------------------------- - -# km_core_state_imx_deregister_callback() {#km_core_state_imx_deregister_callback} - -## Description - -De-register IMX callback endpoint for the client. - -## Specification - -```c -KMN_API -void km_core_state_imx_deregister_callback(km_core_state *state); - -``` -## Parameters - -`state` -: A pointer to the opaque state object - -------------------------------------------------------------------------------- - -# km_core_state_create() {#km_core_state_create} - -## Description - -Create a keyboard processor state object, maintaining state for the keyboard in -the environment passed. - -## Specification - ```c KMN_API km_core_status -km_core_state_create(km_core_keyboard *keyboard, - km_core_option_item const *env, - km_core_state **out); - +km_core_keyboard_get_imx_list( + km_core_keyboard const *keyboard, + km_core_keyboard_imx **imx_list +); ``` + +# km_core_keyboard_imx_list_dispose function {#km_core_keyboard_imx_list_dispose} + +Disposes of the IMX list. + + ## Parameters -`keyboard` -: A pointer to the opaque keyboard object this object will hold state for. +### imx_list +A pointer to the IMX list. -`env` -: The array of [km_core_option_item] key/value pairs used to initialise the - environment, terminated by `KM_CORE_OPTIONS_END`. +```c +KMN_API +void +km_core_keyboard_imx_list_dispose( + km_core_keyboard_imx *imx_list +); +``` -`out` -: A pointer to result variable: A pointer to the opaque state object - returned by the Processor, initalised to maintain state for `keyboard`. - This must be disposed of by a call to [km_core_state_dispose]. +# km_core_state_imx_register_callback function {#km_core_state_imx_register_callback} + +Register the IMX callback endpoint for the client. + + +## Parameters + +### state +A pointer to the opaque state object + +### imx_callback +Pointer to a function that implements the IMX +callback + +### callback_object +An opaque pointer that can be used to pass context +information to the callback function, usually it is +a user-defined data structure. + +```c +KMN_API +void +km_core_state_imx_register_callback( + km_core_state *state, + km_core_keyboard_imx_platform imx_callback, + void *callback_object +); +``` + +# km_core_state_imx_deregister_callback function {#km_core_state_imx_deregister_callback} + +De-register IMX callback endpoint for the client. + + +## Parameters + +### state +A pointer to the opaque state object + +```c +KMN_API +void +km_core_state_imx_deregister_callback( + km_core_state *state +); +``` + +# km_core_state_create function {#km_core_state_create} + +Create a keyboard processor state object, maintaining state for the keyboard +in the environment passed. + + +## Parameters + +### keyboard +A pointer to the opaque keyboard object this object will +hold state for. + +### env +The array of [km_core_option_item] key/value pairs used to +initialise the environment, terminated by +`KM_CORE_OPTIONS_END`. + +### out +A pointer to result variable: A pointer to the opaque state +object returned by the Processor, initalised to maintain +state for `keyboard`. This must be disposed of by a call to +[km_core_state_dispose]. ## Returns +One of the following values: `KM_CORE_STATUS_OK` : On success. @@ -411,34 +348,34 @@ km_core_state_create(km_core_keyboard *keyboard, `KM_CORE_STATUS_INVALID_ARGUMENT` : In the event the `keyboard` or `out` pointer are null. -------------------------------------------------------------------------------- - -# km_core_state_clone() {#km_core_state_clone} - -## Description - -Clone an existing opaque state object. - -## Specification - ```c KMN_API km_core_status -km_core_state_clone(km_core_state const *state, - km_core_state **out); - +km_core_state_create( + km_core_keyboard const *keyboard, + km_core_option_item const *env, + km_core_state **out +); ``` + +# km_core_state_clone function {#km_core_state_clone} + +Clone an existing opaque state object. + + ## Parameters -`state` -: A pointer to the opaque state object to be cloned. +### state +A pointer to the opaque state object to be cloned. -`out` -: A pointer to result variable: A pointer to the opaque state object - returned by the Processor, cloned from the existing object `state`. This - must be disposed of by a call to [km_core_state_dispose]. +### out +A pointer to result variable: A pointer to the opaque state +object returned by the Processor, cloned from the existing +object `state`. This must be disposed of by a call to +[km_core_state_dispose]. ## Returns +One of the following values: `KM_CORE_STATUS_OK` : On success. @@ -449,137 +386,122 @@ km_core_state_clone(km_core_state const *state, `KM_CORE_STATUS_INVALID_ARGUMENT` : In the event the `state` or `out` pointer are null. -------------------------------------------------------------------------------- +```c +KMN_API +km_core_status +km_core_state_clone( + km_core_state const *state, + km_core_state **out +); +``` -# km_core_state_dispose() {#km_core_state_dispose} - -## Description +# km_core_state_dispose function {#km_core_state_dispose} Free the allocated resources belonging to a [km_core_state] object previously returned by [km_core_state_create] or [km_core_state_clone]. After this all -pointers previously returned by any [km_core_state] family of calls will become -invalid. +pointers previously returned by any [km_core_state] family of calls will +become invalid. -## Specification + +## Parameters + +### state +A pointer to the opaque state object to be disposed. ```c KMN_API void -km_core_state_dispose(km_core_state *state); - +km_core_state_dispose( + km_core_state const *state +); ``` -## Parameters - -`state` -: A pointer to the opaque state object to be disposed. - -------------------------------------------------------------------------------- # km_core_debug_context_type enum {#km_core_debug_context_type} -As of version 17, the cached context is an internal property of the -state, not exposed to the consumer of the API -- apart from the -Keyman Developer Keyboard Debugger. However, for other debug -purposes, it is helpful to be able to examine the cached context, so -a debug-formatted version of the context is made available with -[km_core_state_context_debug]. This is not intended to be parsed for -reading the context for other purposes, and the format may change. + +As of version 17, the cached context is an internal property of the state, +not exposed to the consumer of the API -- apart from the Keyman Developer +Keyboard Debugger. However, for other debug purposes, it is helpful to be +able to examine the cached context, so a debug-formatted version of the +context is made available with [km_core_state_context_debug]. This is not +intended to be parsed for reading the context for other purposes, and the +format may change. The three context types are: cached, intermediate, and app. -## Specification - ```c typedef enum { + /** the internal context used by Core, which may be normalized and may contain + * markers. This is set via [km_core_state_context_set_if_needed], and will + * be modified during keystroke event processing. */ KM_CORE_DEBUG_CONTEXT_CACHED = 0, + /** internal context used by IMX, only valid during keystroke event + * processing. */ KM_CORE_DEBUG_CONTEXT_INTERMEDIATE = 1, + /** an exact copy of the current context passed in to + * [km_core_state_context_set_if_needed], which is used to verify the precise + * text manipulations required when emitted changes. This input context is in + * "NFU" -- normalization form unknown, and may be mixed normalization so may + * require fixups when it is manipulated by keyboard processors that support + * normalization, such as the LDML keyboard processor. */ KM_CORE_DEBUG_CONTEXT_APP = 2 } km_core_debug_context_type; - ``` -## Values -`KM_CORE_DEBUG_CONTEXT_CACHED` -: the internal context used by Core, which may be normalized - and may contain markers. This is set via - [km_core_state_context_set_if_needed], and will be modified - during keystroke event processing. - -`KM_CORE_DEBUG_CONTEXT_INTERMEDIATE` -: internal context used by IMX, only valid during - keystroke event processing. - -`KM_CORE_DEBUG_CONTEXT_APP` -: an exact copy of the current context passed in to - [km_core_state_context_set_if_needed], which is used to verify - the precise text manipulations required when emitted changes. - This input context is in "NFU" -- normalization form unknown, - and may be mixed normalization so may require fixups when - it is manipulated by keyboard processors that support - normalization, such as the LDML keyboard processor. - -------------------------------------------------------------------------------- - -# km_core_state_context_debug() {#km_core_state_context_debug} - -## Description +# km_core_state_context_debug function {#km_core_state_context_debug} Returns a debug formatted string of the context from the state. -## Specification + +## Parameters + +### state +A pointer to the opaque state object to be queried. + +### context_type +The type of context to retrieve from the state. + +## Returns +A pointer to a [km_core_cu] UTF-16 string. Must be disposed of by a +call to [km_core_cu_dispose]. ```c KMN_API km_core_cu * -km_core_state_context_debug(km_core_state *state, km_core_debug_context_type context_type); - +km_core_state_context_debug( + const km_core_state *state, + km_core_debug_context_type context_type +); ``` -## Parameters -`state` -: A pointer to the opaque state object to be queried. - -`context_type` -: The type of context to retrieve from the state. - -## Returns - -A pointer to a [km_core_cu] UTF-16 string. Must be disposed of by a call -to [km_core_cu_dispose]. - -------------------------------------------------------------------------------- - -# km_core_cu_dispose() {#km_core_cu_dispose} - -## Description +# km_core_cu_dispose function {#km_core_cu_dispose} Free the allocated memory belonging to a [km_core_cu] array previously returned by [km_core_state_context_debug]. May be `nullptr`. -## Specification + +## Parameters + +### cp +A pointer to the start of the [km_core_cu] array to be disposed +of. ```c KMN_API void -km_core_cu_dispose(km_core_cu *cp); - +km_core_cu_dispose( + km_core_cu *cp +); ``` -## Parameters - -`cp` -: A pointer to the start of the [km_core_cu] array to be disposed of. - -------------------------------------------------------------------------------- - [km_core_cu]: background#km_core_cu "km_core_cu type" [km_core_usv]: background#km_core_usv "km_core_usv type" [km_core_virtual_key]: background#km_core_virtual_key "km_core_virtual_key type" [km_core_status]: background#km_core_status "km_core_status type" -[km_core_modifier_state]: background#km_core_modifier_state "km_core_modifier_state type" [km_core_keyboard]: background#km_core_keyboard "km_core_keyboard struct" [km_core_state]: background#km_core_state "km_core_state struct" [km_core_options]: background#km_core_options "km_core_options struct" +[km_core_keyboard_imx_platform]: background#km_core_keyboard_imx_platform "km_core_keyboard_imx_platform callback function" [km_core_status_codes]: background#km_core_status_codes "km_core_status_codes enum" [km_core_attr]: background#km_core_attr "km_core_attr struct" [km_core_tech_value]: background#km_core_tech_value "km_core_tech_value enum" @@ -594,6 +516,7 @@ km_core_cu_dispose(km_core_cu *cp); [km_core_option_scope]: options#km_core_option_scope "km_core_option_scope enum" [km_core_option_item]: options#km_core_option_item "km_core_option_item struct" [km_core_options_list_size]: options#km_core_options_list_size "km_core_options_list_size function" +[km_core_state_option_lookup]: options#km_core_state_option_lookup "km_core_state_option_lookup function" [km_core_state_options_update]: options#km_core_state_options_update "km_core_state_options_update function" [km_core_keyboard_attrs]: keyboards#km_core_keyboard_attrs "km_core_keyboard_attrs struct" [km_core_keyboard_key]: keyboards#km_core_keyboard_key "km_core_keyboard_key struct" @@ -603,6 +526,7 @@ km_core_cu_dispose(km_core_cu *cp); [km_core_keyboard_get_attrs]: keyboards#km_core_keyboard_get_attrs "km_core_keyboard_get_attrs function" [km_core_keyboard_get_key_list]: keyboards#km_core_keyboard_get_key_list "km_core_keyboard_get_key_list function" [km_core_keyboard_key_list_dispose]: keyboards#km_core_keyboard_key_list_dispose "km_core_keyboard_key_list_dispose function" +[km_core_keyboard_get_imx_list]: keyboards#km_core_keyboard_get_imx_list "km_core_keyboard_get_imx_list function" [km_core_keyboard_imx_list_dispose]: keyboards#km_core_keyboard_imx_list_dispose "km_core_keyboard_imx_list_dispose function" [km_core_state_imx_register_callback]: keyboards#km_core_state_imx_register_callback "km_core_state_imx_register_callback function" [km_core_state_imx_deregister_callback]: keyboards#km_core_state_imx_deregister_callback "km_core_state_imx_deregister_callback function" @@ -616,3 +540,21 @@ km_core_cu_dispose(km_core_cu *cp); [km_core_process_event]: processor#km_core_process_event "km_core_process_event function" [km_core_event]: processor#km_core_event "km_core_event function" [km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" +[km_core_action_item]: actions#km_core_action_item "km_core_action_item struct" +[km_core_state_action_items]: actions#km_core_state_action_items "km_core_state_action_items function" +[km_core_state_queue_action_items]: actions#km_core_state_queue_action_items "km_core_state_queue_action_items function" +[km_core_process_queued_actions]: actions#km_core_process_queued_actions "km_core_process_queued_actions function" +[km_core_context_type]: context#km_core_context_type "km_core_context_type enum" +[km_core_context_item]: context#km_core_context_item "km_core_context_item struct" +[KM_CORE_CONTEXT_ITEM_END]: context#KM_CORE_CONTEXT_ITEM_END "KM_CORE_CONTEXT_ITEM_END macro" +[km_core_state_get_intermediate_context]: context#km_core_state_get_intermediate_context "km_core_state_get_intermediate_context function" +[km_core_context_items_dispose]: context#km_core_context_items_dispose "km_core_context_items_dispose function" +[km_core_state_context]: context#km_core_state_context "km_core_state_context function" +[km_core_state_app_context]: context#km_core_state_app_context "km_core_state_app_context function" +[km_core_context_set]: context#km_core_context_set "km_core_context_set function" +[km_core_context_clear]: context#km_core_context_clear "km_core_context_clear function" +[km_core_context_item_list_size]: context#km_core_context_item_list_size "km_core_context_item_list_size function" +[km_core_context_get]: context#km_core_context_get "km_core_context_get function" +[km_core_context_length]: context#km_core_context_length "km_core_context_length function" +[km_core_modifier_state]: virtual-keys#km_core_modifier_state "km_core_modifier_state enum" +[km_core_virtual_key_value]: virtual-keys#km_core_virtual_key_value "km_core_virtual_key_value " \ No newline at end of file diff --git a/core/docs/api/keyhandling.md b/core/docs/api/keyhandling.md index 874a82ab87..397aacf70d 100644 --- a/core/docs/api/keyhandling.md +++ b/core/docs/api/keyhandling.md @@ -4,40 +4,43 @@ title: Keyhandling # Key Handling -While Keyman Core does not generally emit actions from key up events, -the `emit_keystroke` value for a key up event will match the corresponding -key down event, in order to avoid 'stuck key' scenarios'. +For each key press the processor will called twice, for the key down event +as well as for the key up event. Depending on the type of key pressed the +processor might handle the key itself or pass it on to the application. +The value of `emit_keystroke` in `km_core_actions` struct tells if the +processor handled the key (`emit_keystroke=0`) or not (`emit_keystroke=1`). +It is important that the same value gets set for both key down and key up +events, otherwise the application might miss some events which then looks +to the user like keys are stuck. Usually the processor won't handle any frame keys and let the application deal with it. This allows shortcut keys like Ctrl+C -to work. One exception is the Backspace key which is -handled internally if enough context is available. Keyboards can define -rules for other frame keys, e.g. Ctrl+Key which are then -also handled internally. Regular keys will be handled by the processor. +to work. The only exception is the Backspace key which is +handled internally if enough context is available. Regular keys will be +handled by the processor. Note that there is a difference between CLDR/LDML and KMN keyboards if there are no rules/transforms defined for a key: KMN keyboards will output the cap value of the key (e.g. pressing a will output `a` if no rule is defined), whereas CLDR/LDML keyboards will suppress -any output for that key. However, `km_core_actions.emit_keystroke` will -be `FALSE` for both KMN and CLR/LDML keyboards. +any output for that key. The following table lists the state of `km_core_actions.emit_keystroke` on return of `km_core_process_event` when the following type of key is pressed: -|Type | KeyDown/Up | -|-----------------------------|------------| -|Core key with rule | FALSE | -|Core key w/o rule | FALSE | -|Framekeys: | | -|Enter | TRUE | -|Backspace¹ | FALSE | -|Backspace² | TRUE | -|Ctrl+Key | TRUE | -|Modifier key Shift| TRUE | -|Modifier key Ctrl | TRUE | -|Modifier key LAlt | TRUE | +|Type | KeyDown | KeyUp | +|-----------------------------|---------------|----------| +|Key with rule | FALSE | FALSE | +|Key w/o rule | FALSE | FALSE | +|Framekeys: | | | +|Enter | TRUE | TRUE | +|Backspace¹ | FALSE | FALSE | +|Backspace² | TRUE | TRUE | +|Ctrl+Key | TRUE | TRUE | +|Modifier key Shift| TRUE | TRUE | +|Modifier key Ctrl | TRUE | TRUE | +|Modifier key LAlt | TRUE | TRUE | 1: context available
2: without or with empty context @@ -47,10 +50,10 @@ pressed: [km_core_usv]: background#km_core_usv "km_core_usv type" [km_core_virtual_key]: background#km_core_virtual_key "km_core_virtual_key type" [km_core_status]: background#km_core_status "km_core_status type" -[km_core_modifier_state]: background#km_core_modifier_state "km_core_modifier_state type" [km_core_keyboard]: background#km_core_keyboard "km_core_keyboard struct" [km_core_state]: background#km_core_state "km_core_state struct" [km_core_options]: background#km_core_options "km_core_options struct" +[km_core_keyboard_imx_platform]: background#km_core_keyboard_imx_platform "km_core_keyboard_imx_platform callback function" [km_core_status_codes]: background#km_core_status_codes "km_core_status_codes enum" [km_core_attr]: background#km_core_attr "km_core_attr struct" [km_core_tech_value]: background#km_core_tech_value "km_core_tech_value enum" @@ -65,6 +68,7 @@ pressed: [km_core_option_scope]: options#km_core_option_scope "km_core_option_scope enum" [km_core_option_item]: options#km_core_option_item "km_core_option_item struct" [km_core_options_list_size]: options#km_core_options_list_size "km_core_options_list_size function" +[km_core_state_option_lookup]: options#km_core_state_option_lookup "km_core_state_option_lookup function" [km_core_state_options_update]: options#km_core_state_options_update "km_core_state_options_update function" [km_core_keyboard_attrs]: keyboards#km_core_keyboard_attrs "km_core_keyboard_attrs struct" [km_core_keyboard_key]: keyboards#km_core_keyboard_key "km_core_keyboard_key struct" @@ -74,6 +78,7 @@ pressed: [km_core_keyboard_get_attrs]: keyboards#km_core_keyboard_get_attrs "km_core_keyboard_get_attrs function" [km_core_keyboard_get_key_list]: keyboards#km_core_keyboard_get_key_list "km_core_keyboard_get_key_list function" [km_core_keyboard_key_list_dispose]: keyboards#km_core_keyboard_key_list_dispose "km_core_keyboard_key_list_dispose function" +[km_core_keyboard_get_imx_list]: keyboards#km_core_keyboard_get_imx_list "km_core_keyboard_get_imx_list function" [km_core_keyboard_imx_list_dispose]: keyboards#km_core_keyboard_imx_list_dispose "km_core_keyboard_imx_list_dispose function" [km_core_state_imx_register_callback]: keyboards#km_core_state_imx_register_callback "km_core_state_imx_register_callback function" [km_core_state_imx_deregister_callback]: keyboards#km_core_state_imx_deregister_callback "km_core_state_imx_deregister_callback function" @@ -86,4 +91,22 @@ pressed: [km_core_event_flags]: processor#km_core_event_flags "km_core_event_flags enum" [km_core_process_event]: processor#km_core_process_event "km_core_process_event function" [km_core_event]: processor#km_core_event "km_core_event function" -[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" \ No newline at end of file +[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" +[km_core_action_item]: actions#km_core_action_item "km_core_action_item struct" +[km_core_state_action_items]: actions#km_core_state_action_items "km_core_state_action_items function" +[km_core_state_queue_action_items]: actions#km_core_state_queue_action_items "km_core_state_queue_action_items function" +[km_core_process_queued_actions]: actions#km_core_process_queued_actions "km_core_process_queued_actions function" +[km_core_context_type]: context#km_core_context_type "km_core_context_type enum" +[km_core_context_item]: context#km_core_context_item "km_core_context_item struct" +[KM_CORE_CONTEXT_ITEM_END]: context#KM_CORE_CONTEXT_ITEM_END "KM_CORE_CONTEXT_ITEM_END macro" +[km_core_state_get_intermediate_context]: context#km_core_state_get_intermediate_context "km_core_state_get_intermediate_context function" +[km_core_context_items_dispose]: context#km_core_context_items_dispose "km_core_context_items_dispose function" +[km_core_state_context]: context#km_core_state_context "km_core_state_context function" +[km_core_state_app_context]: context#km_core_state_app_context "km_core_state_app_context function" +[km_core_context_set]: context#km_core_context_set "km_core_context_set function" +[km_core_context_clear]: context#km_core_context_clear "km_core_context_clear function" +[km_core_context_item_list_size]: context#km_core_context_item_list_size "km_core_context_item_list_size function" +[km_core_context_get]: context#km_core_context_get "km_core_context_get function" +[km_core_context_length]: context#km_core_context_length "km_core_context_length function" +[km_core_modifier_state]: virtual-keys#km_core_modifier_state "km_core_modifier_state enum" +[km_core_virtual_key_value]: virtual-keys#km_core_virtual_key_value "km_core_virtual_key_value " \ No newline at end of file diff --git a/core/docs/api/options.md b/core/docs/api/options.md index 35c87bbda4..851d250aba 100644 --- a/core/docs/api/options.md +++ b/core/docs/api/options.md @@ -17,127 +17,89 @@ value. ------------------------------------------------------------------------------- + # km_core_option_scope enum {#km_core_option_scope} -## Description - -## Specification - ```c enum km_core_option_scope { + /** An unknown option type. Reserved. */ KM_CORE_OPT_UNKNOWN = 0, + /** An option that is defined for the currently active keyboard; not all + * processors support this type of option. These options are specific to the + * active keyboard. */ KM_CORE_OPT_KEYBOARD = 1, + /** Properties of the current environment, often but not necessarily always + * read-only. */ KM_CORE_OPT_ENVIRONMENT = 2, KM_CORE_OPT_MAX_SCOPES }; - ``` -## Values - -`KM_CORE_OPT_UNKNOWN` -: An unknown option type. Reserved. - -`KM_CORE_OPT_KEYBOARD` -: An option that is defined for the currently active keyboard; - not all processors support this type of option. These options - are specific to the active keyboard. - -`KM_CORE_OPT_ENVIRONMENT` -: Properties of the current environment, often but not necessarily - always read-only. - -------------------------------------------------------------------------------- # km_core_option_item struct {#km_core_option_item} -## Description +Defines a single option to be passed into the Keyman Core from the Platform +layer. -Defines a single option to be passed into the Keyman Core from the -Platform layer. - -## Specification ```c struct km_core_option_item { + /** Null-terminated string key for the option */ km_core_cu const * key; + /** Null-terminated string value for the option */ km_core_cu const * value; + /** Scope which an option belongs to, from [km_core_option_scope]. */ uint8_t scope; }; - #define KM_CORE_OPTIONS_END { 0, 0, 0 } ``` -## Members -`key` -: Null-terminated string key for the option +# km_core_options_list_size function {#km_core_options_list_size} -`value` -: Null-terminated string value for the option - -`scope` -: Scope which an option belongs to, from [km_core_option_scope]. - -------------------------------------------------------------------------------- - -# km_core_options_list_size() {#km_core_options_list_size} - -## Description Return the length of a terminated [km_core_option_item] array (options list). -## Specification + +## Parameters + +### opts +A pointer to a `KM_CORE_OPTIONS_END` terminated array of +[km_core_option_item] values. + +## Returns +The number of items in the list, not including terminating +item, or 0 if `opts` is null. + ```c KMN_API size_t km_core_options_list_size(km_core_option_item const *opts); - ``` -## Parameters -`opts` -: A pointer to a `KM_CORE_OPTIONS_END` terminated array of - [km_core_option_item] values. - -## Returns - -The number of items in the list, not including terminating item, -or 0 if `opts` is null. - -------------------------------------------------------------------------------- - -# km_core_state_option_lookup - -## Description +# km_core_state_option_lookup function {#km_core_state_option_lookup} Lookup an option based on its key, in an options list. -## Specification -```c -KMN_API -km_core_status -km_core_state_option_lookup(km_core_state const *state, - uint8_t scope, - km_core_cu const *key, - km_core_cu const **value); -``` ## Parameters -`state` -: An opaque pointer to a state object. +### state +An opaque pointer to a state object. -`scope` -: Which key-value store to interrogate. +### scope +Which key-value store to interrogate. -`key` -: A UTF-16 string that matches the key in the target [km_core_option_item]. +### key +A UTF-16 string that matches the key in the target + +### value +A pointer to the result variable: A pointer to a UTF-16 +string value owned by the state or keyboard object at the +time of the call. This pointer is only valid *until* the next +call to any function on this API and should be used +immediately. -`value` -: A pointer to the result variable: A pointer to a UTF-16 string value owned - by the state or keyboard object at the time of the call. This pointer is - only valid *until* the next call to any function on this API and should be - used immediately. ## Returns +One of the following values: `KM_CORE_STATUS_OK` : On success. @@ -148,31 +110,33 @@ km_core_state_option_lookup(km_core_state const *state, `KM_CORE_STATUS_KEY_ERROR` : The key cannot be found. -------------------------------------------------------------------------------- +```c +KMN_API +km_core_status +km_core_state_option_lookup( + km_core_state const *state, + uint8_t scope, + km_core_cu const *key, + km_core_cu const **value +); +``` -# km_core_state_options_update() {#km_core_state_options_update} - -## Description +# km_core_state_options_update function {#km_core_state_options_update} Adds or updates one or more options from a list of [km_core_option_item]s. -## Specification -``` */ -KMN_API -km_core_status -km_core_state_options_update(km_core_state *state, - km_core_option_item const *new_opts); -``` ## Parameters -`state` -: An opaque pointer to a state object. -`new_opts` -: An array of [km_core_option_item] objects to update or add. Must be - terminated with `KM_CORE_OPTIONS_END`. +### state +An opaque pointer to a state object. + +### new_opts +An array of [km_core_option_item] objects to update or add. +Must be terminated with `KM_CORE_OPTIONS_END`. ## Returns +One of the following values: `KM_CORE_STATUS_OK` : On success. @@ -186,17 +150,23 @@ km_core_state_options_update(km_core_state *state, `KM_CORE_STATUS_KEY_ERROR` : The key cannot be found. -------------------------------------------------------------------------------- - +```c +KMN_API +km_core_status +km_core_state_options_update( + km_core_state *state, + km_core_option_item const *new_opts +); +``` [km_core_cu]: background#km_core_cu "km_core_cu type" [km_core_usv]: background#km_core_usv "km_core_usv type" [km_core_virtual_key]: background#km_core_virtual_key "km_core_virtual_key type" [km_core_status]: background#km_core_status "km_core_status type" -[km_core_modifier_state]: background#km_core_modifier_state "km_core_modifier_state type" [km_core_keyboard]: background#km_core_keyboard "km_core_keyboard struct" [km_core_state]: background#km_core_state "km_core_state struct" [km_core_options]: background#km_core_options "km_core_options struct" +[km_core_keyboard_imx_platform]: background#km_core_keyboard_imx_platform "km_core_keyboard_imx_platform callback function" [km_core_status_codes]: background#km_core_status_codes "km_core_status_codes enum" [km_core_attr]: background#km_core_attr "km_core_attr struct" [km_core_tech_value]: background#km_core_tech_value "km_core_tech_value enum" @@ -211,6 +181,7 @@ km_core_state_options_update(km_core_state *state, [km_core_option_scope]: options#km_core_option_scope "km_core_option_scope enum" [km_core_option_item]: options#km_core_option_item "km_core_option_item struct" [km_core_options_list_size]: options#km_core_options_list_size "km_core_options_list_size function" +[km_core_state_option_lookup]: options#km_core_state_option_lookup "km_core_state_option_lookup function" [km_core_state_options_update]: options#km_core_state_options_update "km_core_state_options_update function" [km_core_keyboard_attrs]: keyboards#km_core_keyboard_attrs "km_core_keyboard_attrs struct" [km_core_keyboard_key]: keyboards#km_core_keyboard_key "km_core_keyboard_key struct" @@ -220,6 +191,7 @@ km_core_state_options_update(km_core_state *state, [km_core_keyboard_get_attrs]: keyboards#km_core_keyboard_get_attrs "km_core_keyboard_get_attrs function" [km_core_keyboard_get_key_list]: keyboards#km_core_keyboard_get_key_list "km_core_keyboard_get_key_list function" [km_core_keyboard_key_list_dispose]: keyboards#km_core_keyboard_key_list_dispose "km_core_keyboard_key_list_dispose function" +[km_core_keyboard_get_imx_list]: keyboards#km_core_keyboard_get_imx_list "km_core_keyboard_get_imx_list function" [km_core_keyboard_imx_list_dispose]: keyboards#km_core_keyboard_imx_list_dispose "km_core_keyboard_imx_list_dispose function" [km_core_state_imx_register_callback]: keyboards#km_core_state_imx_register_callback "km_core_state_imx_register_callback function" [km_core_state_imx_deregister_callback]: keyboards#km_core_state_imx_deregister_callback "km_core_state_imx_deregister_callback function" @@ -232,4 +204,22 @@ km_core_state_options_update(km_core_state *state, [km_core_event_flags]: processor#km_core_event_flags "km_core_event_flags enum" [km_core_process_event]: processor#km_core_process_event "km_core_process_event function" [km_core_event]: processor#km_core_event "km_core_event function" -[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" \ No newline at end of file +[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" +[km_core_action_item]: actions#km_core_action_item "km_core_action_item struct" +[km_core_state_action_items]: actions#km_core_state_action_items "km_core_state_action_items function" +[km_core_state_queue_action_items]: actions#km_core_state_queue_action_items "km_core_state_queue_action_items function" +[km_core_process_queued_actions]: actions#km_core_process_queued_actions "km_core_process_queued_actions function" +[km_core_context_type]: context#km_core_context_type "km_core_context_type enum" +[km_core_context_item]: context#km_core_context_item "km_core_context_item struct" +[KM_CORE_CONTEXT_ITEM_END]: context#KM_CORE_CONTEXT_ITEM_END "KM_CORE_CONTEXT_ITEM_END macro" +[km_core_state_get_intermediate_context]: context#km_core_state_get_intermediate_context "km_core_state_get_intermediate_context function" +[km_core_context_items_dispose]: context#km_core_context_items_dispose "km_core_context_items_dispose function" +[km_core_state_context]: context#km_core_state_context "km_core_state_context function" +[km_core_state_app_context]: context#km_core_state_app_context "km_core_state_app_context function" +[km_core_context_set]: context#km_core_context_set "km_core_context_set function" +[km_core_context_clear]: context#km_core_context_clear "km_core_context_clear function" +[km_core_context_item_list_size]: context#km_core_context_item_list_size "km_core_context_item_list_size function" +[km_core_context_get]: context#km_core_context_get "km_core_context_get function" +[km_core_context_length]: context#km_core_context_length "km_core_context_length function" +[km_core_modifier_state]: virtual-keys#km_core_modifier_state "km_core_modifier_state enum" +[km_core_virtual_key_value]: virtual-keys#km_core_virtual_key_value "km_core_virtual_key_value " \ No newline at end of file diff --git a/core/docs/api/processor.md b/core/docs/api/processor.md index f03e05e99c..a09a4fe2b0 100644 --- a/core/docs/api/processor.md +++ b/core/docs/api/processor.md @@ -2,70 +2,50 @@ title: Processor - Keyman Core API --- + # km_core_event_flags enum {#km_core_event_flags} -## Description - -Bit flags to be used with the `event_flags` parameter of [km_core_process_event] - -## Specification +Bit flags to be used with the `event_flags` parameter of +[km_core_process_event]. ```c enum km_core_event_flags { + /** default value: hardware */ KM_CORE_EVENT_FLAG_DEFAULT = 0, + /** set if the event is touch, otherwise hardware */ KM_CORE_EVENT_FLAG_TOUCH = 1, }; - ``` -## Values -`KM_CORE_EVENT_FLAG_DEFAULT` -: default value: hardware +# km_core_process_event function {#km_core_process_event} -`KM_CORE_EVENT_FLAG_TOUCH` -: set if the event is touch, otherwise hardware +Run the keyboard on an opaque state object with the provided virtual key and +modifer key state. Updates the state object as appropriate and fills out its +internal set of actions, which can be retrieved with +[km_core_state_get_actions]. -------------------------------------------------------------------------------- +The state's actions will be cleared at the start of this call; options and +context in the state may also be modified. -# km_core_process_event() {#km_core_process_event} -## Description - -Run the keyboard on an opaque state object with the provided virtual key and modifer -key state. Updates the state object as appropriate and fills out its internal set -of actions, which can be retrieved with [km_core_state_get_actions]. - -The state's actions will be cleared at the start of this call; options and context in -the state may also be modified. - -## Specification - -```c -KMN_API -km_core_status -km_core_process_event(km_core_state *state, - km_core_virtual_key vk, - uint16_t modifier_state, - uint8_t is_key_down, - uint16_t event_flags); - -``` ## Parameters -`state` -: A pointer to the opaque state object. +### state +A pointer to the opaque state object. -`vk` -: A virtual key to be processed. +### vk +A virtual key to be processed. -`modifier_state` -: The combinations of modifier keys set at the time key `vk` was pressed, bitmask - from the [km_core_modifier_state] enum. +### modifier_state +The combinations of modifier keys set at the time key +`vk` was pressed, bitmask from the +[km_core_modifier_state] enum. -`event_flags` -: Event level flags, see [km_core_event_flags] +### event_flags +Event level flags, see [km_core_event_flags] ## Returns +One of the following values: `KM_CORE_STATUS_OK` : On success. @@ -74,17 +54,25 @@ km_core_process_event(km_core_state *state, : In the event memory is unavailable to allocate internal buffers. `KM_CORE_STATUS_INVALID_ARGUMENT` -: In the event the `state` pointer is null or an invalid virtual key or modifier - state is passed. +: In the event the `state` pointer is null or an invalid virtual key or +modifier state is passed. -------------------------------------------------------------------------------- +```c +KMN_API +km_core_status +km_core_process_event( + km_core_state const *state, + km_core_virtual_key vk, + uint16_t modifier_state, + uint8_t is_key_down, + uint16_t event_flags +); +``` -# km_core_event() {#km_core_event} +# km_core_event function {#km_core_event} -## Description - -Tell the keyboard processor that an external event has occurred, such as a keyboard -being activated through the language switching UI. +Tell the keyboard processor that an external event has occurred, such as a +keyboard being activated through the language switching UI. The keyboard processor may generate actions which should be processed by the consumer of the API. @@ -92,30 +80,22 @@ consumer of the API. The actions will be cleared at the start of this call; options and context in the state may also be modified. -## Specification -```c -KMN_API -km_core_status -km_core_event( - km_core_state *state, - uint32_t event, - void* data -); - -``` ## Parameters -`state` -: A pointer to the opaque state object. +### state +A pointer to the opaque state object. -`event` -: The event to be processed, from [km_core_event_code] enumeration +### event +The event to be processed, from [km_core_event_code] +enumeration -`data` -: Additional event-specific data. Currently unused, must be nullptr. +### data +Additional event-specific data. Currently unused, must be +nullptr. ## Returns +One of the following values: `KM_CORE_STATUS_OK` : On success. @@ -124,40 +104,39 @@ km_core_event( : In the event memory is unavailable to allocate internal buffers. `KM_CORE_STATUS_INVALID_ARGUMENT` -: In the event the `state` pointer is null or an invalid event or data is passed. +: In the event the `state` pointer is null or an invalid event or data is +passed. -------------------------------------------------------------------------------- +```c +KMN_API +km_core_status +km_core_event( + km_core_state const *state, + uint32_t event, + void* data +); +``` # km_core_event_code enum {#km_core_event_code} -## Description - Possible events to be passed into Keyman Core from the Platform layer. -## Specification - ```c enum km_core_event_code { + /** A keyboard has been activated by the user. The processor may use this + * event, for example, to switch caps lock state or provide other UX. */ KM_CORE_EVENT_KEYBOARD_ACTIVATED = 1, - //future: KM_CORE_EVENT_KEYBOARD_DEACTIVATED = 2, }; - -``` -## Values - -`KM_CORE_EVENT_KEYBOARD_ACTIVATED` -: A keyboard has been activated by the user. The processor may use this - event, for example, to switch caps lock state or provide other UX. - +/* [km_core_cu]: background#km_core_cu "km_core_cu type" [km_core_usv]: background#km_core_usv "km_core_usv type" [km_core_virtual_key]: background#km_core_virtual_key "km_core_virtual_key type" [km_core_status]: background#km_core_status "km_core_status type" -[km_core_modifier_state]: background#km_core_modifier_state "km_core_modifier_state type" [km_core_keyboard]: background#km_core_keyboard "km_core_keyboard struct" [km_core_state]: background#km_core_state "km_core_state struct" [km_core_options]: background#km_core_options "km_core_options struct" +[km_core_keyboard_imx_platform]: background#km_core_keyboard_imx_platform "km_core_keyboard_imx_platform callback function" [km_core_status_codes]: background#km_core_status_codes "km_core_status_codes enum" [km_core_attr]: background#km_core_attr "km_core_attr struct" [km_core_tech_value]: background#km_core_tech_value "km_core_tech_value enum" @@ -172,6 +151,7 @@ enum km_core_event_code { [km_core_option_scope]: options#km_core_option_scope "km_core_option_scope enum" [km_core_option_item]: options#km_core_option_item "km_core_option_item struct" [km_core_options_list_size]: options#km_core_options_list_size "km_core_options_list_size function" +[km_core_state_option_lookup]: options#km_core_state_option_lookup "km_core_state_option_lookup function" [km_core_state_options_update]: options#km_core_state_options_update "km_core_state_options_update function" [km_core_keyboard_attrs]: keyboards#km_core_keyboard_attrs "km_core_keyboard_attrs struct" [km_core_keyboard_key]: keyboards#km_core_keyboard_key "km_core_keyboard_key struct" @@ -181,6 +161,7 @@ enum km_core_event_code { [km_core_keyboard_get_attrs]: keyboards#km_core_keyboard_get_attrs "km_core_keyboard_get_attrs function" [km_core_keyboard_get_key_list]: keyboards#km_core_keyboard_get_key_list "km_core_keyboard_get_key_list function" [km_core_keyboard_key_list_dispose]: keyboards#km_core_keyboard_key_list_dispose "km_core_keyboard_key_list_dispose function" +[km_core_keyboard_get_imx_list]: keyboards#km_core_keyboard_get_imx_list "km_core_keyboard_get_imx_list function" [km_core_keyboard_imx_list_dispose]: keyboards#km_core_keyboard_imx_list_dispose "km_core_keyboard_imx_list_dispose function" [km_core_state_imx_register_callback]: keyboards#km_core_state_imx_register_callback "km_core_state_imx_register_callback function" [km_core_state_imx_deregister_callback]: keyboards#km_core_state_imx_deregister_callback "km_core_state_imx_deregister_callback function" @@ -193,4 +174,22 @@ enum km_core_event_code { [km_core_event_flags]: processor#km_core_event_flags "km_core_event_flags enum" [km_core_process_event]: processor#km_core_process_event "km_core_process_event function" [km_core_event]: processor#km_core_event "km_core_event function" -[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" \ No newline at end of file +[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" +[km_core_action_item]: actions#km_core_action_item "km_core_action_item struct" +[km_core_state_action_items]: actions#km_core_state_action_items "km_core_state_action_items function" +[km_core_state_queue_action_items]: actions#km_core_state_queue_action_items "km_core_state_queue_action_items function" +[km_core_process_queued_actions]: actions#km_core_process_queued_actions "km_core_process_queued_actions function" +[km_core_context_type]: context#km_core_context_type "km_core_context_type enum" +[km_core_context_item]: context#km_core_context_item "km_core_context_item struct" +[KM_CORE_CONTEXT_ITEM_END]: context#KM_CORE_CONTEXT_ITEM_END "KM_CORE_CONTEXT_ITEM_END macro" +[km_core_state_get_intermediate_context]: context#km_core_state_get_intermediate_context "km_core_state_get_intermediate_context function" +[km_core_context_items_dispose]: context#km_core_context_items_dispose "km_core_context_items_dispose function" +[km_core_state_context]: context#km_core_state_context "km_core_state_context function" +[km_core_state_app_context]: context#km_core_state_app_context "km_core_state_app_context function" +[km_core_context_set]: context#km_core_context_set "km_core_context_set function" +[km_core_context_clear]: context#km_core_context_clear "km_core_context_clear function" +[km_core_context_item_list_size]: context#km_core_context_item_list_size "km_core_context_item_list_size function" +[km_core_context_get]: context#km_core_context_get "km_core_context_get function" +[km_core_context_length]: context#km_core_context_length "km_core_context_length function" +[km_core_modifier_state]: virtual-keys#km_core_modifier_state "km_core_modifier_state enum" +[km_core_virtual_key_value]: virtual-keys#km_core_virtual_key_value "km_core_virtual_key_value " \ No newline at end of file diff --git a/core/docs/api/state.md b/core/docs/api/state.md index dca2075007..db45b54d33 100644 --- a/core/docs/api/state.md +++ b/core/docs/api/state.md @@ -11,161 +11,107 @@ owned by the state object. ------------------------------------------------------------------------------- -# km_core_caps_state enum {#km_core_caps_state} -## Description +# km_core_caps_state enum {#km_core_caps_state} Describes a change to the hardware caps lock indicator state requested by Keyman Core to the Platform layer. -## Specification ```c -typedef enum { KM_CORE_CAPS_UNCHANGED = -1, KM_CORE_CAPS_OFF = 0, KM_CORE_CAPS_ON = 1 } km_core_caps_state; - +typedef enum { + /** Caps lock state has not changed in this event. */ + KM_CORE_CAPS_UNCHANGED = -1, + /** As a result of processing this event, the Platform layer should switch off + * Caps Lock on the hardware keyboard. */ + KM_CORE_CAPS_OFF = 0, + /** As a result of processing this event, the Platform layer should switch on + * Caps Lock on the hardware keyboard.*/ + KM_CORE_CAPS_ON = 1 +} km_core_caps_state; ``` -## Values - -`KM_CORE_CAPS_UNCHANGED` -: Caps lock state has not changed in this event. - -`KM_CORE_CAPS_OFF` -: As a result of processing this event, the Platform layer should switch off - Caps Lock on the hardware keyboard. - -`KM_CORE_CAPS_ON` -: As a result of processing this event, the Platform layer should switch on - Caps Lock on the hardware keyboard. - -------------------------------------------------------------------------------- # km_core_actions struct {#km_core_actions} -## Description - -This structure provides the results of processing a key event to the Platform layer and -should be processed by the Platform layer to issue commands to the os text -services framework to transform the text store in the Client Application, among -other actions. +This structure provides the results of processing a key event to the Platform +layer and should be processed by the Platform layer to issue commands to the +os text services framework to transform the text store in the Client +Application, among other actions. This API replaces the Action items APIs, which are now deprecated and will be removed in the future. -## Specification ```c typedef struct { + /** Number of codepoints (not codeunits!) to delete from app context. */ unsigned int code_points_to_delete; + /** Null-term string of characters to insert into document. */ const km_core_usv* output; + /** List of options to persist, terminated with `KM_CORE_OPTIONS_END`. */ km_core_option_item * persist_options; + /** Issue a beep, 0 = no, 1 = yes. */ km_core_bool do_alert; + /** Emit the (unmodified) input keystroke to the application, 0 = no, 1 = yes. + * On most platforms this signals whether the processor handled the event (0) + * or not (1). See also [key handling](keyhandling). */ km_core_bool emit_keystroke; + /** -1=unchanged, 0=off, 1=on */ km_core_caps_state new_caps_lock_state; + /** Reference copy of actual UTF32 codepoints deleted from end of context + * (closest to caret) exactly `code_points_to_delete` in length (plus null + * terminator). Used to determine encoding conversion differences when + * deleting; only set when using [km_core_state_get_actions], otherwise + * `nullptr`. */ const km_core_usv* deleted_context; } km_core_actions; - ``` -## Members -`code_points_to_delete` -: Number of codepoints (not codeunits!) to delete from app context. +# km_core_state_get_actions function {#km_core_state_get_actions} -`output` -: Null-term string of characters to insert into document. +Returns a pointer to an actions object which details all the actions that the +Platform layer must take after a keystroke. The `code_points_to_delete` +action must be performed before the `output` action, but the other actions +may be performed in any order. -`persist_options` -: List of options to persist, terminated with `KM_CORE_OPTIONS_END`. -`do_alert` -: Issue a beep, 0 = no, 1 = yes. +## Parameters -`emit_keystroke` -: Emit the (unmodified) input keystroke to the application, 0 = no, 1 = yes. - On most platforms this signals whether the processor handled the event - (0) or not (1). See also [key handling](keyhandling). +### state +An opaque pointer to a state object. -`new_caps_lock_state` -: -1=unchanged, 0=off, 1=on +## Returns +A pointer to a [km_core_actions] object. This data becomes invalid +when the state object is destroyed, or after a call to +[km_core_process_event]. Do not modify the contents of this data. -`deleted_context` -: Reference copy of actual UTF32 codepoints deleted from end of context - (closest to caret) exactly `code_points_to_delete` in length (plus null - terminator). Used to determine encoding conversion differences when - deleting; only set when using [km_core_state_get_actions], otherwise `nullptr`. - -------------------------------------------------------------------------------- - -# km_core_state_get_actions() {#km_core_state_get_actions} - -## Description - -Returns a pointer to an actions object which details all the actions -that the Platform layer must take after a keystroke. The `code_points_to_delete` -action must be performed before the `output` action, but the other -actions may be performed in any order. - -## Specification ```c KMN_API km_core_actions const * km_core_state_get_actions( km_core_state const *state ); - ``` -## Parameters - -`state` -: An opaque pointer to a state object. - -## Returns - -A pointer to a [km_core_actions] object. This data becomes invalid -when the state object is destroyed, or after a call to -[km_core_process_event]. Do not modify the contents of this data. - -------------------------------------------------------------------------------- # km_core_context_status enum {#km_core_context_status} -## Description - Return values for [km_core_state_context_set_if_needed]. -## Specification - ```c typedef enum { + /** Cached context change was not needed. */ KM_CORE_CONTEXT_STATUS_UNCHANGED = 0, + /** Cached context was set to application context. */ KM_CORE_CONTEXT_STATUS_UPDATED = 1, + /** Application context was invalid, perhaps had unpaired surrogates, and so + * cached context was cleared instead. */ KM_CORE_CONTEXT_STATUS_CLEARED = 2, + /** Internal error. */ KM_CORE_CONTEXT_STATUS_ERROR = 3, + /** One or more parameters was null. */ KM_CORE_CONTEXT_STATUS_INVALID_ARGUMENT = 4, } km_core_context_status; - ``` -## Values - -`KM_CORE_CONTEXT_STATUS_UNCHANGED` -: Cached context change was not needed. - -`KM_CORE_CONTEXT_STATUS_UPDATED` -: Cached context was set to application context. - -`KM_CORE_CONTEXT_STATUS_CLEARED` -: Application context was invalid, perhaps had unpaired surrogates, - and so cached context was cleared instead. - -`KM_CORE_CONTEXT_STATUS_ERROR` -: Internal error. - -`KM_CORE_CONTEXT_STATUS_INVALID_ARGUMENT` -: One or more parameters was null. - -------------------------------------------------------------------------------- - -# km_core_state_context_set_if_needed() {#km_core_state_context_set_if_needed} - -## Description +# km_core_state_context_set_if_needed function {#km_core_state_context_set_if_needed} Sets the internal cached context for the state object, to the passed-in application context string, if it differs from the codepoints in the @@ -180,7 +126,20 @@ application context, and thus any cached markers will be cleared. [km_core_state_context_set_if_needed] and [km_core_state_context_clear] will replace most uses of the existing Core context APIs. -## Specification + +## Parameters + +### state +An opaque pointer to a state object. + +### application_context +A pointer to an null-terminated array of utf16 +encoded data representing the current context +from the application. + +## Returns +A value from the [km_core_context_status] enum. + ```c KMN_API km_core_context_status @@ -188,26 +147,10 @@ km_core_state_context_set_if_needed( km_core_state *state, km_core_cu const *application_context ); - ``` -## Parameters -`state` -: An opaque pointer to a state object. -`application_context` -: A pointer to an null-terminated array of utf16 encoded data representing - the current context from the application. - -## Returns - -A value from the [km_core_context_status] enum. - -------------------------------------------------------------------------------- - -# km_core_state_context_clear() {#km_core_state_context_clear} - -## Description +# km_core_state_context_clear function {#km_core_state_context_clear} Clears the internal cached context for the state. This is the same as `km_core_context_clear(km_core_state_context(&state))`. @@ -215,21 +158,14 @@ Clears the internal cached context for the state. This is the same as [km_core_state_context_set_if_needed] and [km_core_state_context_clear] will replace most uses of the existing Core context APIs. -## Specification -```c -KMN_API -km_core_status -km_core_state_context_clear( - km_core_state *state -); -``` ## Parameters -`state`: +### state An opaque pointer to a state object. ## Returns +One of the following values: `KM_CORE_STATUS_OK` : On success. @@ -237,17 +173,22 @@ An opaque pointer to a state object. `KM_CORE_STATUS_INVALID_ARGUMENT` : If any parameters are null. -------------------------------------------------------------------------------- - +```c +KMN_API +km_core_status +km_core_state_context_clear( + km_core_state *state +); +``` [km_core_cu]: background#km_core_cu "km_core_cu type" [km_core_usv]: background#km_core_usv "km_core_usv type" [km_core_virtual_key]: background#km_core_virtual_key "km_core_virtual_key type" [km_core_status]: background#km_core_status "km_core_status type" -[km_core_modifier_state]: background#km_core_modifier_state "km_core_modifier_state type" [km_core_keyboard]: background#km_core_keyboard "km_core_keyboard struct" [km_core_state]: background#km_core_state "km_core_state struct" [km_core_options]: background#km_core_options "km_core_options struct" +[km_core_keyboard_imx_platform]: background#km_core_keyboard_imx_platform "km_core_keyboard_imx_platform callback function" [km_core_status_codes]: background#km_core_status_codes "km_core_status_codes enum" [km_core_attr]: background#km_core_attr "km_core_attr struct" [km_core_tech_value]: background#km_core_tech_value "km_core_tech_value enum" @@ -262,6 +203,7 @@ An opaque pointer to a state object. [km_core_option_scope]: options#km_core_option_scope "km_core_option_scope enum" [km_core_option_item]: options#km_core_option_item "km_core_option_item struct" [km_core_options_list_size]: options#km_core_options_list_size "km_core_options_list_size function" +[km_core_state_option_lookup]: options#km_core_state_option_lookup "km_core_state_option_lookup function" [km_core_state_options_update]: options#km_core_state_options_update "km_core_state_options_update function" [km_core_keyboard_attrs]: keyboards#km_core_keyboard_attrs "km_core_keyboard_attrs struct" [km_core_keyboard_key]: keyboards#km_core_keyboard_key "km_core_keyboard_key struct" @@ -271,6 +213,7 @@ An opaque pointer to a state object. [km_core_keyboard_get_attrs]: keyboards#km_core_keyboard_get_attrs "km_core_keyboard_get_attrs function" [km_core_keyboard_get_key_list]: keyboards#km_core_keyboard_get_key_list "km_core_keyboard_get_key_list function" [km_core_keyboard_key_list_dispose]: keyboards#km_core_keyboard_key_list_dispose "km_core_keyboard_key_list_dispose function" +[km_core_keyboard_get_imx_list]: keyboards#km_core_keyboard_get_imx_list "km_core_keyboard_get_imx_list function" [km_core_keyboard_imx_list_dispose]: keyboards#km_core_keyboard_imx_list_dispose "km_core_keyboard_imx_list_dispose function" [km_core_state_imx_register_callback]: keyboards#km_core_state_imx_register_callback "km_core_state_imx_register_callback function" [km_core_state_imx_deregister_callback]: keyboards#km_core_state_imx_deregister_callback "km_core_state_imx_deregister_callback function" @@ -283,4 +226,22 @@ An opaque pointer to a state object. [km_core_event_flags]: processor#km_core_event_flags "km_core_event_flags enum" [km_core_process_event]: processor#km_core_process_event "km_core_process_event function" [km_core_event]: processor#km_core_event "km_core_event function" -[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" \ No newline at end of file +[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" +[km_core_action_item]: actions#km_core_action_item "km_core_action_item struct" +[km_core_state_action_items]: actions#km_core_state_action_items "km_core_state_action_items function" +[km_core_state_queue_action_items]: actions#km_core_state_queue_action_items "km_core_state_queue_action_items function" +[km_core_process_queued_actions]: actions#km_core_process_queued_actions "km_core_process_queued_actions function" +[km_core_context_type]: context#km_core_context_type "km_core_context_type enum" +[km_core_context_item]: context#km_core_context_item "km_core_context_item struct" +[KM_CORE_CONTEXT_ITEM_END]: context#KM_CORE_CONTEXT_ITEM_END "KM_CORE_CONTEXT_ITEM_END macro" +[km_core_state_get_intermediate_context]: context#km_core_state_get_intermediate_context "km_core_state_get_intermediate_context function" +[km_core_context_items_dispose]: context#km_core_context_items_dispose "km_core_context_items_dispose function" +[km_core_state_context]: context#km_core_state_context "km_core_state_context function" +[km_core_state_app_context]: context#km_core_state_app_context "km_core_state_app_context function" +[km_core_context_set]: context#km_core_context_set "km_core_context_set function" +[km_core_context_clear]: context#km_core_context_clear "km_core_context_clear function" +[km_core_context_item_list_size]: context#km_core_context_item_list_size "km_core_context_item_list_size function" +[km_core_context_get]: context#km_core_context_get "km_core_context_get function" +[km_core_context_length]: context#km_core_context_length "km_core_context_length function" +[km_core_modifier_state]: virtual-keys#km_core_modifier_state "km_core_modifier_state enum" +[km_core_virtual_key_value]: virtual-keys#km_core_virtual_key_value "km_core_virtual_key_value " \ No newline at end of file diff --git a/core/docs/api/virtual-keys.md b/core/docs/api/virtual-keys.md new file mode 100644 index 0000000000..8ca085d0df --- /dev/null +++ b/core/docs/api/virtual-keys.md @@ -0,0 +1,386 @@ +--- +title: Virtual Keys - Keyman Core API +--- + +API declarations for modifier keys, handy access masks and Keyman VKEY names. +These follow the same keytop->code associations as the Windows API. This is a +separate header to maintain readability of the primary API header. + + +# km_core_modifier_state enum {#km_core_modifier_state} + +An integral type bitmask representing the state of each modifier key. + +```c +enum km_core_modifier_state { + KM_CORE_MODIFIER_NONE = 0, + KM_CORE_MODIFIER_LCTRL = 1 << 0, + KM_CORE_MODIFIER_RCTRL = 1 << 1, + KM_CORE_MODIFIER_LALT = 1 << 2, + KM_CORE_MODIFIER_RALT = 1 << 3, + KM_CORE_MODIFIER_SHIFT = 1 << 4, + KM_CORE_MODIFIER_CTRL = 1 << 5, + KM_CORE_MODIFIER_ALT = 1 << 6, + /* + KM_CORE_MODIFIER_META = 1 << 7, // Either Meta-key flag (tentative). Not usable by keyboards currently + */ + KM_CORE_MODIFIER_CAPS = 1 << 8, + KM_CORE_MODIFIER_NOCAPS = 1 << 9, + /* + KM_CORE_MODIFIER_NUMLOCK = 1 << 10, + KM_CORE_MODIFIER_NONUMLOCK = 1 << 11, + KM_CORE_MODIFIER_SCROLLOCK = 1 << 12, + KM_CORE_MODIFIER_NOSCROLLOCK = 1 << 13, + KM_CORE_MODIFIER_VIRTUALKEY = 1 << 14, + */ +}; +``` +An integral type bitmask representing common bitmask sets for +km_core_modifier_state + +```c +enum km_core_modifier_mask { + KM_CORE_MODIFIER_MASK_ALL = 0x7f, + KM_CORE_MODIFIER_MASK_ALT_GR_SIM = KM_CORE_MODIFIER_LCTRL|KM_CORE_MODIFIER_LALT, + KM_CORE_MODIFIER_MASK_CHIRAL = 0x1f, + KM_CORE_MODIFIER_MASK_IS_CHIRAL = 0x0f, + KM_CORE_MODIFIER_MASK_NON_CHIRAL = 0x7f, + KM_CORE_MODIFIER_MASK_CAPS = 0x0300, +/*KM_CORE_MODIFIER_MASK_NUMLOCK = 0x0C00, + KM_CORE_MODIFIER_MASK_SCROLLLOCK = 0x3000,*/ +}; +``` + +# km_core_virtual_key_value {#km_core_virtual_key_value} + +These are Windows API VKEYs, using Keyman VKEY names. Underlying values from +winuser.h +(https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes) +Note, some codes are defined here for parity with winuser.h, but are not +available in .kmn language. These codes are marked as "internal" by using +`__` in the name: `KM_CORE_VKEY____` + +```c +enum km_core_virtual_key_value { + KM_CORE_VKEY__00, + KM_CORE_VKEY_LBUTTON, // 0x01 + KM_CORE_VKEY_RBUTTON, // 0x02 + KM_CORE_VKEY_CANCEL, // 0x03 + KM_CORE_VKEY_MBUTTON, // 0x04 + KM_CORE_VKEY__XBUTTON1__, // 0x05 + KM_CORE_VKEY__XBUTTON2__, // 0x06 + KM_CORE_VKEY__07, // 0x07 - Reserved + KM_CORE_VKEY_BKSP, // 0x08 - VK_BACK + KM_CORE_VKEY_TAB, // 0x09 + KM_CORE_VKEY__0A, // 0x0a - Reserved + KM_CORE_VKEY__0B, // 0x0b - Reserved + KM_CORE_VKEY_KP5, // 0x0c - VK_CLEAR + KM_CORE_VKEY_ENTER, // 0x0d - VK_RETURN + KM_CORE_VKEY__0E, // 0x0e - Reserved + KM_CORE_VKEY__0F, // 0x0f - Reserved + KM_CORE_VKEY_SHIFT, // 0x10 + KM_CORE_VKEY_CONTROL, // 0x11 + KM_CORE_VKEY_ALT, // 0x12 - VK_MENU + KM_CORE_VKEY_PAUSE, // 0x13 + KM_CORE_VKEY_CAPS, // 0x14 - VK_CAPITAL + KM_CORE_VKEY__KANA__, // 0x15 + KM_CORE_VKEY__HANGUL__, // 0x16 + KM_CORE_VKEY__JUNJA__, // 0x17 + KM_CORE_VKEY__FINAL__, // 0x18 + KM_CORE_VKEY__HANJA__, // 0x19 - or VK_KANJI + KM_CORE_VKEY__IMEOFF__, // 0x1a - VK_IME_OFF + KM_CORE_VKEY_ESC, // 0x1b - VK_ESCAPE + KM_CORE_VKEY__CONVERT__, // 0x1c + KM_CORE_VKEY__NONCONVERT__, // 0x1d + KM_CORE_VKEY__ACCEPT__, // 0x1e + KM_CORE_VKEY__MODECHANGE__, // 0x1f + KM_CORE_VKEY_SPACE, // 0x20 + KM_CORE_VKEY_PGUP, // 0x21 - VK_PRIOR + KM_CORE_VKEY_PGDN, // 0x22 - VK_NEXT + KM_CORE_VKEY_END, // 0x23 + KM_CORE_VKEY_HOME, // 0x24 + KM_CORE_VKEY_LEFT, // 0x25 + KM_CORE_VKEY_UP, // 0x26 + KM_CORE_VKEY_RIGHT, // 0x27 + KM_CORE_VKEY_DOWN, // 0x28 + KM_CORE_VKEY_SEL, // 0x29 - VK_SELECT + KM_CORE_VKEY_PRINT, // 0x2a + KM_CORE_VKEY_EXEC, // 0x2b - VK_EXECUTE + KM_CORE_VKEY_PRTSCN, // 0x2c - VK_SNAPSHOT + KM_CORE_VKEY_INS, // 0x2d - VK_INSERT + KM_CORE_VKEY_DEL, // 0x2e - VK_DELETE + KM_CORE_VKEY_HELP, // 0x2f + KM_CORE_VKEY_0, // 0x30 + KM_CORE_VKEY_1, // 0x31 + KM_CORE_VKEY_2, // 0x32 + KM_CORE_VKEY_3, // 0x33 + KM_CORE_VKEY_4, // 0x34 + KM_CORE_VKEY_5, // 0x35 + KM_CORE_VKEY_6, // 0x36 + KM_CORE_VKEY_7, // 0x37 + KM_CORE_VKEY_8, // 0x38 + KM_CORE_VKEY_9, // 0x39 + KM_CORE_VKEY__3A, // 0x3a - undefined + KM_CORE_VKEY__3B, // 0x3b - undefined + KM_CORE_VKEY__3C, // 0x3c - undefined + KM_CORE_VKEY__3D, // 0x3d - undefined + KM_CORE_VKEY__3E, // 0x3e - undefined + KM_CORE_VKEY__3F, // 0x3f - undefined + KM_CORE_VKEY__40, // 0x40 - undefined + KM_CORE_VKEY_A, // 0x41 + KM_CORE_VKEY_B, // 0x42 + KM_CORE_VKEY_C, // 0x43 + KM_CORE_VKEY_D, // 0x44 + KM_CORE_VKEY_E, // 0x45 + KM_CORE_VKEY_F, // 0x46 + KM_CORE_VKEY_G, // 0x47 + KM_CORE_VKEY_H, // 0x48 + KM_CORE_VKEY_I, // 0x49 + KM_CORE_VKEY_J, // 0x4a + KM_CORE_VKEY_K, // 0x4b + KM_CORE_VKEY_L, // 0x4c + KM_CORE_VKEY_M, // 0x4d + KM_CORE_VKEY_N, // 0x4e + KM_CORE_VKEY_O, // 0x4f + KM_CORE_VKEY_P, // 0x50 + KM_CORE_VKEY_Q, // 0x51 + KM_CORE_VKEY_R, // 0x52 + KM_CORE_VKEY_S, // 0x53 + KM_CORE_VKEY_T, // 0x54 + KM_CORE_VKEY_U, // 0x55 + KM_CORE_VKEY_V, // 0x56 + KM_CORE_VKEY_W, // 0x57 + KM_CORE_VKEY_X, // 0x58 + KM_CORE_VKEY_Y, // 0x59 + KM_CORE_VKEY_Z, // 0x5a + KM_CORE_VKEY__LWIN__, // 0x5b + KM_CORE_VKEY__RWIN__, // 0x5c + KM_CORE_VKEY__APPS__, // 0x5d + KM_CORE_VKEY__5E, // 0x5e - reserved + KM_CORE_VKEY__SLEEP__, // 0x5f + KM_CORE_VKEY_NP0, // 0x60 - VK_NUMPAD0 + KM_CORE_VKEY_NP1, // 0x61 - VK_NUMPAD1 + KM_CORE_VKEY_NP2, // 0x62 - VK_NUMPAD2 + KM_CORE_VKEY_NP3, // 0x63 - VK_NUMPAD3 + KM_CORE_VKEY_NP4, // 0x64 - VK_NUMPAD4 + KM_CORE_VKEY_NP5, // 0x65 - VK_NUMPAD5 + KM_CORE_VKEY_NP6, // 0x66 - VK_NUMPAD6 + KM_CORE_VKEY_NP7, // 0x67 - VK_NUMPAD7 + KM_CORE_VKEY_NP8, // 0x68 - VK_NUMPAD8 + KM_CORE_VKEY_NP9, // 0x69 - VK_NUMPAD9 + KM_CORE_VKEY_NPSTAR, // 0x6a - VK_MULTIPLY + KM_CORE_VKEY_NPPLUS, // 0x6b - VK_ADD + KM_CORE_VKEY_SEPARATOR, // 0x6c + KM_CORE_VKEY_NPMINUS, // 0x6d - VK_SUBTRACT + KM_CORE_VKEY_NPDOT, // 0x6e - VK_DECIMAL + KM_CORE_VKEY_NPSLASH, // 0x6f - VK_DIVIDE + KM_CORE_VKEY_F1, // 0x70 + KM_CORE_VKEY_F2, // 0x71 + KM_CORE_VKEY_F3, // 0x72 + KM_CORE_VKEY_F4, // 0x73 + KM_CORE_VKEY_F5, // 0x74 + KM_CORE_VKEY_F6, // 0x75 + KM_CORE_VKEY_F7, // 0x76 + KM_CORE_VKEY_F8, // 0x77 + KM_CORE_VKEY_F9, // 0x78 + KM_CORE_VKEY_F10, // 0x79 + KM_CORE_VKEY_F11, // 0x7a + KM_CORE_VKEY_F12, // 0x7b + KM_CORE_VKEY_F13, // 0x7c + KM_CORE_VKEY_F14, // 0x7d + KM_CORE_VKEY_F15, // 0x7e + KM_CORE_VKEY_F16, // 0x7f + KM_CORE_VKEY_F17, // 0x80 + KM_CORE_VKEY_F18, // 0x81 + KM_CORE_VKEY_F19, // 0x82 + KM_CORE_VKEY_F20, // 0x83 + KM_CORE_VKEY_F21, // 0x84 + KM_CORE_VKEY_F22, // 0x85 + KM_CORE_VKEY_F23, // 0x86 + KM_CORE_VKEY_F24, // 0x87 + KM_CORE_VKEY__88, // 0x88 - reserved + KM_CORE_VKEY__89, // 0x89 - reserved + KM_CORE_VKEY__8A, // 0x8a - reserved + KM_CORE_VKEY__8B, // 0x8b - reserved + KM_CORE_VKEY__8C, // 0x8c - reserved + KM_CORE_VKEY__8D, // 0x8d - reserved + KM_CORE_VKEY__8E, // 0x8e - reserved + KM_CORE_VKEY__8F, // 0x8f - reserved + KM_CORE_VKEY_NUMLOCK, // 0x90 + KM_CORE_VKEY_SCROLL, // 0x91 + KM_CORE_VKEY__92, // 0x92 - OEM specific + KM_CORE_VKEY__93, // 0x93 - OEM specific + KM_CORE_VKEY__94, // 0x94 - OEM specific + KM_CORE_VKEY__95, // 0x95 - OEM specific + KM_CORE_VKEY__96, // 0x96 - OEM specific + KM_CORE_VKEY__97, // 0x97 - unassigned + KM_CORE_VKEY__98, // 0x98 - unassigned + KM_CORE_VKEY__99, // 0x99 - unassigned + KM_CORE_VKEY__9A, // 0x9a - unassigned + KM_CORE_VKEY__9B, // 0x9b - unassigned + KM_CORE_VKEY__9C, // 0x9c - unassigned + KM_CORE_VKEY__9D, // 0x9d - unassigned + KM_CORE_VKEY__9E, // 0x9e - unassigned + KM_CORE_VKEY__9F, // 0x9f - unassigned + KM_CORE_VKEY__LSHIFT__, // 0xa0 + KM_CORE_VKEY__RSHIFT__, // 0xa1 + KM_CORE_VKEY__LCONTROL__, // 0xa2 + KM_CORE_VKEY__RCONTROL__, // 0xa3 + KM_CORE_VKEY__LMENU__, // 0xa4 + KM_CORE_VKEY__RMENU__, // 0xa5 + KM_CORE_VKEY__BROWSERBACK__, // 0xa6 - VK_BROWSER_BACK + KM_CORE_VKEY__BROWSERFORWARD__, // 0xa7 - VK_BROWSER_FORWARD + KM_CORE_VKEY__BROWSERREFRESH__, // 0xa8 - VK_BROWSER_REFRESH + KM_CORE_VKEY__BROWSERSTOP__, // 0xa9 - VK_BROWSER_STOP + KM_CORE_VKEY__BROWSERSEARCH__, // 0xaa - VK_BROWSER_SEARCH + KM_CORE_VKEY_BROWSERFAVORITES, // 0xab - VK_BROWSER_FAVORITES + KM_CORE_VKEY__BROWSERHOME__, // 0xac - VK_BROWSER_HOME + KM_CORE_VKEY__VOLUMEMUTE__, // 0xad - VK_VOLUME_MUTE + KM_CORE_VKEY__VOLUMEDOWN__, // 0xae - VK_VOLUME_DOWN + KM_CORE_VKEY__VOLUMEUP__, // 0xaf - VK_VOLUME_UP + KM_CORE_VKEY__MEDIANEXT__, // 0xb0 - VK_MEDIA_NEXT_TRACK + KM_CORE_VKEY__MEDIAPREV__, // 0xb1 - VK_MEDIA_PREV_TRACK + KM_CORE_VKEY__MEDIASTOP__, // 0xb2 - VK_MEDIA_STOP + KM_CORE_VKEY__MEDIAPLAY__, // 0xb3 - VK_MEDIA_PLAY_PAUSE + KM_CORE_VKEY__MAIL__, // 0xb4 - VK_LAUNCH_MAIL + KM_CORE_VKEY__MEDIA__, // 0xb5 - VK_LAUNCH_MEDIA_SELECT + KM_CORE_VKEY__APP1__, // 0xb6 - VK_LAUNCH_APP1 + KM_CORE_VKEY__APP2__, // 0xb7 - VK_LAUNCH_APP2 + KM_CORE_VKEY__B8, // 0xb8 - reserved + KM_CORE_VKEY__B9, // 0xb9 - reserved + KM_CORE_VKEY_COLON, // 0xba - VK_OEM_1 + KM_CORE_VKEY_EQUAL, // 0xbb - VK_OEM_PLUS + KM_CORE_VKEY_COMMA, // 0xbc - VK_OEM_COMMA + KM_CORE_VKEY_HYPHEN, // 0xbd - VK_OEM_MINUS + KM_CORE_VKEY_PERIOD, // 0xbe - VK_OEM_PERIOD + KM_CORE_VKEY_SLASH, // 0xbf - VK_OEM_2 + KM_CORE_VKEY_BKQUOTE, // 0xc0 - VK_OEM_3 + KM_CORE_VKEY__C1, // 0xc1 - reserved + KM_CORE_VKEY__C2, // 0xc2 - reserved + KM_CORE_VKEY__C3, // 0xc3 - reserved + KM_CORE_VKEY__C4, // 0xc4 - reserved + KM_CORE_VKEY__C5, // 0xc5 - reserved + KM_CORE_VKEY__C6, // 0xc6 - reserved + KM_CORE_VKEY__C7, // 0xc7 - reserved + KM_CORE_VKEY__C8, // 0xc8 - reserved + KM_CORE_VKEY__C9, // 0xc9 - reserved + KM_CORE_VKEY__CA, // 0xca - reserved + KM_CORE_VKEY__CB, // 0xcb - reserved + KM_CORE_VKEY__CC, // 0xcc - reserved + KM_CORE_VKEY__CD, // 0xcd - reserved + KM_CORE_VKEY__CE, // 0xce - reserved + KM_CORE_VKEY__CF, // 0xcf - reserved + KM_CORE_VKEY__D0, // 0xd0 - reserved + KM_CORE_VKEY__D1, // 0xd1 - reserved + KM_CORE_VKEY__D2, // 0xd2 - reserved + KM_CORE_VKEY__D3, // 0xd3 - reserved + KM_CORE_VKEY__D4, // 0xd4 - reserved + KM_CORE_VKEY__D5, // 0xd5 - reserved + KM_CORE_VKEY__D6, // 0xd6 - reserved + KM_CORE_VKEY__D7, // 0xd7 - reserved + KM_CORE_VKEY__D8, // 0xd8 - reserved + KM_CORE_VKEY__D9, // 0xd9 - reserved + KM_CORE_VKEY__DA, // 0xda - reserved + KM_CORE_VKEY_LBRKT, // 0xdb - VK_OEM_4 + KM_CORE_VKEY_BKSLASH, // 0xdc - VK_OEM_5 + KM_CORE_VKEY_RBRKT, // 0xdd - VK_OEM_6 + KM_CORE_VKEY_QUOTE, // 0xde - VK_OEM_7 + KM_CORE_VKEY_oDF, // 0xdf - VK_OEM_8 + KM_CORE_VKEY_oE0, // 0xe0 - reserved + KM_CORE_VKEY_oE1, // 0xe1 - reserved + KM_CORE_VKEY_oE2, // 0xe2 - VK_OEM_102 - 102nd key on European layouts + KM_CORE_VKEY_oE3, // 0xe3 - OEM specific + KM_CORE_VKEY_oE4, // 0xe4 - OEM specific + KM_CORE_VKEY__PROCESSKEY__, // 0xe5 + KM_CORE_VKEY_oE6, // 0xe6 - OEM specific + KM_CORE_VKEY__PACKET__, // 0xe7 + KM_CORE_VKEY__E8, // 0xe8 - unassigned + KM_CORE_VKEY_oE9, // 0xe9 - OEM specific + KM_CORE_VKEY_oEA, // 0xea - OEM specific + KM_CORE_VKEY_oEB, // 0xeb - OEM specific + KM_CORE_VKEY_oEC, // 0xec - OEM specific + KM_CORE_VKEY_oED, // 0xed - OEM specific + KM_CORE_VKEY_oEE, // 0xee - OEM specific + KM_CORE_VKEY_oEF, // 0xef - OEM specific + KM_CORE_VKEY_oF0, // 0xf0 - OEM specific + KM_CORE_VKEY_oF1, // 0xf1 - OEM specific + KM_CORE_VKEY_oF2, // 0xf2 - OEM specific + KM_CORE_VKEY_oF3, // 0xf3 - OEM specific + KM_CORE_VKEY_oF4, // 0xf4 - OEM specific + KM_CORE_VKEY_oF5, // 0xf5 - OEM specific + KM_CORE_VKEY__ATTN__, // 0xf6 + KM_CORE_VKEY__CRSEL__, // 0xf7 + KM_CORE_VKEY__EXSEL__, // 0xf8 + KM_CORE_VKEY__EREOF__, // 0xf9 + KM_CORE_VKEY__PLAY__, // 0xfa + KM_CORE_VKEY__ZOOM__, // 0xfb + KM_CORE_VKEY__NONAME__, // 0xfc + KM_CORE_VKEY__PA1__, // 0xfd + KM_CORE_VKEY__OEMCLEAR__, // 0xfe + KM_CORE_VKEY__FF, // 0xff +}; + +[km_core_cu]: background#km_core_cu "km_core_cu type" +[km_core_usv]: background#km_core_usv "km_core_usv type" +[km_core_virtual_key]: background#km_core_virtual_key "km_core_virtual_key type" +[km_core_status]: background#km_core_status "km_core_status type" +[km_core_keyboard]: background#km_core_keyboard "km_core_keyboard struct" +[km_core_state]: background#km_core_state "km_core_state struct" +[km_core_options]: background#km_core_options "km_core_options struct" +[km_core_keyboard_imx_platform]: background#km_core_keyboard_imx_platform "km_core_keyboard_imx_platform callback function" +[km_core_status_codes]: background#km_core_status_codes "km_core_status_codes enum" +[km_core_attr]: background#km_core_attr "km_core_attr struct" +[km_core_tech_value]: background#km_core_tech_value "km_core_tech_value enum" +[km_core_get_engine_attrs]: background#km_core_get_engine_attrs "km_core_get_engine_attrs function" +[km_core_bool]: background#km_core_bool "km_core_bool enum" +[km_core_caps_state]: state#km_core_caps_state "km_core_caps_state enum" +[km_core_actions]: state#km_core_actions "km_core_actions struct" +[km_core_state_get_actions]: state#km_core_state_get_actions "km_core_state_get_actions function" +[km_core_context_status]: state#km_core_context_status "km_core_context_status enum" +[km_core_state_context_set_if_needed]: state#km_core_state_context_set_if_needed "km_core_state_context_set_if_needed function" +[km_core_state_context_clear]: state#km_core_state_context_clear "km_core_state_context_clear function" +[km_core_option_scope]: options#km_core_option_scope "km_core_option_scope enum" +[km_core_option_item]: options#km_core_option_item "km_core_option_item struct" +[km_core_options_list_size]: options#km_core_options_list_size "km_core_options_list_size function" +[km_core_state_option_lookup]: options#km_core_state_option_lookup "km_core_state_option_lookup function" +[km_core_state_options_update]: options#km_core_state_options_update "km_core_state_options_update function" +[km_core_keyboard_attrs]: keyboards#km_core_keyboard_attrs "km_core_keyboard_attrs struct" +[km_core_keyboard_key]: keyboards#km_core_keyboard_key "km_core_keyboard_key struct" +[km_core_keyboard_imx]: keyboards#km_core_keyboard_imx "km_core_keyboard_imx struct" +[km_core_keyboard_load_from_blob]: keyboards#km_core_keyboard_load_from_blob "km_core_keyboard_load_from_blob function" +[km_core_keyboard_dispose]: keyboards#km_core_keyboard_dispose "km_core_keyboard_dispose function" +[km_core_keyboard_get_attrs]: keyboards#km_core_keyboard_get_attrs "km_core_keyboard_get_attrs function" +[km_core_keyboard_get_key_list]: keyboards#km_core_keyboard_get_key_list "km_core_keyboard_get_key_list function" +[km_core_keyboard_key_list_dispose]: keyboards#km_core_keyboard_key_list_dispose "km_core_keyboard_key_list_dispose function" +[km_core_keyboard_get_imx_list]: keyboards#km_core_keyboard_get_imx_list "km_core_keyboard_get_imx_list function" +[km_core_keyboard_imx_list_dispose]: keyboards#km_core_keyboard_imx_list_dispose "km_core_keyboard_imx_list_dispose function" +[km_core_state_imx_register_callback]: keyboards#km_core_state_imx_register_callback "km_core_state_imx_register_callback function" +[km_core_state_imx_deregister_callback]: keyboards#km_core_state_imx_deregister_callback "km_core_state_imx_deregister_callback function" +[km_core_state_create]: keyboards#km_core_state_create "km_core_state_create function" +[km_core_state_clone]: keyboards#km_core_state_clone "km_core_state_clone function" +[km_core_state_dispose]: keyboards#km_core_state_dispose "km_core_state_dispose function" +[km_core_debug_context_type]: keyboards#km_core_debug_context_type "km_core_debug_context_type enum" +[km_core_state_context_debug]: keyboards#km_core_state_context_debug "km_core_state_context_debug function" +[km_core_cu_dispose]: keyboards#km_core_cu_dispose "km_core_cu_dispose function" +[km_core_event_flags]: processor#km_core_event_flags "km_core_event_flags enum" +[km_core_process_event]: processor#km_core_process_event "km_core_process_event function" +[km_core_event]: processor#km_core_event "km_core_event function" +[km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" +[km_core_action_item]: actions#km_core_action_item "km_core_action_item struct" +[km_core_state_action_items]: actions#km_core_state_action_items "km_core_state_action_items function" +[km_core_state_queue_action_items]: actions#km_core_state_queue_action_items "km_core_state_queue_action_items function" +[km_core_process_queued_actions]: actions#km_core_process_queued_actions "km_core_process_queued_actions function" +[km_core_context_type]: context#km_core_context_type "km_core_context_type enum" +[km_core_context_item]: context#km_core_context_item "km_core_context_item struct" +[KM_CORE_CONTEXT_ITEM_END]: context#KM_CORE_CONTEXT_ITEM_END "KM_CORE_CONTEXT_ITEM_END macro" +[km_core_state_get_intermediate_context]: context#km_core_state_get_intermediate_context "km_core_state_get_intermediate_context function" +[km_core_context_items_dispose]: context#km_core_context_items_dispose "km_core_context_items_dispose function" +[km_core_state_context]: context#km_core_state_context "km_core_state_context function" +[km_core_state_app_context]: context#km_core_state_app_context "km_core_state_app_context function" +[km_core_context_set]: context#km_core_context_set "km_core_context_set function" +[km_core_context_clear]: context#km_core_context_clear "km_core_context_clear function" +[km_core_context_item_list_size]: context#km_core_context_item_list_size "km_core_context_item_list_size function" +[km_core_context_get]: context#km_core_context_get "km_core_context_get function" +[km_core_context_length]: context#km_core_context_length "km_core_context_length function" +[km_core_modifier_state]: virtual-keys#km_core_modifier_state "km_core_modifier_state enum" +[km_core_virtual_key_value]: virtual-keys#km_core_virtual_key_value "km_core_virtual_key_value " \ No newline at end of file diff --git a/core/include/keyman/keyman_core_api.h b/core/include/keyman/keyman_core_api.h index d6fe6d4b4c..e49e8a9af9 100644 --- a/core/include/keyman/keyman_core_api.h +++ b/core/include/keyman/keyman_core_api.h @@ -1,9 +1,10 @@ /* - Copyright: © 2018 SIL International. - Description: Cross platform API C/C++ declarations for libkeymancore - Create Date: 2 Oct 2018 - Authors: Tim Eves (TSE) -*/ + * Keyman is copyright (C) SIL International. MIT License. + * + * Created by Tim Eves (TSE) on 2018-10-02 + * + * Cross platform API C/C++ declarations for libkeymancore + */ #pragma once #include @@ -17,7 +18,7 @@ extern "C" { #endif -/* +/** --- filename: index.md title: Keyman Core API @@ -318,305 +319,217 @@ macros](#lib-version-macros) to check the loaded DLL supplies the correct interface. ------------------------------------------------------------------------------- +*/ -# Common functions, types, and macros +// Note: `km_core_cu` and `km_core_usv` are defined in common/km_types.h, as the +// underlying type may vary by platform, and the types are shared across +// multiple projects. +/** + * @name km_core_cu type + * + * Represents a UTF16 codepoint, most strings are passed as UTF16. + * + * ```c + * typedef uint16_t/char16_t km_core_cu; + * ``` + */ -## Basic types +/** + * @name km_core_usv type + * + * An integral type capable of holding a single Unicode Scalar Value, a decoded + * UTF codepoint. + * + * ```c + * typedef uint32_t/char32_t km_core_usv; + * ``` + */ -Fundamental types for representing data passed across the API. +//------------------------------------------------------------------------------- -### km_core_cu type +/** + * @name km_core_virtual_key type + * + * An integral type capable of holding a platform specific virtual key code. + */ +typedef uint16_t km_core_virtual_key; -`uint16_t/char16_t` +/** + * @name km_core_status type + * + * An integral 32 bit wide type capable of holding any valid status code as + * defined by the `enum` [km_core_status_codes]. + */ +typedef uint32_t km_core_status; -Represents a UTF16 codepoint, most strings are passed as UTF16. - -### km_core_usv type - -`uint32_t/char32_t` - -An integral type capable of holding a single Unicode Scalar Value, a decoded UTF -codepoint. - -### km_core_virtual_key type - -`uint16_t` - -An integral type capable of holding a platform specific virtual key code. - -### km_core_status type - -`uint32_t` - -An integral 32 bit wide type capable of holding any valid status code as defined -by the `enum` [km_core_status_codes]. - -### km_core_modifier_state type - -`uint16_t` - -An integral type bitmask representing the state of each modifier key. - - - -## Resource types - -Opaque types for representing resources provided or created by the keyboard -processor implementation. - -### km_core_keyboard struct - -Represents a keyboard loaded from disk, that can be executed by the keyboard -processor to consume events, update state associated with an insertion point and -produce action items. A keyboard object may be referenced by any number of state -objects but must be disposed of after all state objects referencing it have -first been disposed of. - -### km_core_state struct - -Represents all state associated with an insertion point using a keyboard. This -tracks context, and current action items resulting from a processed keyboard -event. There can be many state objects using the same keyboard. A state object -may not live longer than the keyboard it manages state for. - -### km_core_options struct - -Represents a set of option items for environmental state and keyboard state. - - - - - - -------------------------------------------------------------------------------- - -# km_core_status_codes enum - -## Description - -An error code mechanism similar to COM's `HRESULT` scheme (unlike COM, any -non-zero value is an error). - -## Specification - ---> -// keep in sync with web/src/engine/src/core-adapter/KM_Core.ts -// (see https://github.com/emscripten-core/emscripten/issues/18585) -