From 94c5e361fbb229b0cd6853e2102a7d95f1f358b3 Mon Sep 17 00:00:00 2001 From: Berke Güzel Date: Mon, 12 Oct 2026 22:12:02 +0300 Subject: better public interface and doxygen --- docs/migrating.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/migrating.md (limited to 'docs/migrating.md') 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. -- cgit v1.2.3