API reference

C ABI reference: aster.h

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)

Text
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);
Text
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);
Text
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_light

aster_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);
Text
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);
Text
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);
Text
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

Text
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);
Text
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.
Text
press at (x, y)
Text
release at (x, y)
Text
the pointer left the window; x and y are ignored but must be finite
Text
move + press + release

aster_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);
Text
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.