diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/guide.md | 41 | ||||
| -rw-r--r-- | docs/migrating.md | 38 |
2 files changed, 57 insertions, 22 deletions
diff --git a/docs/guide.md b/docs/guide.md index 1bd1aef..f195e5e 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -45,7 +45,9 @@ in `event`, and render into `frame->cpu.pixels` in `frame`. Present with `yasl_frame_present_cpu(frame, NULL, 0)` and return `YASL_APP_QUIT` from an event handler to exit. The runner handles dispatch, input polling, resize redraws, and remaining surface/display cleanup. Display quit stops the runner; connection -loss and dispatch failures return an error after cleanup. +loss and dispatch failures return an error after cleanup. The runner delivers +input exactly as `yasl_surface_poll_event()` returns it, plus +`YASL_EVENT_WINDOW_RESIZE`, `YASL_EVENT_WINDOW_CLOSE`, and `YASL_EVENT_USER`. Unified pointer button and motion events retain `device` and `pen` axes, including erasers and pressure-only motion. Cancel held input or active strokes @@ -159,19 +161,21 @@ clock; it does not establish actual scanout time. ## Input, text, and payload lifetime -Dispatch receives native input. `yasl_surface_input_poll()` only drains it and +Dispatch receives native input. `yasl_surface_poll_event()` only drains it and never waits. Poll every live surface queue until empty. Wayland routes popup pointer and keyboard events through the root parent's queue; inspect `event.surface` to identify the recipient. Do not assume it equals the object whose queue you polled. -Read the union member selected by `event.kind`. The `reserved` field is internal -and must not be interpreted. Text, paste, and file-drop payloads are UTF-8 byte -strings, NUL-terminated; `len` excludes the NUL. They remain valid until the +Read the union member selected by `event.type`; `time_ns` is a monotonic +timestamp on the `yasl_loop_now_ns()` clock. Polling returns only input types, +`YASL_EVENT_KEY` through `YASL_EVENT_INPUT_RESET`. Text, paste, and file-drop +payloads share `event.text`: UTF-8 byte strings, NUL-terminated; `len` excludes +the NUL. They remain valid until the next **successful** poll on the queue or queue destruction. Dispatch, flush, and unsuccessful polls do not invalidate them. Copy data to keep it longer. -Use `YASL_INPUT_TEXT` for document text insertion, including committed IME text. +Use `YASL_EVENT_TEXT` for document text insertion, including committed IME text. It contains UTF-8 and can contain several characters. Key actions are for commands and held-key state; releases and repeats have separate tags. A text commit need not correspond to one key event, and a key need not produce text. @@ -192,11 +196,11 @@ are useful for displaying shortcuts or choosing layout-sensitive commands; they are never document text. For example: ```c -if (event.kind == YASL_INPUT_KEY && event.key.action == YASL_KEY_PRESS && +if (event.type == YASL_EVENT_KEY && event.key.action == YASL_KEY_PRESS && event.key.key == YASL_KEY_ESCAPE) { running = false; } -/* Insert event.text.text[0..event.text.len) only for YASL_INPUT_TEXT. */ +/* Insert event.text.data[0..event.text.len) only for YASL_EVENT_TEXT. */ ``` Wayland uses the supplied XKB layout and locale compose rules for ordinary text @@ -209,14 +213,21 @@ not change the process locale. IME availability and system configuration still determine which compositions work. Physical key events remain available for commands; input methods may consume keys while composing. -Pointer events use `YASL_INPUT_MOUSE`, with `device` distinguishing mouse, touch, -pen, and eraser. Press/release button 0 is primary/tip, 1 middle, and 2 secondary. -Track those transitions; motion/leave button values are informational. Pen +Pointer events use the `YASL_EVENT_POINTER_*` types and share `event.pointer`, +with `device` distinguishing mouse, touch, pen, and eraser. `POINTER_DOWN` and +`POINTER_UP` carry a `YASL_BUTTON_*` value: `PRIMARY` is the left button, pen tip, +or touch contact. Track those transitions; other types leave `button` +meaningless. `POINTER_MOTION` reports `delta`, the device-pixel movement since +the previous sample, which restarts from zero after enter, leave, or reset. +`yasl_surface_set_pointer_mode()` with `YASL_POINTER_RELATIVE` hides and locks the +cursor while the surface is focused; motion then carries unbounded `delta` and +`pos` stays at the lock position. No backend implements it yet, so it +currently returns false and leaves the surface in `YASL_POINTER_NORMAL`. Pen pressure is normalized to 0..65535, signed tilt is in degrees, and missing axes are zero. Pressure-only changes can produce motion. Zero pressure alone does not mean release. This interface does not expose simultaneous touch contacts. -For `YASL_PTR_SCROLL`, read `mouse.scroll.x` and `.y`: fractional line offsets, +For `YASL_EVENT_POINTER_SCROLL`, read `pointer.scroll.x` and `.y`: fractional line offsets, positive right and down, after system scroll preferences. Both axes may be nonzero in one event. Preserve fractions and choose your application's own pixels per line; one wheel detent normally gives one line. `button` is unused @@ -225,7 +236,7 @@ discrete/raw descriptions. Smooth Wayland offsets and precise Cocoa offsets use ten native units per line. X11 currently reports whole wheel steps, so it does not provide the same smooth-scroll precision as the other backends. -Cancel held keys, buttons, active strokes, and composition on `YASL_INPUT_RESET`, +Cancel held keys, buttons, active strokes, and composition on `YASL_EVENT_INPUT_RESET`, focus loss, or pointer leave as appropriate to your application. RESET has no union payload. It is emitted after input-queue allocation failure and certain device interruptions; ignoring it can leave application input stuck. @@ -234,7 +245,7 @@ device interruptions; ignoring it can leave application input stuck. `yasl_display_copy()` copies a NUL-terminated UTF-8 string during the call. `yasl_display_paste()` requests delivery to the original target as -`YASL_INPUT_PASTE`; destroying the target cancels delivery. There is no transfer +`YASL_EVENT_PASTE`; destroying the target cancels delivery. There is no transfer ID or error callback, so unavailable or failed transfers may produce no event. Wayland selection offers can require a recent input serial. X11 currently does not implement incremental (`INCR`) selection transfers and may reject large @@ -245,7 +256,7 @@ and never aliases the clipboard. Cocoa uses a YASL named pasteboard to emulate p this is not a desktop-wide macOS select-to-copy convention. External file drag hover uses the surface `drop` callback; actual file URLs -arrive as `YASL_INPUT_DROP_FILES`. `files` is a `text/uri-list` string separated by +arrive as `YASL_EVENT_DROP`. `text.data` is a `text/uri-list` string separated by CRLF, not a list of native paths. Parse URL encoding, skip blank/comment lines, and decide which schemes/hosts your application accepts before opening files. diff --git a/docs/migrating.md b/docs/migrating.md index 395072e..e1f5442 100644 --- a/docs/migrating.md +++ b/docs/migrating.md @@ -12,10 +12,34 @@ Replace manual dispatch/poll/flush loops with the runner and request redraws wit `yasl_surface_request_frame()`. Present the frame context with `yasl_frame_present_cpu()`; the runner destroys remaining surfaces on exit. -Unified pointer button and motion events retain `device` and tablet axes. -Handle `YASL_EVENT_INPUT_RESET` by clearing held input and active strokes, just -as for the core API's `YASL_INPUT_RESET`. Window state remains a `YASL_STATE_*` -bitmask; `YASL_STATE_TILED` is reported for tiled Wayland toplevels. +Window state remains a `YASL_STATE_*` bitmask; `YASL_STATE_TILED` is reported +for tiled Wayland toplevels. + +## Events + +The core API and the runner now share one `struct yasl_event`, declared in +`<yasl/yasl.h>`. `yasl_surface_poll_event()` returns the same events that +`yasl_app_desc.event` receives, so input handling code works under both. + +| Previous use | Replacement | +| --- | --- | +| `yasl_surface_input_poll()`, `struct yasl_input_event` | `yasl_surface_poll_event()`, `struct yasl_event` | +| `event.kind`, `YASL_INPUT_*` | `event.type`, `YASL_EVENT_*` | +| `YASL_INPUT_MOUSE` with `mouse.kind` | `YASL_EVENT_POINTER_DOWN`, `_UP`, `_MOTION`, `_SCROLL`, `_LEAVE` with `event.pointer` | +| Runner `YASL_EVENT_MOUSE_BUTTON` with `pressed` | `YASL_EVENT_POINTER_DOWN` / `_UP` | +| Integer `button` 0/1/2 | `YASL_BUTTON_PRIMARY`, `_MIDDLE`, `_SECONDARY`, `_BACK`, `_FORWARD` | +| `paste.text`, `drop_files.files`, `text.text` | `text.data` for `PASTE`, `DROP`, and `TEXT` | +| `YASL_INPUT_DROP_FILES` / `YASL_EVENT_DROP_FILES` | `YASL_EVENT_DROP` | +| `YASL_EVENT_WINDOW_FOCUS` | `YASL_EVENT_FOCUS` | +| `YASL_EVENT_WINDOW_SCALE_CHANGED` | `YASL_EVENT_WINDOW_RESIZE` with `resize.scale_changed` | +| `YASL_EVENT_WINDOW_CLOSE_REQUEST` | `YASL_EVENT_WINDOW_CLOSE` | +| `user.type` | `user.code` | +| `key.repeat` | `key.action == YASL_KEY_REPEAT` | +| `yasl_surface_set_mouse_mode()` | `yasl_surface_set_pointer_mode()` | + +Every event carries a monotonic `time_ns`. Pointer motion carries `delta` on +both paths. Handle `YASL_EVENT_INPUT_RESET` by clearing held input and active +strokes. ## Window creation @@ -40,7 +64,7 @@ provide application notifications through `yasl_app_desc.event` and `.frame`. | 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 | +| Advisory `key.text` character | `YASL_EVENT_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 @@ -49,7 +73,7 @@ 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 +Text comes only from `YASL_EVENT_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. @@ -57,7 +81,7 @@ 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 +`pointer.scroll.x` and `.y` for `YASL_EVENT_POINTER_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 |