Pre-1.0: signatures are not frozen. ABI 1.4. Generated from
native/runtime/include/aster.h; the declarations and comments below are the header's own text. The header is meant to ship with the runtime binaries.
Overview (the header's introduction)
aster.h: the public C ABI of the Aster Runtime (ABI 1.4).
Copyright (c) Barnyard Greens LLC
MIT License
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of
the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.
This licence covers this header only. The Aster Runtime binaries that implement it are under the separate
Aster Runtime EULA.
The model is declarative. Your code keeps its own state and describes the screen as JSON:
{"type":"col","gap":4,"children":["Hello",{"type":"button","text":"Add one","action":"add"}]}
Clicks arrive on the UI thread as JSON events; answer them by setting a new view and/or state.
All strings are UTF-8 and NUL-terminated. Functions returning int give 0 on success and -1 on failure;
functions returning a pointer give NULL on failure. aster_last_error() says why, on the same thread.
Threading. An app belongs to the thread that created it (the UI thread). aster_app_set_view,
aster_app_set_state and aster_app_set_theme may be called from any thread at any time, including from inside
the event callback; every other function that takes the app must be called on the UI thread. The three setters
never touch the app itself: they check their argument (bad JSON or an unknown theme fails), queue the update
and wake the window. The UI thread applies queued updates in the run loop before the next frame, at the start
of its next call on the app (before it reads the app or invokes the event callback), and when the event
callback returns. A queued update is either applied or dropped (when the window has closed, or at
aster_app_free); a setter never fails because the window closed. Events are delivered only on the UI thread.
Any other function called off the UI thread fails with error code wrong-thread and changes nothing;
aster_app_free called off the UI thread frees nothing, so the UI thread can still free the app later.
Lifetime: the app pointer is valid from aster_app_new until aster_app_free. aster_app_free must be called on
the UI thread, and only after every other thread has stopped calling functions with the pointer and none of
those calls is still in progress; a setter racing with aster_app_free is still safe: its update is dropped, or it fails with error code stale-handle. A freed handle stays stale for the life of the process: its address is never reused for a later app (each freed app keeps its small handle allocation, 96 bytes on x64, reserved; the engine it owned is released). While a call on
the app is still in progress on the UI thread (the event callback runs inside aster_app_click, aster_app_type
and aster_app_run), aster_app_free fails with error code wrong-time and frees nothing; free the app after
that call returns. The version and error functions work on any thread; aster_last_error is per thread.
Types and functions
AsterApp
typedef struct AsterApp AsterApp;AsterEventFn
typedef void (*AsterEventFn)(void *user, const char *event_json);event_json, valid only during the call:
* {"type":"action"|"change","action":"<action>","key":"<key>","state":{...},
* "selection":{"<key>":{"start":n,"end":n,"caret":n}}}
* "action": a button, menu item, command palette entry or keyboard shortcut fired. (ABI 1.0 sent "click")
* "change": the user changed state the host has not seen (typing, a switch, a tab, a slider). (ABI 1.1)
* State the host set itself with aster_app_set_state is not echoed back as a change.
* selection positions are character indices into text inputs and text areas. (ABI 1.1)aster_abi_version
uint32_t aster_abi_version(void);major << 16 | minor; check major == ASTER_ABI_MAJOR
aster_runtime_version
const char *aster_runtime_version(void);static, do not free
aster_last_error
const char *aster_last_error(void);this thread's last error, "" when none
aster_free
void aster_free(char *s);free strings returned by aster_app_tree / aster_app_state
aster_app_new
AsterApp *aster_app_new(const char *desc_json);desc_json (may be NULL): {"title","width","height","scale","theme","clock":"auto"|"manual","state":{...},"view":...}
* themes: dark (default), light, mission_dark, mission_light, mission_dusk, paper_dark, paper_light, high_contrast_dark, high_contrast_lightaster_app_free
void aster_app_free(AsterApp *app);UI thread, after other threads stopped and no call on app is in progress
aster_app_set_view
int aster_app_set_view(const AsterApp *app, const char *view_json);Any thread (see Threading above).aster_app_set_state
int aster_app_set_state(const AsterApp *app, const char *state_json);merge a JSON object
aster_app_on_event
int aster_app_on_event(const AsterApp *app, AsterEventFn cb, void *user);aster_app_run
int aster_app_run(const AsterApp *app);opens the window, blocks until closed; once per app
aster_app_click
int aster_app_click(const AsterApp *app, const char *label);Headless (before or instead of run): what an LLM or a test uses to see and drive the app.aster_app_shot
int aster_app_shot(const AsterApp *app, const char *png_path);aster_app_tree
char *aster_app_tree(const AsterApp *app);free with aster_free
aster_app_state
char *aster_app_state(const AsterApp *app);free with aster_free
aster_app_type
int aster_app_type(const AsterApp *app, const char *text);type into the focused element (ABI 1.1)
aster_app_set_theme
int aster_app_set_theme(const AsterApp *app, const char *theme);Any thread, queued (see Threading above). (ABI 1.1)aster_app_set_clock
int aster_app_set_clock(const AsterApp *app, int manual);0 auto (default), 1 manual
Headless clock, for offline rendering (ABI 1.2). The animation clock is injected, never the wall clock.
* Default ("auto"): click, type and the setters leave the app settled, so a shot never shows a half-open dialog.
* "manual" (desc_json {"clock":"manual"}, or aster_app_set_clock(app, 1)): click, type, set_state, set_view and
* set_theme only START motion; aster_app_advance plays it, one frame per call, so a video renderer can shoot
* every in-between frame. Same calls, same pixels.aster_app_advance
int aster_app_advance(const AsterApp *app, double ms);clock += ms (fractions carry), render that frame
aster_app_animating
int aster_app_animating(const AsterApp *app);1 motion running or timer pending, 0 at rest, -1 error
aster_app_pointer
int aster_app_pointer(const AsterApp *app, int kind, double x, double y);Headless input and pixels (ABI 1.4): what a test, a recorder or another toolkit's host uses to drive the app
* like a person would and read the frame back without a PNG. Coordinates are logical pixels (as in the view);
* pixels are device pixels (logical size * scale). Each input call settles like aster_app_click, unless the clock
* is manual, and reports state changes through the event callback. UI thread only.press at (x, y)release at (x, y)the pointer left the window; x and y are ignored but must be finitemove + press + releaseaster_app_wheel
int aster_app_wheel(const AsterApp *app, double x, double y, double dy);dy > 0 scrolls down; a notch is 40
aster_app_key
int aster_app_key(const AsterApp *app, const char *chord);"enter", "ctrl+s", "shift+tab", "a": press + release
aster_app_focus
int aster_app_focus(const AsterApp *app, const char *id);aster_app_resize
int aster_app_resize(const AsterApp *app, uint32_t width, uint32_t height, double scale);width, height: logical px, 64..16384 each; scale 0.25..8
aster_app_pixels
int aster_app_pixels(const AsterApp *app, uint8_t *rgba, size_t capacity, uint32_t *width, uint32_t *height);Straight RGBA, 4 bytes per device pixel, rows top to bottom. Writes the size to *width and *height (either may be
* NULL). rgba NULL: only report the size. Fails (copying nothing) when capacity < width * height * 4.