diff options
Diffstat (limited to 'docs/migrating.md')
| -rw-r--r-- | docs/migrating.md | 40 |
1 files changed, 40 insertions, 0 deletions
diff --git a/docs/migrating.md b/docs/migrating.md new file mode 100644 index 0000000..d224cd4 --- /dev/null +++ b/docs/migrating.md @@ -0,0 +1,40 @@ +# Migrating pre-release applications + +YASL 0.1 has no stable source or binary compatibility promise. Rebuild all +consumers against the matching installed headers and library after updating. +The following changes replace backend-specific input fields with a common +contract. See the [application guide](guide.md) for the full input workflow. + +## Keyboard events + +| Previous use | Replacement | +| --- | --- | +| Linux keysym or Cocoa virtual keycode in `key.key` | Portable physical `YASL_KEY_*` identity | +| `key.base` | `key.native_code`, with explicit backend-specific encoding | +| `key.keypad` | Distinct `YASL_KEY_KP_*` identities | +| Advisory `key.text` character | `YASL_INPUT_TEXT` UTF-8 payload for insertion | +| Layout label from a keysym | Optional `key.codepoint` and `key.shifted` Unicode scalars | + +Replace magic numbers and X11 symbols with named keys. For example, a quit +command checks `key.key == YASL_KEY_ESCAPE` on a press. `YASL_KEY_A` means the +US A position on every layout; use layout labels when a command should follow +the printed letter instead. Do not cast key identities to characters. Keypad +Enter and ordinary Enter now have distinct identities without a separate flag. + +Text comes only from `YASL_INPUT_TEXT`. Handle its byte length, copy it when +retaining it after the next successful poll, and allow multiple characters per +commit. Cocoa sends key events through its text input manager; Wayland emits +ordinary XKB text and locale compose results in addition to IME commits. + +## Scroll events + +Replace `scroll_lines`, `scroll_delta`, and scroll button numbers with +`mouse.scroll.x` and `.y` when `mouse.kind == YASL_PTR_SCROLL`. These double +values are fractional line offsets, positive right/down on every backend. +Do not infer scroll direction from `button`. One event may include both axes. +Remove backend-specific sign inversions and whole-line casts; multiply the +offset by your application's preferred pixels per line instead. + +X11 still supplies whole wheel steps. Wayland high-resolution wheels and smooth +offsets, and Cocoa precise scrolling, preserve fractions. Device acceleration +and system preferences still affect the native offsets. |