---

A keyboard is a set of rules and transforms in a Processor specific format for transforming key events into action items. The keyboard is parsed and loaded by the processor and made available in an immutable fashion for use with any number of state objects.

km_kbp_keyboard_attrs struct

Description

A static structure describing the basic keyboard attributes.

Specification

    typedef struct {
      km_kbp_cp const * version_string;
      km_kbp_cp const * id;
      km_kbp_path_name  folder_path;
      km_kbp_option_item const * default_options;
    } km_kbp_keyboard_attrs;

Members

version_string

Processor specific version string.

id

Keyman keyboard ID string.

folder_path

Path to the unpacked folder containing the keyboard and associated resources.

default_options

Pointer to an array of km_kbp_option_item, terminated with KM_KBP_OPTIONS_END.

km_kbp_keyboard_key struct

Description

A structure pairing a virtual key and modifier

Specification

    typedef struct {
      km_kbp_virtual_key key;
      uint32_t modifier_flag;
    } km_kbp_keyboard_key;

Members

key

a virtual key code

modifier_flag

The modifier flag

km_kbp_keyboard_imx struct

Description

A structure of IMX library and function name associated with an unique id

Specification

    typedef struct {
      km_kbp_cp const * library_name;
      km_kbp_cp const * function_name;
      uint32_t imx_id;
    } km_kbp_keyboard_imx;

Members

library_name

IMX library name

function_name

IMX function name

imx_id

unique identifier used to call this function

km_kbp_keyboard_load()

Description

Parse and load keyboard from the supplied path and a pointer to the loaded keyboard into the out parameter.

Specification

    km_kbp_status
    km_kbp_keyboard_load(km_kbp_path_name kb_path,
                         km_kbp_keyboard **keyboard);

Parameters

kb_path

On Windows, a UTF-16 string; on other platforms, a C string: contains a valid path to the keyboard file.

keyboard

A pointer to result variable: A pointer to the opaque keyboard object returned by the Processor. This memory must be freed with a call to km_kbp_keyboard_dispose()

Returns

KM_KBP_STATUS_OK

On success.

KM_KBP_STATUS_NO_MEM

In the event an internal memory allocation fails.

KM_KBP_STATUS_IO_ERROR

In the event the keyboard file is unparseable for any reason.

KM_KBP_STATUS_INVALID_ARGUMENT

In the event the file doesn't exist or is inaccessible or keyboard is null.

KM_KBP_STATUS_OS_ERROR

Bit 31 (high bit) set, bits 0-30 are an OS-specific error code.

km_kbp_keyboard_dispose()

Description

Free the allocated memory belonging to an opaque keyboard object previously returned by km_kbp_keyboard_load().

Specification

    void
    km_kbp_keyboard_dispose(km_kbp_keyboard *keyboard);

Parameters

keyboard

A pointer to the opaque keyboard object to be disposed of.

km_kbp_keyboard_get_attrs()

Description

Returns the const internal attributes of the keyboard. This structure is valid for the lifetime of the opaque keyboard object. Do not modify the returned data.

Specification

    km_kbp_status
    km_kbp_keyboard_get_attrs(km_kbp_keyboard const *keyboard,
                              km_kbp_keyboard_attrs const **out);

Parameters

keyboard

A pointer to the opaque keyboard object to be queried.

out

A pointer to the result: A pointer to a km_kbp_keyboard_attrs structure.

Returns

KM_KBP_STATUS_OK

On success.

KM_KBP_STATUS_INVALID_ARGUMENT

If non-optional parameters are null.

km_kbp_keyboard_get_key_list()

Description

Returns the unordered full set of modifier + virtual keys that are handled by the keyboard. The matching dispose call needs to be called to free the memory.

Specification

    km_kbp_status
    km_kbp_keyboard_get_key_list(km_kbp_keyboard const *keyboard,
                                km_kbp_keyboard_key const **out);

Parameters

keyboard

A pointer to the opaque keyboard object to be queried.

out

A pointer to the result, an array of km_kbp_keyboard_keys

Returns

KM_KBP_STATUS_OK

On success.

KM_KBP_STATUS_INVALID_ARGUMENT

If non-optional parameters are null.

km_kbp_keyboard_key_list_dispose()

Description

Free the allocated memory belonging to a keyboard key list previously returned by km_kbp_keyboard_get_key_list

Specification

    void km_kbp_keyboard_key_list_dispose(km_kbp_keyboard_key *key_list);

Parameters

keyboard

A pointer to the keyboard key list to be disposed of.

km_kbp_keyboard_get_imx_list()

Description

Returns the list of IMX libraries and function names that are referenced by the keyboard. The matching dispose call km_kbp_keyboard_imx_list_dispose needs to be called to free the memory.

Specification

    km_kbp_status km_kbp_keyboard_get_imx_list(
                                  km_kbp_keyboard const *keyboard,
                                  km_kbp_keyboard_imx** imx_list);

Parameters

keyboard

A pointer to the opaque keyboard object to be queried.

imx_list

A pointer to the result, an array of km_kbp_keyboard_imx structure.

Returns

KM_KBP_STATUS_OK

On success.

KM_KBP_STATUS_INVALID_ARGUMENT

If non-optional parameters are null.

km_kbp_keyboard_imx_list_dispose()

Description

Free the allocated memory belonging to a IMX list previously returned by km_kbp_keyboard_get_imx_list.

Specification

    void km_kbp_keyboard_key_list_dispose(km_kbp_keyboard_key *key_list);

Parameters

keyboard

A pointer to the IMX list to be disposed of.