mirror of
https://github.com/keymanapp/keyman.git
synced 2026-08-05 00:15:32 +00:00
docs(core): add keyhandling doc
This documents the state of `km_core_actions.emit_keystroke` for different keys pressed. Also some cleanup in other docs. This documents the state after merging #15609 (for ldml keyboards) and NN (for kmn keyboards). Follows: #15609 Build-bot: skip Test-bot: skip
This commit is contained in:
Eberhard Beilharz
parent
b526238b70
commit
f07f95452f
7 changed files with 65 additions and 16 deletions
|
|
@ -19,6 +19,7 @@ This is an internal API intended for use only within Keyman Engine.
|
|||
* [Options](options)
|
||||
* [Processor](processor)
|
||||
* [State and Actions](state)
|
||||
* [Key Handling](keyhandling)
|
||||
* [JSON introspection Schema](json-schema)
|
||||
* [Building Keyman Core](building)
|
||||
|
||||
|
|
@ -122,4 +123,4 @@ Caps Lock.
|
|||
[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_event_code]: processor#km_core_event_code "km_core_event_code enum"
|
||||
|
|
|
|||
|
|
@ -4,10 +4,10 @@ title: JSON Introspection Schema
|
|||
|
||||
The [`km_core_state_to_json()`](state#km_core_state_to_json) call
|
||||
generates a JSON document describing the internal state of the keyboard
|
||||
processor, this is the schema describing that document.
|
||||
processor. This is the schema describing that document.
|
||||
|
||||
**WARNING**: The structure and format of the JSON document is independently
|
||||
versioned is not considered part of C API. It is intended solely for use in
|
||||
versioned and is not considered part of the C API. It is intended solely for use in
|
||||
diagnostics or by development and debugging tools which may need to be aware of
|
||||
keyboard processor engine implementation details.
|
||||
|
||||
|
|
@ -74,4 +74,4 @@ keyboard processor engine implementation details.
|
|||
"context": { "$ref": "#/definitions/context" }
|
||||
}
|
||||
}
|
||||
```
|
||||
```
|
||||
|
|
|
|||
42
core/docs/api/keyhandling.md
Normal file
42
core/docs/api/keyhandling.md
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
# Key Handling
|
||||
|
||||
For each key press the processor will called twice, for the key down event
|
||||
as well as for the key up event. Depending on the type of key pressed the
|
||||
processor might handle the key itself or pass it on to the application.
|
||||
The value of `emit_keystroke` in `km_core_actions` struct tells if the
|
||||
processor handled the key (`emit_keystroke=0`) or not (`emit_keystroke=1`).
|
||||
It is important that the same value gets set for both key down and key up
|
||||
events, otherwise the application might miss some events which then looks
|
||||
to the user like keys are stuck.
|
||||
|
||||
Usually the processor won't handle any frame keys and let the application
|
||||
deal with it. This allows shortcut keys like <kbd>Ctrl</kbd>+<kbd>C</kbd>
|
||||
to work. The only exception is the <kbd>Backspace</kbd> key which is
|
||||
handled internally if enough context is available. Regular keys will be
|
||||
handled by the processor.
|
||||
|
||||
Note that there is a difference between CLDR/LDML and KMN keyboards if
|
||||
there are no rules/transforms defined for a key: KMN keyboards will
|
||||
output the cap value of the key (e.g. pressing <kbd>a</kbd> will output
|
||||
`a` if no rule is defined), whereas CLDR/LDML keyboards will suppress
|
||||
any output for that key.
|
||||
|
||||
The following table lists the state of `km_core_actions.emit_keystroke`
|
||||
on return of `km_core_process_event` when the following type of key is
|
||||
pressed:
|
||||
|
||||
|Type | KeyDown | KeyUp |
|
||||
|-----------------------------|---------------|----------|
|
||||
|Key with rule | FALSE | FALSE |
|
||||
|Key w/o rule | FALSE | FALSE |
|
||||
|Framekeys: | | |
|
||||
|<kbd>Enter</kbd> | TRUE | TRUE |
|
||||
|<kbd>Backspace</kbd>¹ | FALSE | FALSE |
|
||||
|<kbd>Backspace</kbd>² | TRUE | TRUE |
|
||||
|<kbd>Ctrl</kbd>+Key | TRUE | TRUE |
|
||||
|Modifier key <kbd>Shift</kbd>| TRUE | TRUE |
|
||||
|Modifier key <kbd>Ctrl</kbd> | TRUE | TRUE |
|
||||
|Modifier key <kbd>LAlt</kbd> | TRUE | TRUE |
|
||||
|
||||
1: context available<br/>
|
||||
2: without or with empty context
|
||||
|
|
@ -3,7 +3,7 @@ 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 is expected to apply any persisted
|
||||
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
|
||||
|
|
@ -281,4 +281,4 @@ km_core_state_options_to_json(km_core_state const *state,
|
|||
[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_event_code]: processor#km_core_event_code "km_core_event_code enum"
|
||||
|
|
|
|||
|
|
@ -15,8 +15,8 @@ enum km_core_event_flags {
|
|||
KM_CORE_EVENT_FLAG_DEFAULT = 0,
|
||||
KM_CORE_EVENT_FLAG_TOUCH = 1,
|
||||
};
|
||||
|
||||
```
|
||||
|
||||
## Values
|
||||
|
||||
`KM_CORE_EVENT_FLAG_DEFAULT`
|
||||
|
|
@ -195,4 +195,4 @@ enum km_core_event_code {
|
|||
[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_event_code]: processor#km_core_event_code "km_core_event_code enum"
|
||||
|
|
|
|||
|
|
@ -15,7 +15,8 @@ owned by the state object.
|
|||
|
||||
## Description
|
||||
|
||||
Describes the
|
||||
Describes a change to the hardware caps lock indicator state requested by
|
||||
Keyman Core to the Platform layer.
|
||||
|
||||
## Specification
|
||||
```c
|
||||
|
|
@ -50,6 +51,7 @@ This API replaces the Action items APIs, which are now deprecated and will be
|
|||
removed in the future.
|
||||
|
||||
## Specification
|
||||
|
||||
```c
|
||||
typedef struct {
|
||||
unsigned int code_points_to_delete;
|
||||
|
|
@ -60,8 +62,8 @@ typedef struct {
|
|||
km_core_caps_state new_caps_lock_state;
|
||||
const km_core_usv* deleted_context;
|
||||
} km_core_actions;
|
||||
|
||||
```
|
||||
|
||||
## Members
|
||||
|
||||
`code_points_to_delete`
|
||||
|
|
@ -78,15 +80,17 @@ typedef struct {
|
|||
|
||||
`emit_keystroke`
|
||||
: Emit the (unmodified) input keystroke to the application, 0 = no, 1 = yes.
|
||||
On most platforms this signals whether the processor handled the event
|
||||
(0) or not (1). See also [key handling](keyhandling).
|
||||
|
||||
`new_caps_lock_state`
|
||||
: -1=unchanged, 0=off, 1=on
|
||||
|
||||
`deleted_context`
|
||||
: Reference copy of actual UTF32 codepoints deleted from end of context
|
||||
(closest to caret) exactly code_points_to_delete in length (plus null
|
||||
(closest to caret) exactly `code_points_to_delete` in length (plus null
|
||||
terminator). Used to determine encoding conversion differences when
|
||||
deleting; only set when using [km_core_state_get_actions], otherwise nullptr.
|
||||
deleting; only set when using [km_core_state_get_actions], otherwise `nullptr`.
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
|
|
@ -282,4 +286,4 @@ An opaque pointer to a state object.
|
|||
[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_event_code]: processor#km_core_event_code "km_core_event_code enum"
|
||||
|
|
|
|||
|
|
@ -576,15 +576,17 @@ typedef struct {
|
|||
|
||||
`emit_keystroke`
|
||||
: Emit the (unmodified) input keystroke to the application, 0 = no, 1 = yes.
|
||||
On most platforms this signals whether the processor handled the event
|
||||
(0) or not (1). See also [key handling](keyhandling).
|
||||
|
||||
`new_caps_lock_state`
|
||||
: -1=unchanged, 0=off, 1=on
|
||||
|
||||
`deleted_context`
|
||||
: Reference copy of actual UTF32 codepoints deleted from end of context
|
||||
(closest to caret) exactly code_points_to_delete in length (plus null
|
||||
(closest to caret) exactly `code_points_to_delete` in length (plus null
|
||||
terminator). Used to determine encoding conversion differences when
|
||||
deleting; only set when using [km_core_state_get_actions], otherwise nullptr.
|
||||
deleting; only set when using [km_core_state_get_actions], otherwise `nullptr`.
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
|
|
@ -744,7 +746,7 @@ 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 is expected to apply any persisted
|
||||
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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue