spiegel-keyman/core/docs/api/actions.md

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

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].

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

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.

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

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.

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

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

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_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 "