This page documents every function in aster.h at ABI 1.4: 25 functions, one entry each. It is derived from the header and from the runtime source (native/runtime/src/lib.rs) at aster-ui f19b91bcd, and every example below was compiled and run against a build of that source on Linux (see "How this page was checked"). Where something could not be confirmed from the source or by running it, the entry says not verified.
The runtime is a native library (libaster_runtime.so on Linux, aster_runtime.dll on Windows) plus the aster command-line tool. Your program keeps its own state, describes the screen as JSON, and receives user actions as JSON events.
The model in one screen
/* The setup every example on this page shares. */
#include "aster.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
/* A small app: a heading, a text field bound to state key "name", and a button that fires the action "add". */
static const char *COUNTER =
"{\"title\":\"Counter\",\"width\":360,\"height\":240,"
"\"state\":{\"count\":0,\"name\":\"\"},"
"\"view\":{\"type\":\"col\",\"gap\":4,\"pad\":6,\"children\":["
"{\"type\":\"heading\",\"title\":\"Counter\"},"
"{\"type\":\"text_field\",\"key\":\"name\",\"placeholder\":\"Your name\"},"
"{\"type\":\"button\",\"text\":\"Add one\",\"action\":\"add\"}]}}";aster_app_newcreates an app from a JSON descriptor. The calling thread becomes the app's UI thread.- You describe the screen with
aster_app_set_viewand your data withaster_app_set_state. - You register one event callback with
aster_app_on_event. It runs on the UI thread when the user clicks, types, flips a switch and so on. - Either
aster_app_runopens a window and blocks until it closes, or you drive the app headless (aster_app_click,aster_app_shot,aster_app_tree, ...), which is what tests, recorders and LLM agents use. aster_app_freereleases the app.
Conventions that apply to every function
- Strings are UTF-8 and NUL-terminated. A NULL string argument fails with an error naming the argument ("
labelis NULL"). A string that is not valid UTF-8 fails the same way. - Return values. Functions that return
intgive0on success and-1on failure, exceptaster_app_animating(see its entry). Functions that return a pointer give NULL on failure. - Errors. On failure the function stores a message you read with
aster_last_error()on the same thread. The message ends with a stable code and a help link, for example... [aster error wrong-thread: https://barnyardgreens.farm/aster/errors/wrong-thread]. The codes in this build are:wrong-thread,bad-json,unknown-theme,click-target-missing,duplicate-key,state-loop,already-ran,wrong-time,no-display,image-load,stale-handle,bad-argument,internal,other. The view layer adds its own, for exampleunknown-type(seen in the tree text below). The code is derived from the message text (error_codeinlib.rs), so treat it as a hint and the message as the source of truth. Whether the help pages at that link are live was not checked. - Panics never cross the boundary. Every entry point catches panics and turns them into a
-1/NULL with codeinternal. - Thread rules are summarised in the table below and repeated in each entry.
| Function | Thread |
|---|---|
aster_abi_version, aster_runtime_version, aster_last_error, aster_free | any |
aster_app_set_view, aster_app_set_state, aster_app_set_theme | any, queued |
every other aster_app_* | the UI thread only (the one that called aster_app_new) |
"UI thread only" means: called from another thread the function fails with code wrong-thread and changes nothing. aster_app_free from another thread frees nothing.
Lifetime and ownership at a glance
- The
AsterApp *is valid fromaster_app_newuntilaster_app_free. Free it on the UI thread, after every other thread has stopped using it. - The runtime never keeps your string arguments past the call. It copies what it needs.
- Strings the runtime returns (
aster_app_tree,aster_app_state) are yours: release them withaster_free, never withfree. aster_runtime_versionandaster_last_errorreturn pointers you do not free. The first is static. The second belongs to the calling thread and is overwritten by the next failing call on that thread.- The
event_jsonstring given to your callback is valid only during the callback. Copy it if you need it later.
Library functions
aster_abi_version
uint32_t aster_abi_version(void);Returns the ABI the loaded library implements as major << 16 | minor. This build returns 0x00010004 (1.4). Majors break, minors only add functions, so check major == ASTER_ABI_MAJOR and the minor against the first version that has the function you need (the header marks each addition: 1.1, 1.2, 1.4).
- Ownership: returns a value, nothing to free.
- Threading: any thread.
- Errors: cannot fail.
/* example: aster_abi_version */
static void example_aster_abi_version(void) {
uint32_t abi = aster_abi_version();
if ((abi >> 16) != ASTER_ABI_MAJOR) { printf("incompatible runtime\n"); return; }
printf("ABI %u.%u\n", abi >> 16, abi & 0xffff);
}aster_runtime_version
const char *aster_runtime_version(void);Returns the runtime's product version string, for example "0.1.0".
- Ownership: static storage; do not free.
- Threading: any thread.
- Errors: cannot fail.
/* example: aster_runtime_version */
static void example_aster_runtime_version(void) {
printf("Aster Runtime %s\n", aster_runtime_version());
}aster_last_error
const char *aster_last_error(void);Returns the message of the last failure on the calling thread, or "" when this thread has not had one yet.
- Ownership: the pointer belongs to the runtime. It stays valid until the next failing call on the same thread, which replaces the message. Copy the text if you need it longer.
- Threading: any thread; the message is per thread, so read it on the thread that made the failing call. A failure on a worker thread (for example a setter given bad JSON) is not visible on the UI thread.
- Errors: cannot fail.
- Note: a successful call does not clear the message (checked in the source and by running it: after a failed call, a later successful
aster_app_set_stateleft the old text in place). Test the return value of the call, notaster_last_error().
/* example: aster_last_error */
static void example_aster_last_error(void) {
AsterApp *app = aster_app_new("{\"theme\":\"plaid\"}"); /* no such theme */
if (!app) printf("new failed: %s\n", aster_last_error());
}aster_free
void aster_free(char *s);Releases a string returned by aster_app_tree or aster_app_state. NULL is accepted and ignored.
- Ownership: takes back a runtime-allocated string. Use this and nothing else: the string comes from the runtime's allocator, so
free()is wrong. Freeing the same pointer twice, or a pointer the runtime did not return, is undefined behavior. - Threading: any thread (the source does not check the thread). Not otherwise synchronised: do not free one pointer from two threads.
- Errors: cannot fail.
/* example: aster_free */
static void example_aster_free(void) {
AsterApp *app = aster_app_new(COUNTER);
char *tree = aster_app_tree(app);
if (tree) printf("%zu bytes of tree\n", strlen(tree));
aster_free(tree); /* never free(tree) */
aster_free(NULL); /* fine */
aster_app_free(app);
}App lifecycle
aster_app_new
AsterApp *aster_app_new(const char *desc_json);Creates an app. desc_json may be NULL or "" (an empty app with an empty view). Otherwise it is a JSON object with these keys, all optional:
| key | meaning | default |
|---|---|---|
title | window title | "Aster" |
width, height | logical pixels, clamped to 64..16384 | 800 x 600 |
scale | device scale, clamped to 0.25..8 | 1 |
theme | one of the theme names in the header | dark |
clock | "auto" or "manual" (headless animation clock, see aster_app_set_clock) | "auto" |
state | initial state, a JSON object | {} |
view | initial view, a JSON object (or array) | an empty array |
gpu | "auto", "on" or "off": window GPU mode. Not mentioned in aster.h; read from the source. The ASTER_GPU environment variable overrides it. Headless calls never use the GPU. | "auto" |
- Ownership: returns a new app that you must release with
aster_app_free. NULL on failure. - Threading: any thread may create an app; the calling thread becomes the app's UI thread for life. Keep every non-setter call on that thread.
- Errors:
bad-jsonfor malformed JSON,unknown-themefor a bad theme name,bad-argumentfor non-UTF-8,otherfor an unknowngpuvalue. It does not need a display: creation is headless. - Note: a descriptor whose
viewis valid JSON but uses an unknown node type is accepted (checked): the app is created and the unknown node draws as a visible placeholder,[aster: unknown type "nonesuch" · aster error unknown-type]. Width and height below 64 are clamped (a10x10request gave a 64x64 frame, checked).
/* example: aster_app_new */
static void example_aster_app_new(void) {
AsterApp *app = aster_app_new(COUNTER);
if (!app) { printf("new failed: %s\n", aster_last_error()); return; }
AsterApp *empty = aster_app_new(NULL); /* legal: an empty app */
aster_app_free(empty);
aster_app_free(app);
}aster_app_free
void aster_app_free(AsterApp *app);Destroys an app and releases the engine it owned. Queued updates that were never applied are dropped. NULL is accepted.
- Ownership: ends the app's life. After this the pointer is stale: setters given it fail with
stale-handle(they look it up in a registry and never touch the freed memory), and the address is never reused for a later app. The runtime keeps a small allocation (96 bytes on x64) per freed app for the life of the process to guarantee that. - Threading: UI thread only, after every other thread has stopped calling functions with this pointer and none of those calls is still in progress. Called off the UI thread it frees nothing and sets
wrong-thread(checked), so the UI thread can still free it later. - Errors: (reported through
aster_last_error, no return value)wrong-threadas above.wrong-timewhen a call on the app is still in progress on the UI thread, for example freeing from inside the event callback whileaster_app_click,aster_app_typeoraster_app_runis running: it frees nothing, so free after that call returns. - Caution: only the three setters are protected against a freed pointer. Calling any other function, or
aster_app_freea second time, with an already freed pointer is not covered by the header's guarantees: treat a double free as undefined behavior. Not verified by running it.
/* example: aster_app_free */
static void example_aster_app_free(void) {
AsterApp *app = aster_app_new(COUNTER);
aster_app_free(app);
/* A setter racing with the free is safe: it fails with a stale-handle error. */
if (aster_app_set_state(app, "{\"count\":1}") != 0)
printf("after free: %s\n", aster_last_error());
}Updating the app (any thread)
These three are queued, not applied immediately. They check their argument (bad JSON or an unknown theme fails), queue the update, and wake the window. The UI thread applies the queue in the run loop before the next frame, at the start of its next call on the app, 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.
aster_app_set_view
int aster_app_set_view(const AsterApp *app, const char *view_json);Replaces the whole view. The view is a JSON node such as {"type":"col","children":[...]}; the node types are listed in the runtime's docs/view-*.md files and demonstrated by native/runtime/samples/*.json. Returns 0 or -1.
- Ownership: the string is copied (parsed) during the call.
- Threading: any thread, including from inside the event callback. Does not touch the app on the calling thread.
- Errors:
bad-jsonwhen the text is not JSON,bad-argumentfor NULL,stale-handlefor a freed or never-issued pointer. Only JSON syntax is checked on the calling thread. A well-formed JSON view with a wrong node type is accepted (returns 0, checked by running it): the unknown node draws as a placeholder text[aster: unknown type "nonesuch" · aster error unknown-type]in the tree and the frame. So a typo in a node type does not fail; look at the tree or a screenshot. - Note: the whole view is replaced, so send the complete new view, not a patch. Use state plus bound keys (a
text_fieldwith"key") for values that change often.
/* example: aster_app_set_view */
static void example_aster_app_set_view(void) {
AsterApp *app = aster_app_new(COUNTER);
if (aster_app_set_view(app,
"{\"type\":\"col\",\"pad\":6,\"children\":[{\"type\":\"text\",\"text\":\"Replaced\"}]}") != 0)
printf("set_view failed: %s\n", aster_last_error());
char *tree = aster_app_tree(app); /* applies the queued view first */
printf("%s\n", strstr(tree, "Replaced") ? "view replaced" : "view NOT replaced");
aster_free(tree);
aster_app_free(app);
}aster_app_set_state
int aster_app_set_state(const AsterApp *app, const char *state_json);Merges the keys of a JSON object into the app state. Keys you do not mention keep their values. Returns 0 or -1.
- Ownership: copied during the call.
- Threading: any thread; queued. If the same key is queued twice before the UI thread drains, the last value wins, so an unattended queue never grows beyond the size of the state.
- Errors:
bad-jsonfor bad JSON or when the value is not an object (state must be a JSON object),bad-argumentfor NULL,stale-handlefor a freed pointer. - Echo rule: state you set yourself is not reported back to your callback as a
changeevent. - Key naming:
aster_app_stateand eventstateobjects leave out keys that start with__or~and keys that contain a.(those are runtime bookkeeping such asfield.focused). Do not put dots in your own state keys if you want to read them back. - Types: JSON integers become integers, other numbers become floats, strings become text,
nullbecomes the empty string, arrays and objects become lists and records.
/* example: aster_app_set_state */
static void example_aster_app_set_state(void) {
AsterApp *app = aster_app_new(COUNTER);
aster_app_set_state(app, "{\"count\":7}");
char *st = aster_app_state(app); /* applies the queue first */
printf("%s\n", st);
aster_free(st);
aster_app_free(app);
}aster_app_set_theme
int aster_app_set_theme(const AsterApp *app, const char *theme); /* ABI 1.1 */Switches the theme by name: dark (default), light, mission_dark, mission_light, mission_dusk, paper_dark, paper_light, high_contrast_dark, high_contrast_light. The source also accepts a few spellings (case-insensitive, - and space as _, and the aliases mission, dusk, paper, contrast, high_contrast). Returns 0 or -1.
- Ownership: copied during the call.
- Threading: any thread; queued like the other setters.
- Errors:
unknown-themefor a name not in the list,bad-argumentfor NULL,stale-handlefor a freed pointer.
/* example: aster_app_set_theme */
static void example_aster_app_set_theme(void) {
AsterApp *app = aster_app_new(COUNTER);
if (aster_app_set_theme(app, "paper_light") != 0) printf("%s\n", aster_last_error());
if (aster_app_set_theme(app, "plaid") != 0) printf("expected: %s\n", aster_last_error());
aster_app_free(app);
}Events
aster_app_on_event
typedef void (*AsterEventFn)(void *user, const char *event_json);
int aster_app_on_event(const AsterApp *app, AsterEventFn cb, void *user);Sets, replaces or (with cb == NULL) clears the event callback. One callback per app. user is passed back unchanged.
The callback runs on the UI thread, inside the call that produced the event (aster_app_click, aster_app_type, the input functions, aster_app_run's loop). event_json is valid only during the call:
{"type":"action","action":"add","key":"","state":{"count":0,"name":""},"selection":{}}type: "action": a button, menu item, command palette entry or keyboard shortcut fired.actionnames it (the"action"of the node that fired). ABI 1.0 sent"click"here.type: "change": the user changed state the host has not seen (typing, a switch, a tab, a slider). Sent once per real change. ABI 1.1.state: the current host-visible state after that event.selection: caret and selection of every text input, as character indices:{"name":{"start":2,"end":5,"caret":5}}. ABI 1.1.
Inside the callback you answer with aster_app_set_view / aster_app_set_state / aster_app_set_theme. They are queued and land in the same frame as the click, when the callback returns.
- Ownership: the runtime stores
cbanduserand never freesuser. The pointer must stay valid until you clear the callback or free the app. Your callback must not free the app (it fails withwrong-time). - Threading: UI thread only (
wrong-threadotherwise). The callback is only ever invoked on the UI thread. - Errors:
wrong-thread,bad-argumentfor a NULL app. - Panics: a panic inside the runtime while it calls you is caught; the callback itself is C, so it must not unwind or
longjmpout.
/* example: aster_app_on_event */
typedef struct { int adds; } Counter;
static void on_event(void *user, const char *event_json) {
Counter *c = (Counter *)user;
if (strstr(event_json, "\"action\":\"add\"")) c->adds++;
}
static void example_aster_app_on_event(void) {
Counter c = {0};
AsterApp *app = aster_app_new(COUNTER);
aster_app_on_event(app, on_event, &c);
aster_app_click(app, "Add one");
aster_app_click(app, "Add one");
printf("adds = %d\n", c.adds);
aster_app_on_event(app, NULL, NULL); /* clear before c goes out of scope */
aster_app_free(app);
}Running a window
aster_app_run
int aster_app_run(const AsterApp *app);Opens the window and blocks until the user closes it. Returns 0 on a normal close, -1 on failure.
- Ownership: while it runs, the app belongs to the loop. When it returns, the window and its engine are gone. Afterwards only
aster_app_freeis useful; the headless functions fail with "the app has already run and closed". - Threading: UI thread only, and the window's loop runs on that thread, so it blocks there. Other threads keep using the three setters, which wake the window. Your callback runs inside the loop.
- Errors:
already-ranif the app has run before (once per app),no-displaywhen no display can be opened (checked on Linux with noDISPLAY/WAYLAND_DISPLAY: the message names the missing variables),wrong-thread. A failed run still consumes the app (checked): the secondaster_app_rungavealready-ranandaster_app_stategave "the app has already run and closed". Create a new app to retry, for example after fixing the display. While the window is running,aster_app_state,aster_app_tree,aster_app_shotand the other headless calls fail withwrong-time("not available while the window is running"); use thestatefield of the events instead. - GPU: a window installs the GPU frame accelerator when one is available and falls back to CPU drawing otherwise (source comment). The headless functions never use it, so shots and pixels are always the CPU renderer's bytes.
- Not run here: opening a window needs a display. This page's examples ran headless; the
aster_app_runexample was compiled but not run.
/* example: aster_app_run */
static void on_action(void *user, const char *event_json) {
AsterApp *app = (AsterApp *)user;
if (strstr(event_json, "\"action\":\"add\""))
aster_app_set_state(app, "{\"count\":1}"); /* a setter may be called from the callback */
}
static int example_aster_app_run(void) {
AsterApp *app = aster_app_new(COUNTER);
if (!app) return 1;
aster_app_on_event(app, on_action, app);
int rc = aster_app_run(app); /* blocks until the window closes */
if (rc != 0) printf("run failed: %s\n", aster_last_error());
aster_app_free(app);
return rc;
}Headless driving
Everything in this section is UI thread only, fails with wrong-time while a window is running, and can run with no display at all. In the default clock mode each call leaves the app settled (animations finished) so a screenshot never shows a half-open dialog. With the manual clock (see aster_app_set_clock) calls only start motion.
aster_app_click
int aster_app_click(const AsterApp *app, const char *label);Clicks the element whose label (or key) is label, settles, and fires the event callback (an action event, then a change event if state changed). Returns 0 or -1.
- Ownership:
labelis only read during the call. - Threading: UI thread only.
- Errors:
click-target-missingwhen no interactive element has that label ("no interactive target"),wrong-thread,wrong-time,bad-argument. The callback is invoked synchronously, so a callback that callsaster_app_freegetswrong-time.
/* example: aster_app_click */
static void example_aster_app_click(void) {
AsterApp *app = aster_app_new(COUNTER);
if (aster_app_click(app, "Add one") != 0) printf("%s\n", aster_last_error());
if (aster_app_click(app, "Nonexistent") != 0) printf("expected: %s\n", aster_last_error());
aster_app_free(app);
}aster_app_type
int aster_app_type(const AsterApp *app, const char *text); /* ABI 1.1 */Types text into the focused element. Click or focus an input first. After typing it settles (default clock) and reports the state change through the callback. Returns 0 or -1.
- Ownership:
textis read during the call. - Threading: UI thread only.
- Errors:
wrong-thread,wrong-time,bad-argument. With nothing focused the call returns 0 and changes nothing (checked): it does not tell you the text went nowhere, so focus first (aster_app_focusor a click).
/* example: aster_app_type */
static void example_aster_app_type(void) {
AsterApp *app = aster_app_new(COUNTER);
aster_app_focus(app, "name");
aster_app_type(app, "Ada");
char *st = aster_app_state(app);
printf("%s\n", st); /* the name key now reads "Ada" */
aster_free(st);
aster_app_free(app);
}aster_app_shot
int aster_app_shot(const AsterApp *app, const char *png_path);Renders the current frame and writes it as a PNG file. This is the call to use when you want to look at what the app draws. Returns 0 or -1.
- Ownership:
png_pathis read during the call; the file is written by the runtime. The image is device pixels (logical size x scale). - Threading: UI thread only.
- Errors:
wrong-thread,wrong-time,bad-argument, and anothererror when the file cannot be written (the message carries the OS error). Writing twice to the same path succeeds and overwrites (checked). A directory that cannot be written gives anothererror whose message carries the OS error.
/* example: aster_app_shot */
static void example_aster_app_shot(const char *path) {
AsterApp *app = aster_app_new(COUNTER);
if (aster_app_shot(app, path) != 0) printf("%s\n", aster_last_error());
aster_app_free(app);
}aster_app_tree
char *aster_app_tree(const AsterApp *app);Returns the semantic tree as text: every labelled element with its role and rectangle. NULL on failure.
- Ownership: a new string you must release with
aster_free. - Threading: UI thread only.
- Errors:
wrong-thread,wrong-time. - Note: the text format is for people and test assertions (search it with
strstr); it is not documented as a stable machine format.
/* example: aster_app_tree */
static void example_aster_app_tree(void) {
AsterApp *app = aster_app_new(COUNTER);
char *tree = aster_app_tree(app);
if (tree) printf("%s", tree);
aster_free(tree);
aster_app_free(app);
}aster_app_state
char *aster_app_state(const AsterApp *app);Returns the current host-visible state as a JSON object. NULL on failure.
- Ownership: a new string; release with
aster_free. - Threading: UI thread only. Not available while the window runs (
wrong-time). - Errors:
wrong-thread,wrong-time. - Note: runtime-internal keys (starting
__or~, or containing.) are left out.
/* example: aster_app_state */
static void example_aster_app_state(void) {
AsterApp *app = aster_app_new(COUNTER);
char *st = aster_app_state(app);
printf("%s\n", st);
aster_free(st);
aster_app_free(app);
}Headless clock (ABI 1.2)
Offline rendering injects the animation clock; it never reads the wall clock. That is what makes a recorded video frame-exact.
aster_app_set_clock
int aster_app_set_clock(const AsterApp *app, int manual); /* 0 auto, 1 manual */Chooses the headless clock. 0 (auto, the default): every headless call leaves the app settled. Non-zero (manual): click, type, set_state, set_view and set_theme only start motion; aster_app_advance plays it. You can also choose it at creation with "clock":"manual". Returns 0 or -1.
- Threading: UI thread only.
- Errors:
wrong-thread,bad-argument(NULL app).
/* example: aster_app_set_clock */
static void example_aster_app_set_clock(void) {
AsterApp *app = aster_app_new(COUNTER);
aster_app_set_clock(app, 1); /* manual */
aster_app_set_clock(app, 0); /* back to auto */
aster_app_free(app);
}aster_app_advance
int aster_app_advance(const AsterApp *app, double ms);Moves the animation clock forward by ms milliseconds (fractions carry to the next call, so 33.33 ms steps stay exact) and renders that frame. Works in either clock mode; in manual mode it is the only thing that plays motion. Same calls give the same pixels. Returns 0 or -1.
- Threading: UI thread only.
- Errors: fails when
msis negative, NaN or infinite ("ms must be a finite number of milliseconds, 0 or more"); a single call advances at most one hour (3,600,000 ms; longer values are capped, not rejected). Alsowrong-thread,wrong-time.
/* example: aster_app_advance */
static void example_aster_app_advance(void) {
AsterApp *app = aster_app_new("{\"clock\":\"manual\",\"width\":320,\"height\":200,"
"\"view\":{\"type\":\"text\",\"text\":\"Hi\"}}");
for (int i = 0; i < 3; i++) {
if (aster_app_advance(app, 1000.0 / 60.0) != 0) { printf("%s\n", aster_last_error()); break; }
/* aster_app_shot(app, "frame.png") here to capture each frame */
}
aster_app_free(app);
}aster_app_animating
int aster_app_animating(const AsterApp *app);Returns 1 when more time would change the picture (a transition is running or a timer is pending), 0 when the app is at rest, -1 on error. An endless motion such as a spinner counts as animating.
- Threading: UI thread only.
- Errors:
-1withwrong-threadorwrong-time. This is the oneintfunction where-1is not the only non-zero result: test== 1, not!= 0.
/* example: aster_app_animating */
static void example_aster_app_animating(void) {
AsterApp *app = aster_app_new(COUNTER);
int a = aster_app_animating(app);
if (a < 0) printf("%s\n", aster_last_error());
else printf("animating: %d\n", a);
aster_app_free(app);
}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 and read the frame back without a PNG. Coordinates are logical pixels (the units of the view). Pixels are device pixels (logical size x scale). Each input call settles like aster_app_click unless the clock is manual, and reports state changes through the callback. All of them are UI thread only.
aster_app_pointer
#define ASTER_POINTER_MOVE 0
#define ASTER_POINTER_DOWN 1
#define ASTER_POINTER_UP 2
#define ASTER_POINTER_LEAVE 3
#define ASTER_POINTER_CLICK 4
int aster_app_pointer(const AsterApp *app, int kind, double x, double y);Moves, presses, releases, leaves the window, or does a whole click (move, press, release) at logical (x, y). For ASTER_POINTER_LEAVE the coordinates are ignored but must be finite. Returns 0 or -1.
- Errors: an unknown
kindfails (message lists 0 to 4), non-finitexoryfails, pluswrong-thread,wrong-time. - Use: hover effects (
MOVE), drags (DOWN,MOVE,UP), and clicking by position when an element has no label.
/* example: aster_app_pointer */
static void example_aster_app_pointer(void) {
AsterApp *app = aster_app_new(COUNTER);
aster_app_pointer(app, ASTER_POINTER_MOVE, 40, 60);
aster_app_pointer(app, ASTER_POINTER_CLICK, 40, 60);
aster_app_pointer(app, ASTER_POINTER_LEAVE, 0, 0);
if (aster_app_pointer(app, 99, 0, 0) != 0) printf("expected: %s\n", aster_last_error());
aster_app_free(app);
}aster_app_wheel
int aster_app_wheel(const AsterApp *app, double x, double y, double dy);One wheel step at (x, y). dy > 0 scrolls down (content moves up); a notch is 40 logical pixels. Returns 0 or -1.
- Errors: non-finite
x,yordyfails;wrong-thread,wrong-time.
/* example: aster_app_wheel */
static void example_aster_app_wheel(void) {
AsterApp *app = aster_app_new(COUNTER);
if (aster_app_wheel(app, 100, 100, 40) != 0) printf("%s\n", aster_last_error()); /* one notch down */
aster_app_free(app);
}aster_app_key
int aster_app_key(const AsterApp *app, const char *chord);Presses and releases a key chord on the focused element or as an app-wide shortcut: "enter", "ctrl+s", "shift+tab", "a". Returns 0 or -1.
- Errors: an unrecognised chord fails (
unknown key chord "...");wrong-thread,wrong-time,bad-argument. Checked:enter,ctrl+s,shift+tab,a,escape,tab,space,up,ctrl+shift+z,Ctrl+S(case-insensitive) andcmd+swere accepted;f5andpage_downwere rejected. The full grammar is not in the header, so treat a-1as "chord not supported" rather than a bug in your call.
/* example: aster_app_key */
static void example_aster_app_key(void) {
AsterApp *app = aster_app_new(COUNTER);
aster_app_focus(app, "add");
if (aster_app_key(app, "enter") != 0) printf("%s\n", aster_last_error()); /* activates the focused button */
if (aster_app_key(app, "ctrl+nope") != 0) printf("expected: %s\n", aster_last_error());
aster_app_free(app);
}aster_app_focus
int aster_app_focus(const AsterApp *app, const char *id);Focuses the element whose id (its key or id in the view) is id. Returns 0 or -1.
- Errors: an id that does not exist fails;
wrong-thread,wrong-time,bad-argument.
/* example: aster_app_focus */
static void example_aster_app_focus(void) {
AsterApp *app = aster_app_new(COUNTER);
if (aster_app_focus(app, "name") != 0) printf("%s\n", aster_last_error());
aster_app_free(app);
}aster_app_resize
int aster_app_resize(const AsterApp *app, uint32_t width, uint32_t height, double scale);Re-renders at a new logical size and output scale, like a window resize or a display DPI change. width and height must be 64..16384 and scale 0.25..8, otherwise it fails and changes nothing. Returns 0 or -1.
- Errors: out of range (message: "resize wants 64..16384 logical px each and a scale of 0.25..8");
wrong-thread,wrong-time. - Note: the header says only "0.25..8" for scale; the 64..16384 limits come from the source.
/* example: aster_app_resize */
static void example_aster_app_resize(void) {
AsterApp *app = aster_app_new(COUNTER);
if (aster_app_resize(app, 400, 300, 1.5) != 0) printf("%s\n", aster_last_error());
if (aster_app_resize(app, 1, 1, 1.0) != 0) printf("expected: %s\n", aster_last_error());
aster_app_free(app);
}aster_app_pixels
int aster_app_pixels(const AsterApp *app, uint8_t *rgba, size_t capacity,
uint32_t *width, uint32_t *height);Reads the current frame back as straight (non-premultiplied) RGBA, 4 bytes per device pixel, rows top to bottom. width and height may be NULL. With rgba == NULL it only reports the size, so the usual pattern is two calls: ask for the size, allocate width * height * 4 bytes, then call again. If capacity < width * height * 4 it fails and copies nothing. Returns 0 or -1.
- Ownership: you own
rgba. The runtime writes into it during the call only and never keeps it. - Threading: UI thread only.
- Errors: a too-small buffer (message states the bytes needed),
wrong-thread,wrong-time. - Size: device pixels, so a 400 x 300 view at scale 1.5 is 600 x 450.
/* example: aster_app_pixels */
static void example_aster_app_pixels(void) {
AsterApp *app = aster_app_new(COUNTER);
uint32_t w = 0, h = 0;
if (aster_app_pixels(app, NULL, 0, &w, &h) != 0) { printf("%s\n", aster_last_error()); return; }
size_t n = (size_t)w * h * 4;
uint8_t *rgba = (uint8_t *)malloc(n);
if (rgba && aster_app_pixels(app, rgba, n, &w, &h) == 0)
printf("%ux%u, first pixel %02x%02x%02x%02x\n", w, h, rgba[0], rgba[1], rgba[2], rgba[3]);
free(rgba);
aster_app_free(app);
}Putting it together: a headless session
The whole loop an agent or a test uses: create, drive, look, free.
/* example: session */
static void on_session_event(void *user, const char *event_json) {
AsterApp *app = (AsterApp *)user;
if (strstr(event_json, "\"action\":\"add\"")) {
static int n = 0;
char state[64];
snprintf(state, sizeof state, "{\"count\":%d}", ++n);
aster_app_set_state(app, state); /* answer the click */
}
}
static void example_session(const char *png_path) {
AsterApp *app = aster_app_new(COUNTER);
aster_app_on_event(app, on_session_event, app);
aster_app_click(app, "Add one");
aster_app_click(app, "Add one");
char *st = aster_app_state(app);
printf("%s\n", st);
aster_free(st);
aster_app_shot(app, png_path);
aster_app_free(app);
}Linking
- Linux: link against
libaster_runtime.so(built as thecdylibof theaster-runtimecrate), for examplecc -I native/runtime/include prog.c -L <target>/debug -laster_runtime -Wl,-rpath,<target>/debug. This is the command the repo's owntests/smoke.cdocuments, and the one used to check this page. - Windows: the header marks functions
__declspec(dllimport), so you link the import libraryaster_runtime.dll.libthat is written next toaster_runtime.dlland ship the DLL next to your program. The DLL and its import library were cross-built from Linux; linking and running a C program on Windows was not run here. - Other languages: any language with a C FFI can call these 25 functions. The strings are plain UTF-8; there are no structs other than the opaque
AsterApp.
How this page was checked
Each /* example: ... */ block was extracted from this page's source by a script, compiled together with aster.h (cc -Wall -Wextra, clean) and run on Linux against libaster_runtime.so built from aster-ui main f19b91bcd with Rust 1.98.0 (2026-11-15). The window example (aster_app_run) was compiled but not run, because the build machine has no display. On Windows the runtime was cross-built, not run: its import library is aster_runtime.dll.lib and the DLL exports exactly the 25 functions of aster.h. Still unverified: linking and running a C program on Windows, and whether the error help links are live.