8b88195aec
Rebuild the API docs using api-header-extractor script, and add the script to the normal build for Core so that it doesn't get out of sync again. Hotdoc configuration has not been used for a while; it is currently broken and we haven't got any docs generated by it anyway, so remove from repo. Remove largely duplicate BUILDING.md and old json-schema.md. Test-bot: skip
8.4 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
Description
Specification
enum km_core_option_scope {
KM_CORE_OPT_UNKNOWN = 0,
KM_CORE_OPT_KEYBOARD = 1,
KM_CORE_OPT_ENVIRONMENT = 2,
KM_CORE_OPT_MAX_SCOPES
};
Values
KM_CORE_OPT_UNKNOWN- An unknown option type. Reserved.
KM_CORE_OPT_KEYBOARD- 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_ENVIRONMENT- Properties of the current environment, often but not necessarily always read-only.
km_core_option_item struct
Description
Defines a single option to be passed into the Keyman Core from the Platform layer.
Specification
struct km_core_option_item {
km_core_cu const * key;
km_core_cu const * value;
uint8_t scope;
};
#define KM_CORE_OPTIONS_END { 0, 0, 0 }
Members
key- Null-terminated string key for the option
value- Null-terminated string value for the option
scope- Scope which an option belongs to, from km_core_option_scope.
km_core_options_list_size()
Description
Return the length of a terminated km_core_option_item array (options list).
Specification
KMN_API
size_t
km_core_options_list_size(km_core_option_item const *opts);
Parameters
opts- A pointer to a
KM_CORE_OPTIONS_ENDterminated 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.
km_core_state_option_lookup
Description
Lookup an option based on its key, in an options list.
Specification
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);
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
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.
km_core_state_options_update()
Description
Adds or updates one or more options from a list of km_core_option_items.
Specification
KMN_API
km_core_status
km_core_state_options_update(km_core_state *state,
km_core_option_item const *new_opts);
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
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.