--- 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 {#km_core_option_scope} ```c 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 {#km_core_option_item} Defines a single option to be passed into the Keyman Core from the Platform layer. ```c 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 {#km_core_options_list_size} 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. ```c KMN_API size_t km_core_options_list_size(km_core_option_item const *opts); ``` # km_core_state_option_lookup function {#km_core_state_option_lookup} 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. ```c 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 {#km_core_state_options_update} Adds or updates one or more options from a list of [km_core_option_item]s. ## 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. ```c KMN_API km_core_status km_core_state_options_update( km_core_state *state, km_core_option_item const *new_opts ); ``` [km_core_cu]: background#km_core_cu "km_core_cu type" [km_core_usv]: background#km_core_usv "km_core_usv type" [km_core_virtual_key]: background#km_core_virtual_key "km_core_virtual_key type" [km_core_status]: background#km_core_status "km_core_status type" [km_core_keyboard]: background#km_core_keyboard "km_core_keyboard struct" [km_core_state]: background#km_core_state "km_core_state struct" [km_core_options]: background#km_core_options "km_core_options struct" [km_core_keyboard_imx_platform]: background#km_core_keyboard_imx_platform "km_core_keyboard_imx_platform callback function" [km_core_status_codes]: background#km_core_status_codes "km_core_status_codes enum" [km_core_attr]: background#km_core_attr "km_core_attr struct" [km_core_tech_value]: background#km_core_tech_value "km_core_tech_value enum" [km_core_get_engine_attrs]: background#km_core_get_engine_attrs "km_core_get_engine_attrs function" [km_core_bool]: background#km_core_bool "km_core_bool enum" [km_core_caps_state]: state#km_core_caps_state "km_core_caps_state enum" [km_core_actions]: state#km_core_actions "km_core_actions struct" [km_core_state_get_actions]: state#km_core_state_get_actions "km_core_state_get_actions function" [km_core_context_status]: state#km_core_context_status "km_core_context_status enum" [km_core_state_context_set_if_needed]: state#km_core_state_context_set_if_needed "km_core_state_context_set_if_needed function" [km_core_state_context_clear]: state#km_core_state_context_clear "km_core_state_context_clear function" [km_core_option_scope]: options#km_core_option_scope "km_core_option_scope enum" [km_core_option_item]: options#km_core_option_item "km_core_option_item struct" [km_core_options_list_size]: options#km_core_options_list_size "km_core_options_list_size function" [km_core_state_option_lookup]: options#km_core_state_option_lookup "km_core_state_option_lookup function" [km_core_state_options_update]: options#km_core_state_options_update "km_core_state_options_update function" [km_core_keyboard_attrs]: keyboards#km_core_keyboard_attrs "km_core_keyboard_attrs struct" [km_core_keyboard_key]: keyboards#km_core_keyboard_key "km_core_keyboard_key struct" [km_core_keyboard_imx]: keyboards#km_core_keyboard_imx "km_core_keyboard_imx struct" [km_core_keyboard_load_from_blob]: keyboards#km_core_keyboard_load_from_blob "km_core_keyboard_load_from_blob function" [km_core_keyboard_dispose]: keyboards#km_core_keyboard_dispose "km_core_keyboard_dispose function" [km_core_keyboard_get_attrs]: keyboards#km_core_keyboard_get_attrs "km_core_keyboard_get_attrs function" [km_core_keyboard_get_key_list]: keyboards#km_core_keyboard_get_key_list "km_core_keyboard_get_key_list function" [km_core_keyboard_key_list_dispose]: keyboards#km_core_keyboard_key_list_dispose "km_core_keyboard_key_list_dispose function" [km_core_keyboard_get_imx_list]: keyboards#km_core_keyboard_get_imx_list "km_core_keyboard_get_imx_list function" [km_core_keyboard_imx_list_dispose]: keyboards#km_core_keyboard_imx_list_dispose "km_core_keyboard_imx_list_dispose function" [km_core_state_imx_register_callback]: keyboards#km_core_state_imx_register_callback "km_core_state_imx_register_callback function" [km_core_state_imx_deregister_callback]: keyboards#km_core_state_imx_deregister_callback "km_core_state_imx_deregister_callback function" [km_core_state_create]: keyboards#km_core_state_create "km_core_state_create function" [km_core_state_clone]: keyboards#km_core_state_clone "km_core_state_clone function" [km_core_state_dispose]: keyboards#km_core_state_dispose "km_core_state_dispose function" [km_core_debug_context_type]: keyboards#km_core_debug_context_type "km_core_debug_context_type enum" [km_core_state_context_debug]: keyboards#km_core_state_context_debug "km_core_state_context_debug function" [km_core_cu_dispose]: keyboards#km_core_cu_dispose "km_core_cu_dispose function" [km_core_event_flags]: processor#km_core_event_flags "km_core_event_flags enum" [km_core_process_event]: processor#km_core_process_event "km_core_process_event function" [km_core_event]: processor#km_core_event "km_core_event function" [km_core_event_code]: processor#km_core_event_code "km_core_event_code enum" [km_core_action_item]: actions#km_core_action_item "km_core_action_item struct" [km_core_state_action_items]: actions#km_core_state_action_items "km_core_state_action_items function" [km_core_state_queue_action_items]: actions#km_core_state_queue_action_items "km_core_state_queue_action_items function" [km_core_process_queued_actions]: actions#km_core_process_queued_actions "km_core_process_queued_actions function" [km_core_context_type]: context#km_core_context_type "km_core_context_type enum" [km_core_context_item]: context#km_core_context_item "km_core_context_item struct" [KM_CORE_CONTEXT_ITEM_END]: context#KM_CORE_CONTEXT_ITEM_END "KM_CORE_CONTEXT_ITEM_END macro" [km_core_state_get_intermediate_context]: context#km_core_state_get_intermediate_context "km_core_state_get_intermediate_context function" [km_core_context_items_dispose]: context#km_core_context_items_dispose "km_core_context_items_dispose function" [km_core_state_context]: context#km_core_state_context "km_core_state_context function" [km_core_state_app_context]: context#km_core_state_app_context "km_core_state_app_context function" [km_core_context_set]: context#km_core_context_set "km_core_context_set function" [km_core_context_clear]: context#km_core_context_clear "km_core_context_clear function" [km_core_context_item_list_size]: context#km_core_context_item_list_size "km_core_context_item_list_size function" [km_core_context_get]: context#km_core_context_get "km_core_context_get function" [km_core_context_length]: context#km_core_context_length "km_core_context_length function" [km_core_modifier_state]: virtual-keys#km_core_modifier_state "km_core_modifier_state enum" [km_core_modifier_mask]: virtual-keys#km_core_modifier_mask "km_core_modifier_mask " [km_core_virtual_key_value]: virtual-keys#km_core_virtual_key_value "km_core_virtual_key_value "