Context - Keyman Core API
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 {#km_kbp_context_type}
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_type_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 {#km_kbp_context_item}
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() {#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() {#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() {#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() {#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() {#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() {#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() {#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() {#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() {#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() {#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() {#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() {#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.