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}

Description

Describes the

Specification

typedef enum { KM_CORE_CAPS_UNCHANGED = -1, KM_CORE_CAPS_OFF = 0, 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 API replaces the Action items APIs, which are now deprecated and will be removed in the future.

Specification

typedef struct {
  unsigned int code_points_to_delete;
  const km_core_usv* output;
  km_core_option_item * persist_options;
  km_core_bool do_alert;
  km_core_bool emit_keystroke;
  km_core_caps_state new_caps_lock_state;
  const km_core_usv* deleted_context;
} km_core_actions;

Members

code_points_to_delete : Number of codepoints (not codeunits!) to delete from app context.

output : Null-term string of characters to insert into document.

persist_options : List of options to persist, terminated with KM_CORE_OPTIONS_END.

do_alert : Issue a beep, 0 = no, 1 = yes.

emit_keystroke : Emit the (unmodified) input keystroke to the application, 0 = no, 1 = yes.

new_caps_lock_state : -1=unchanged, 0=off, 1=on

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

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

typedef enum {
  KM_CORE_CONTEXT_STATUS_UNCHANGED = 0,
  KM_CORE_CONTEXT_STATUS_UPDATED = 1,
  KM_CORE_CONTEXT_STATUS_CLEARED = 2,
  KM_CORE_CONTEXT_STATUS_ERROR = 3,
  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

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.

Specification

KMN_API
km_core_context_status
km_core_state_context_set_if_needed(
  km_core_state *state,
  km_core_cp 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

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.

Specification

KMN_API
km_core_status
km_core_state_context_clear(
  km_core_state *state
);

Parameters

state: An opaque pointer to a state object.

Returns

KM_CORE_STATUS_OK : On success.

KM_CORE_STATUS_INVALID_ARGUMENT : If any parameters are null.