From c059e3aa7f93da470f052a5cd8ee0d8dc969e679 Mon Sep 17 00:00:00 2001 From: Berke Güzel Date: Tue, 13 Oct 2026 13:44:13 +0300 Subject: rename and simplification --- docs/api-policy.md | 4 ++-- docs/getting-started.md | 6 ++++-- docs/guide.md | 20 +++++++++++++++++++- docs/migrating.md | 19 +++++++++++++++++-- 4 files changed, 42 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/api-policy.md b/docs/api-policy.md index d5c7159..0c8f040 100644 --- a/docs/api-policy.md +++ b/docs/api-policy.md @@ -12,8 +12,8 @@ across releases, mix headers and binaries from different revisions, or persist public structs as a file/network format. The package version is available through `pkg-config --modversion yasl`. -See [migration notes](migrating.md) for the portable keyboard and fractional -scroll API changes. +See [migration notes](migrating.md) for window creation, portable keyboard, and +fractional scroll API changes. API changes should keep ordinary CPU drawing usable with only `` and the C standard library. Prefer an explicit capability and an ordinary diff --git a/docs/getting-started.md b/docs/getting-started.md index ff40a9b..d21c9bd 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -78,9 +78,11 @@ can be included from C++11 or newer; the library itself builds as C23. 1. Open a display with `yasl_display_open(NULL, &spec)`. NULL creates a loop owned by the display. Supply your own loop only when you need shared loop ownership. -2. Create a toplevel with a positive **logical-pixel** size and install callbacks. +2. Create a toplevel with `yasl_window_spec`: supply a positive **logical-pixel** + size, a `yasl_window_cbs` table in `cbs`, and callback userdata in `ud`. Zero-initialize every option and callback struct. Callback tables are copied; - userdata must remain alive. Registration can call back synchronously. + userdata must remain alive. The new window's callbacks start after creation + returns. Read initial geometry with `yasl_surface_geometry()`. 3. Schedule the initial redraw. `draw` receives a borrowed target. Fill every pixel with premultiplied `0xAARRGGBB`, then present that exact target, once. 4. Dispatch, drain input for every live surface queue, update application state, diff --git a/docs/guide.md b/docs/guide.md index 43a7a1e..adcacc8 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -37,11 +37,29 @@ server. A capability does not guarantee every related action: Cocoa currently returns false for interactive resize and window-menu requests even though it advertises CSD. Check each result and provide an application fallback. +## Window creation and callbacks + +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 +`ud`. One display can own multiple windows with separate callback tables. + +The window copies its callbacks during creation. Its callbacks cannot run before +creation returns, so the application can store the returned surface first. +Userdata stays borrowed until callbacks are replaced or the surface is destroyed. +Read initial geometry with `yasl_surface_geometry()`; creation does not guarantee +an initial `configure` notification. Request the first redraw once application +state is ready. `yasl_surface_set_callbacks()` replaces callbacks later and also +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`. + ## Geometry and scaling | Value | Units | | --- | --- | -| Toplevel `yasl_surface_spec.size` | Logical pixels | +| Toplevel `yasl_window_spec.size` | Logical pixels | | `yasl_geometry.size`, framebuffer size | Device pixels | | Pointer position, caret, window-menu position | Device pixels, relative to the surface | | Damage rectangles | Device pixels, relative to the draw target | diff --git a/docs/migrating.md b/docs/migrating.md index d224cd4..da4e591 100644 --- a/docs/migrating.md +++ b/docs/migrating.md @@ -2,8 +2,23 @@ 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. +See the [application guide](guide.md) for the full window and input workflow. + +## Window creation + +Rename `struct yasl_surface_spec` to `struct yasl_window_spec` and +`struct yasl_surface_cbs` to `struct yasl_window_cbs`. Surface handles and +functions retain their names. Supply the window's callback table in `spec.cbs` +and its userdata in `spec.ud` when calling `yasl_surface_create_toplevel()` or +`yasl_surface_create_native()`. Callback tables are copied, and userdata is +borrowed. The new window's callbacks cannot run before creation returns; read +initial geometry with `yasl_surface_geometry()` and request the first redraw +after initializing application state. + +`yasl_surface_set_callbacks()` remains available to replace callbacks after +creation and to configure popups. A NULL `spec.cbs` creates a window without +callbacks. Displays owned by `yasl_run()` use the runner's callbacks instead; +provide application notifications through `yasl_app_desc.event` and `.frame`. ## Keyboard events -- cgit v1.2.3