---

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

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

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()

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

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()

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()

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.

---