mirror of
https://github.com/keymanapp/keyman.git
synced 2026-08-19 06:47:41 +00:00
249 lines
No EOL
12 KiB
Markdown
249 lines
No EOL
12 KiB
Markdown
---
|
|
title: State and Actions - Keyman Core API
|
|
---
|
|
<!-- generated by core/tools/api-header-extractor from core/include/keyman/*.h on 2026-05-06 -->
|
|
|
|
A State object maintains all per keyboard related state including context
|
|
and dynamic options ("option stores" in kmn format).
|
|
|
|
When a keystroke is processed by Keyman Core, Core provides back a set of actions
|
|
for the Platform layer to emit to the Client application. These actions are
|
|
owned by the state object.
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
# 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.
|
|
|
|
```c
|
|
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;
|
|
```
|
|
|
|
# km_core_actions struct {#km_core_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.
|
|
|
|
```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;
|
|
```
|
|
|
|
# km_core_state_get_actions function {#km_core_state_get_actions}
|
|
|
|
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.
|
|
|
|
|
|
## 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.
|
|
|
|
```c
|
|
KMN_API
|
|
km_core_actions const *
|
|
km_core_state_get_actions(
|
|
km_core_state const *state
|
|
);
|
|
```
|
|
|
|
# km_core_context_status enum {#km_core_context_status}
|
|
|
|
Return values for [km_core_state_context_set_if_needed].
|
|
|
|
```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;
|
|
```
|
|
|
|
# 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
|
|
cached context. For the purposes of comparison, (1) cached markers are
|
|
ignored, (2) if the cached context is shorter than the application
|
|
context, it is considered identical, but (3) if the cached context is
|
|
longer, then it is considered different.
|
|
|
|
If a difference is found, then the cached context will be set to the
|
|
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.
|
|
|
|
|
|
## 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
|
|
km_core_state_context_set_if_needed(
|
|
km_core_state *state,
|
|
km_core_cu const *application_context
|
|
);
|
|
```
|
|
|
|
|
|
# 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))`.
|
|
|
|
[km_core_state_context_set_if_needed] and [km_core_state_context_clear]
|
|
will replace most uses of the existing Core context APIs.
|
|
|
|
|
|
## Parameters
|
|
|
|
### state
|
|
An opaque pointer to a state object.
|
|
|
|
## Returns
|
|
One of the following values:
|
|
|
|
`KM_CORE_STATUS_OK`
|
|
: On success.
|
|
|
|
`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_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 " |