---

The context is the text prior to the insertion point (caret, cursor). The context is constructed by the Platform layer, typically by interrogating the Client Application. The context will be updated by the engine for keystroke events. If the Platform layer code caches the context, the context should be reset when a context state change is detected. Context state changes can occur when the user uses the mouse to move the insertion point, uses cursor keys, switches applications or input fields, or presses hotkeys such as Ctrl+N to start a new document. The full set of context state change triggers is up to the Platform layer.

Context can also contain positional Markers (also known as 'deadkeys' in kmn keyboards), which are transitory state flags that are erased whenever a context state change is detected. Markers are always controlled by the Engine.

Contexts are always owned by their state. They may be set to a list of context_items or interrogated for their current list of context items.

km_kbp_context_type enum

Description

km_kbp_context_item.type values which identify which data value (if any) the context item carries.

Specification

    enum km_kbp_context_type {
      KM_KBP_CT_END,
      KM_KBP_CT_CHAR,
      KM_KBP_CT_MARKER
    };

Values

KM_KBP_CT_END

A km_kbp_context_item of this type marks the end of an array of context items.

KM_KBP_CT_CHAR

The context item contains a Unicode Scalar Value which must be accessed through the km_kbp_context_item.character union member.

KM_KBP_CT_MARKER

The context item contains a positional marker which must be accessed through the km_kbp_context_item.marker union member.

km_kbp_context_item struct

Description

A tagged union representing an element of context which can be either a Unicode character or a positional marker.

Specification

    typedef struct {
      uint8_t   type;
      uint8_t   _reserved[3];
      union {
        km_kbp_usv  character;
        uint32_t    marker;
      };
    } km_kbp_context_item;

Members

type

Identifies the union member to access. A value of enum km_kbp_context_type values.

_reserved

Space reserved for alignment purposes and possible future use.

character

A Unicode Scalar Value.

marker

A marker value, only meaningful to an engine.

KM_KBP_CONTEXT_ITEM_END macro

Description

Convenience macro to declare a terminating entry in a km_kbp_context_item item array.

Specification

    #define KM_KBP_CONTEXT_ITEM_END {KM_KBP_CT_END, {0,}, {0,}}

km_kbp_context_items_from_utf16()

Description

Convert a UTF16 encoded Unicode string into an array of km_kbp_context_item structures. Allocates memory as needed.

Specification

    km_kbp_status
    km_kbp_context_items_from_utf16(km_kbp_cp const *text,
                                    km_kbp_context_item **out_ptr);

Parameters

text

a pointer to a null terminated array of utf16 encoded data.

out_ptr

A pointer to the result variable: A pointer to the start of the km_kbp_context_item array containing the representation of the input string. Terminated with a type of KM_KBP_CT_END. Must be disposed of with km_kbp_context_items_dispose()

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 not enough memory can be allocated for the output buffer.

KM_KBP_STATUS_INVALID_UTF

In the event the UTF16 string cannot be decoded because it contains unpaired surrogate codeunits.

km_kbp_context_items_from_utf8()

Description

Convert an UTF8 encoded Unicode string into an array of km_kbp_context_item structures. Allocates memory as needed.

Specification

    km_kbp_status
    km_kbp_context_items_from_utf8(char const *text,
                                    km_kbp_context_item **out_ptr);

Parameters

text

a pointer to a null terminated array of utf8 encoded data.

out_ptr

A pointer to the result variable: A pointer to the start of the km_kbp_context_item array containing the representation of the input string. Terminated with a type of KM_KBP_CT_END.

Returns

KM_KBP_STATUS_INVALID_ARGUMENT

If non-optional parameters are null.

KM_KBP_STATUS_NO_MEM

In the event it cannot allocate enough memory for the output buffer.

KM_KBP_STATUS_INVALID_UTF

In the event the UTF8 string cannot be decoded.

km_kbp_context_items_to_utf16()

Description

Convert a context item array into a UTF-16 encoded string placing it into the supplied buffer of specified size, and return the number codepoints actually used in the conversion. If null is passed as the buffer the number codeunits required is returned. This will strip markers from the context during the conversion.

Specification

    km_kbp_status
    km_kbp_context_items_to_utf16(km_kbp_context_item const *item,
                                  km_kbp_cp *buf,
                                  size_t *buf_size);

Parameters

context_items

A pointer to the start of an array km_kbp_context_item. Must be terminated with a type of KM_KBP_CT_END.

buf

A pointer to the buffer to place the UTF-16 string into. May be be null to request size calculation.

buf_size

A pointer to the result variable: A pointer the size of the supplied buffer in codeunits or filled with the size required if buf is null.

Returns

KM_KBP_STATUS_OK

On success.

KM_KBP_STATUS_INVALID_ARGUMENT

