10 KiB
| title |
|---|
| 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 expected to apply any persisted
options it is maintaining. Options are passed into and out of API functions as
simple C arrays of km_core_option_item terminated with a KM_CORE_OPTIONS_END
sentinel value. A state's options are exposed and manipulatable via the
km_core_options API. All option values are of type C string.
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_core_option_scope enum
enum km_core_option_scope {
/** An unknown option type. Reserved. */
KM_CORE_OPT_UNKNOWN = 0,
/** An option that is defined for the currently active keyboard; not all
* processors support this type of option. These options are specific to the
* active keyboard. */
KM_CORE_OPT_KEYBOARD = 1,
/** Properties of the current environment, often but not necessarily always
* read-only. */
KM_CORE_OPT_ENVIRONMENT = 2,
KM_CORE_OPT_MAX_SCOPES
};
km_core_option_item struct
Defines a single option to be passed into the Keyman Core from the Platform layer.
struct km_core_option_item {
/** Null-terminated string key for the option */
km_core_cu const * key;
/** Null-terminated string value for the option */
km_core_cu const * value;
/** Scope which an option belongs to, from [km_core_option_scope]. */
uint8_t scope;
};
#define KM_CORE_OPTIONS_END { 0, 0, 0 }
km_core_options_list_size function
Return the length of a terminated km_core_option_item array (options list).
Parameters
opts
A pointer to a KM_CORE_OPTIONS_END terminated array of
km_core_option_item values.
Returns
The number of items in the list, not including terminating
item, or 0 if opts is null.
KMN_API
size_t
km_core_options_list_size(km_core_option_item const *opts);
km_core_state_option_lookup function
Lookup an option based on its key, in an options list.
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_core_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
One of the following values:
KM_CORE_STATUS_OK- On success.
KM_CORE_STATUS_INVALID_ARGUMENT- If non-optional parameters are null, or if the scope is invalid.
KM_CORE_STATUS_KEY_ERROR- The key cannot be found.
KMN_API
km_core_status
km_core_state_option_lookup(
km_core_state const *state,
uint8_t scope,
km_core_cu const *key,
km_core_cu const **value
);
km_core_state_options_update function
Adds or updates one or more options from a list of km_core_option_items.
Parameters
state
An opaque pointer to a state object.
new_opts
An array of km_core_option_item objects to update or add.
Must be terminated with KM_CORE_OPTIONS_END.
Returns
One of the following values:
KM_CORE_STATUS_OK- On success.
KM_CORE_STATUS_INVALID_ARGUMENT- If non-optional parameters are null.
KM_CORE_STATUS_NO_MEM- In the event an internal memory allocation fails.
KM_CORE_STATUS_KEY_ERROR- The key cannot be found.
KMN_API
km_core_status
km_core_state_options_update(
km_core_state *state,
km_core_option_item const *new_opts
);