From 98f0d51157fa2a2b8ccaae54ed4850a88d223d01 Mon Sep 17 00:00:00 2001 From: Berke Güzel Date: Tue, 13 Oct 2026 15:05:06 +0300 Subject: Simplify surface state, examples, and library installation --- docs/guide.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) (limited to 'docs/guide.md') diff --git a/docs/guide.md b/docs/guide.md index adcacc8..1bd1aef 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -39,6 +39,22 @@ it advertises CSD. Check each result and provide an application fallback. ## Window creation and callbacks +All examples include `` and call `yasl_run()` with a +`yasl_app_desc`. Create surfaces in `init`, handle `YASL_EVENT_*` notifications +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. + +Unified pointer button and motion events retain `device` and `pen` axes, +including erasers and pressure-only motion. Cancel held input or active strokes +on `YASL_EVENT_INPUT_RESET`, pointer leave, or focus loss. Reset also starts the +next motion delta from zero. [hello.c](../examples/hello.c) shows the minimal +lifecycle; [tablet.c](../examples/tablet.c) demonstrates device-aware drawing. + +For applications managing their own event loop, use the core API below. + Open the display with application-wide options and notifications in `yasl_display_spec`. Create each toplevel with `yasl_window_spec`, including its title, logical size, optional `yasl_window_cbs` table in `cbs`, and userdata in @@ -55,6 +71,14 @@ installs popup callbacks; the setter does not invoke the callbacks. When using `yasl_run()`, its runner installs callbacks for windows on its display. Use `yasl_app_desc.event` and `.frame` rather than `yasl_window_spec.cbs` and `.ud`. +Read window state with `yasl_surface_state()`. Its `YASL_STATE_*` flags can +coexist, and the `state` callback receives the same current bitmask. Wayland +also reports `YASL_STATE_TILED` when any window edge is tiled; X11 and Cocoa +currently leave that flag unset. Unsupported flags are absent. On Wayland, an +ordinary floating toplevel has fullscreen, maximized, and tiled all absent. +`YASL_STATE_SUSPENDED` describes repaint suspension rather than minimization; +there is no portable minimized flag. + ## Geometry and scaling | Value | Units | @@ -301,7 +325,7 @@ signals the loop pipe but is not a portable cross-thread event-posting API. Portable CPU drawing needs no native headers. Opt into `` and ``, ``, or `` when -integrating a platform API. Typed headers and functions are installed only for +integrating a platform API. Typed native functions are exported only for built backends. Accessors return borrowed handles and zero/NULL for the wrong backend. Do not pass freed objects, destroy borrowed handles, independently dispatch native connections, or change surface roles and buffer ownership. -- cgit v1.2.3