diff options
Diffstat (limited to 'docs/guide.md')
| -rw-r--r-- | docs/guide.md | 20 |
1 files changed, 19 insertions, 1 deletions
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 | |