mirror of
https://github.com/keymanapp/keyman.git
synced 2026-08-16 05:39:24 +00:00
390 lines
No EOL
14 KiB
Markdown
390 lines
No EOL
14 KiB
Markdown
---
|
|
title: Internal Context - Keyman Core API
|
|
---
|
|
<!-- generated by core/tools/api-header-extractor from core/include/keyman/*.h on 2026-05-06 -->
|
|
|
|
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_modifier_mask]: virtual-keys#km_core_modifier_mask "km_core_modifier_mask "
|
|
[km_core_virtual_key_value]: virtual-keys#km_core_virtual_key_value "km_core_virtual_key_value " |