If non-optional parameters are null.

KM_KBP_STATUS_INSUFFICENT_BUFFER

If the buffer is not large enough buf_size will contain the space required. The contents of the buffer are undefined.

km_kbp_context_items_to_utf8()

Description

Convert a context item array into a UTF-8 encoded string placing it into the supplied buffer of specified size, and return the number codepoints actually used in the conversion. If null is passed as the buffer the number codeunits required is returned. This will strip markers from the context during the conversion.

Specification

    km_kbp_status
    km_kbp_context_items_to_utf8(km_kbp_context_item const *item,
                                  char *buf,
                                  size_t *buf_size);

Parameters

context_items

A pointer to the start of an array km_kbp_context_item. Must be terminated with a type of KM_KBP_CT_END.

buf

A pointer to the buffer to place the UTF-8 string into. May be be null to request size calculation.

buf_size

A pointer to the result variable: A pointer the size of the supplied buffer in codeunits or filled with the size required if buf is null.

Returns

KM_KBP_STATUS_OK

On success.

KM_KBP_STATUS_INVALID_ARGUMENT

If non-optional parameters are null.

KM_KBP_STATUS_INSUFFICENT_BUFFER

If the buffer is not large enough buf_size will contain the space required. The contents of the buffer are undefined.

km_kbp_context_items_dispose()

Description

Free the allocated memory belonging to a km_kbp_context_item array previously returned by km_kbp_context_items_from_utf16() or km_kbp_context_get().

Specification

    void
    km_kbp_context_items_dispose(km_kbp_context_item *context_items);

Parameters

context_items

A pointer to the start of the km_kbp_context_item array to be disposed of.

km_kbp_context_set()

Description

Replace the contents of the current context with a new sequence of km_kbp_context_item entries.

Specification

    km_kbp_status
    km_kbp_context_set(km_kbp_context *context,
                       km_kbp_context_item const *context_items);

Parameters

context

A pointer to an opaque context object.

context_items

A pointer to the start of the km_kbp_context_item array containing the new context. It must be terminated with an item of type KM_KBP_CT_END.

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 not enough memory can be allocated to grow the context buffer internally.

km_kbp_context_get()

Description

Copies all items in the context into a new array and returns the new array. This must be disposed of by caller using km_kbp_context_items_dispose().

Specification

    km_kbp_status
    km_kbp_context_get(km_kbp_context const *context_items,
                       km_kbp_context_item **out);

Parameters

context_items

A pointer to the start of an array km_kbp_context_item.

out

A pointer to the result variable: A pointer to the start of the km_kbp_context_item array containing a copy of the context. Terminated with a type of KM_KBP_CT_END. Must be disposed of with km_kbp_context_items_dispose().

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 not enough memory can be allocated for the output buffer.

km_kbp_context_clear()

Description

Removes all context_items from the internal array. If context is null, has no effect.

Specification

    void
    km_kbp_context_clear(km_kbp_context *context);

Parameters

context

A pointer to an opaque context object.

km_kbp_context_length()

Description

Return the number of items in the context.

Specification

    size_t
    km_kbp_context_length(km_kbp_context *);

Parameters

context

A pointer to an opaque context object.

Returns

The number of items in the context, and will return 0 if passed a null context pointer.

km_kbp_context_append()

Description

Add more items to the end (insertion point) of the context. If these exceed the maximum context length the same number of items will be dropped from the beginning of the context.

Specification

    km_kbp_status
    km_kbp_context_append(km_kbp_context *context,
                          km_kbp_context_item const *context_items);

Parameters

context

A pointer to an opaque context object.

context_items

A pointer to the start of the KM_KBP_CT_END terminated array of km_kbp_context_item to append.

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 not enough memory can be allocated to grow the context buffer internally.

km_kbp_context_shrink()

Description

Remove a specified number of items from the end of the context, optionally add up to the same number of the supplied items to the front of the context.

Specification

    km_kbp_status
    km_kbp_context_shrink(km_kbp_context *context,
                          size_t num,
                          km_kbp_context_item const *prefix);

Parameters

context

A pointer to an opaque context object.

num

The number of items to remove from the end of context.

context_items

Pointer to the start of the KM_KBP_CT_END terminated array of km_kbp_context_item to add to the front. Up to num items will be prepended. This may be null if not required.

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 it cannot allocate enough memory to grow the context internally.

km_kbp_context_item_list_size()

Description

Return the length of a terminated km_kbp_context_item array.

Specification

    size_t
    km_kbp_context_item_list_size(km_kbp_context_item const *context_items);

Parameters

context_items

A pointer to a KM_KBP_CT_END terminated array of km_kbp_context_item values.

Returns

The number of items in the list, not including terminating item, or 0 if context_items is null.