Options - Keyman Core API
A state’s default options are set from the keyboard at creation time and the environment. The Platform layer is then is expected to apply any persisted options it is maintaining. Options are passed into and out of API functions as simple C arrays of km_kbp_option_item
terminated with a KM_KBP_OPTIONS_END
sentinel value. A state's options are exposed and manipulatable via the state object.
During processing when the Platform layer finds a PERSIST action type it should store the updated option in the appropriate place, based on its scope. For RESET the processor will apply the pristine value from the original scope, the Platform layer should update that only if it manages a previously persisted value.
km_kbp_option_scope enum {#km_kbp_option_scope}
Description
Identifies which scope and option should be stored to. Scopes are essentially separate key-value stores.
Specification
enum km_kbp_option_scope {
KM_KBP_OPT_UNKNOWN = 0,
KM_KBP_OPT_KEYBOARD = 1,
KM_KBP_OPT_ENVIRONMENT = 2,
KM_KBP_OPT_MAX_SCOPES
};
Values {#km_kbp_opt_type_values}}
KM_KBP_OPT_UNKNOWN
:It is unknown which store and option has come from. This should never be seen by client code.
KM_KBP_OPT_KEYBOARD
:The option is store in the keyboard store, a per-keyboard store modifiable by the keyboard itself.
KM_KBP_OPT_ENVIRONMENT
:The option is store in the global environment store, set and managed by the Keyman application.
KM_KBP_OPT_MAX_SCOPES
:The maximum number of different scopes supported by the API.
km_kbp_option_item struct {#km_kbp_option_item}
Description
A scoped key-value tuple. This is used to permit mass update of a keyboard state object with multiple options differently scoped options in a single call.
Specification
struct km_kbp_option_item {
km_kbp_cp const * key;
km_kbp_cp const * value;
uint8_t scope;
};
Members
key
:The name of an option. Pointer to a null-terminated UTF16 encoded string.
value
:The value of an option. Pointer to an array of km_kbp_cp
value containing a null-terminated UTF16 encoded string.
scope
:The scope of the option. A km_kbp_option_scope
value which must be less than KM_KBP_OPT_MAX_SCOPES
.
KM_KBP_OPTIONS_END macro {#km_kbp_options_end}
Description
Terminating entry for a c array of km_kbp_option_item
values
Specification
#define KM_KBP_OPTIONS_END { 0, 0, 0 }
km_kbp_options_list_size() {#km_kbp_options_list_size}
Description
Calculate the length of a terminated km_kbp_option_item
array (options list).
Specification
size_t
km_kbp_options_list_size(km_kbp_option_item const *opts);
Parameters
opts
:A pointer to a KM_KBP_OPTIONS_END
terminated array of km_kbp_option_item
values.
Returns
The number of items in the list or 0 if opts
is null.
km_kbp_state_option_lookup() {#km_kbp_state_option_lookup}
Description
Lookup an option based on its key and scope from a keyboard state. The scope may never be KM_KBP_OPT_UNKNOWN
.
Specification
km_kbp_status
km_kbp_state_option_lookup(km_kbp_state const *state,
uint8_t scope,
km_kbp_cp const *key,
km_kbp_cp const **value);
Parameters
state
:An opaque pointer to a state object.
scope
:Which key-value store to interrogate.
key
:A UTF-16 string that matches the key in the target km_kbp_option_item
.
value
:A pointer to the result variable: A pointer to a UTF-16 string value owned by
the state or keyboard object at the time of the call. This pointer is only valid
*until* the next call to any function on this API and should be used
immediately.
Returns
KM_KBP_STATUS_OK
:On success.
KM_KBP_STATUS_INVALID_ARGUMENT
:If non-optional parameters are null, or if the scope is invalid.
KM_KBP_STATUS_KEY_ERROR
:The key cannot be found.
km_kbp_state_options_update() {#km_kbp_state_options_update}
Description
Adds or updates one or more options from a list of
km_kbp_option_items
. All UTF16 strings passed int the
km_kbp_option_item
are copied. The scope of any
km_kbp_option_item
may never be
KM_KBP_OPT_UNKNOWN
.
Specification
km_kbp_status
km_kbp_state_options_update(km_kbp_state *state,
km_kbp_option_item const *new_opts);
Parameters
state
:An opaque pointer to a state object.
new_opts
:An array of km_kbp_option_item
objects to update or
add. Must be terminated with KM_KBP_OPTIONS_END
.
Returns
KM_KBP_STATUS_OK
:On success.
KM_KBP_STATUS_INVALID_ARGUMENT
:If non-optional parameters are null or any option has
KM_KBP_OPT_UNKNOWN
scope.
KM_KBP_STATUS_NO_MEM
:In the event an internal memory allocation fails.
KM_KBP_STATUS_KEY_ERROR
:The key cannot be found.
km_kbp_state_options_to_json() {#km_kbp_state_options_to_json}
Description
Export the state objects options to a JSON formatted document and place it in
the supplied buffer, reporting how much space was used. If null is passed as the
buffer the number of bytes required is returned in space
. If there
is insufficent space to hold the document the contents of the buffer is
undefined. The returned buffer uses UTF-8 encoding.
Specification
km_kbp_status
km_kbp_state_options_to_json(km_kbp_state const *state,
char *buf,
size_t *space);
Parameters
opts
:An opaque pointer to a state object.
buf
:A pointer to the buffer to place the C string containing the JSON document
into, can be null.
space
:A pointer to a size_t variable. This variable must contain the number of bytes
available in the buffer pointed to by buf
, unless buf
is null. On return it
will hold how many bytes were used.
Returns
KM_KBP_STATUS_OK
:On success.
KM_KBP_STATUS_INVALID_ARGUMENT
:If non-optional parameters are null.
KM_KBP_STATUS_NO_MEM
:In the event an internal memory allocation fails.