diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/getting-started.md | 4 | ||||
| -rw-r--r-- | docs/guide.md | 41 |
2 files changed, 42 insertions, 3 deletions
diff --git a/docs/getting-started.md b/docs/getting-started.md index 73af4ab..5e569fe 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -20,7 +20,8 @@ Use a C23 compiler, Meson 1.6 or newer, and Ninja. GCC and Clang can build the l | --- | --- | | Wayland | `wayland-client`, `wayland-cursor`, `xkbcommon` | | X11 | `x11`, `xi`, `xkbcommon`, `xext`; optional `xrandr` | -| Cocoa | macOS 14+ SDK with AppKit, Metal, and QuartzCore; Metal-capable device | +| Linux desktop services | Optional `dbus-1` for notifications and appearance | +| Cocoa | macOS 14+ SDK with AppKit, Metal, QuartzCore, and UserNotifications; Metal-capable device | ```sh meson setup build @@ -32,6 +33,7 @@ meson test -C build --print-errorlogs Each Linux backend defaults to `auto`, meaning build it when its dependencies are available. Require one with `-Dwayland=enabled` or `-Dx11=enabled`; omit one with `-Dwayland=disabled` or `-Dx11=disabled`. At least one backend is required. +`-Ddbus` works the same way for the optional D-Bus desktop services. Cocoa is selected on macOS and requires no extra third-party dependencies. Its minimum deployment target is macOS 14. Set `MACOSX_DEPLOYMENT_TARGET=14.0` (or newer) before configuring if your toolchain defaults to an older target. diff --git a/docs/guide.md b/docs/guide.md index 61583b1..7f02ab7 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -1,8 +1,8 @@ # Application guide The contracts in [yasl.h](../include/yasl/yasl.h), [loop.h](../include/yasl/loop.h), -[timing.h](../include/yasl/timing.h), and [native.h](../include/yasl/native.h) are -the reference for individual calls. All examples here use the display's opening +[timing.h](../include/yasl/timing.h), [desktop.h](../include/yasl/desktop.h), and +[native.h](../include/yasl/native.h) are the reference for individual calls. All examples here use the display's opening thread, which must be the main thread on macOS. Userdata stays owned by the application. Copy borrowed data before retaining it beyond its documented life. @@ -363,6 +363,43 @@ and restores the previous action on unwatch. YASL leaves thread signal masks alone: a watched signal must stay unblocked in at least one thread. Only one loop can watch a given signal at a time. +## Desktop services + +Include `<yasl/desktop.h>` for services that sit next to windowing. Display and +surface calls use the display thread; path and locale calls work from any +thread. + +| Call | Linux | Cocoa | +| --- | --- | --- | +| `yasl_display_open_uri()` | `xdg-open` from `PATH` | NSWorkspace | +| `yasl_display_notify()` | Notifications service over D-Bus | User notifications; app bundle required | +| `yasl_display_appearance()` | Settings portal over D-Bus, then `GTK_THEME` | Effective appearance and increase-contrast setting | +| `yasl_surface_bell()` | Wayland xdg-system-bell; X11 XKB bell | `NSBeep` | +| `yasl_executable_path()` | `/proc/self/exe` | Executable path, resolved | +| `yasl_resource_dir()` | Always zero | App bundle resources | +| `yasl_default_locale()` | `LC_ALL`, `LC_CTYPE`, `LANG`, then `C.UTF-8` | Current language and region | + +`yasl_display_open_uri()` checks only that the URI has a scheme. Decide which +schemes and hosts your application trusts before calling it, for example +before opening a link from untrusted text. On Linux the opener starts in its +own session with default signal handling and none of the application's +descriptors above stderr. D-Bus services need YASL built with `dbus-1`; without +it, notifications return false and appearance falls back to `GTK_THEME`. +Appearance changes send no notification, so query again when a window gains +focus. + +Functions that fill a buffer return the full length, excluding the NUL. A +result less than the buffer size means the string was written. Otherwise the +buffer is unchanged, so call again with a larger one: + +```c +char path[4096]; +size_t len = yasl_executable_path(path, sizeof(path)); +if (len == 0 || len >= sizeof(path)) { + /* No path, or a longer buffer is needed. */ +} +``` + ## Native interoperability Portable CPU drawing needs no native headers. Opt into `<yasl/native.h>` and |