API reference

The public surface an app or driver codes against. Signatures are quoted from the headers (unoui/unoui.h, pc64/fb.h, pc64/uno_app.h, uno3d.h).

unoui: windows

void unoui_window_init(unoui_window *win, const char *title,
                       int x, int y, int w, int h);

void         unoui_ui_init (unoui_ui *, const unoui_theme *, int sw, int sh);
void         unoui_ui_theme(unoui_ui *, const unoui_theme *);   /* live re-skin */
void         unoui_ui_add  (unoui_ui *, unoui_window *);        /* topmost = focus */
void         unoui_bring_to_front(unoui_ui *, unoui_window *win);
unoui_action unoui_handle  (unoui_ui *, const unoui_event *);   /* feed one event */
void         unoui_render_ui(unoui_ui *);
void         unoui_fullscreen(unoui_ui *, unoui_window *win);   /* NULL = restore */
void         unoui_reflow_window(const unoui_theme *, unoui_window *);

/* window flags: UI_WIN_BARE UI_WIN_BOTTOM UI_WIN_TOP UI_WIN_RESIZE
   limits: UNOUI_MAX_WIDGETS = 64, UNOUI_MAX_WINDOWS = 8 */

unoui: widgets

Every constructor returns a unoui_widget *; set its ->id so you can recognise it in the returned unoui_action.

/* all return unoui_widget *; set ->id afterwards to identify it in actions */
unoui_widget *unoui_add_label   (unoui_window *, int x, int y, const char *text);
unoui_widget *unoui_add_button  (unoui_window *, int x, int y, int w, const char *text, int flags);
unoui_widget *unoui_add_check   (unoui_window *, int x, int y, const char *text, int on);
unoui_widget *unoui_add_radio   (unoui_window *, int x, int y, const char *text, int on);
unoui_widget *unoui_add_field   (unoui_window *, int x, int y, int w, const char *text, int focus);
unoui_widget *unoui_add_edit    (unoui_window *, int x, int y, int w, unoui_text *t);
unoui_widget *unoui_add_textarea(unoui_window *, int x, int y, int w, int h, unoui_text *t);
unoui_widget *unoui_add_progress(unoui_window *, int x, int y, int w, int v, int vmax);
unoui_widget *unoui_add_vscroll (unoui_window *, int x, int y, int h, int v, int vmax);
unoui_widget *unoui_add_hscroll (unoui_window *, int x, int y, int w, int v, int vmax);
unoui_widget *unoui_add_slider  (unoui_window *, int x, int y, int w, int vmin, int vmax, int v);
unoui_widget *unoui_add_spinner (unoui_window *, int x, int y, int w, int vmin, int vmax, int v);
unoui_widget *unoui_add_dropdown(unoui_window *, int x, int y, int w, const char **items, int n, int sel);
unoui_widget *unoui_add_tabs    (unoui_window *, int x, int y, int w, const char **items, int n, int sel);
unoui_widget *unoui_add_menubar (unoui_window *, const unoui_menu *menus, int n);
unoui_widget *unoui_add_list    (unoui_window *, int x, int y, int w, int h, const char **items, int n, int sel);
unoui_widget *unoui_add_group   (unoui_window *, int x, int y, int w, int h, const char *title);
unoui_widget *unoui_add_sep     (unoui_window *, int x, int y, int w);
unoui_widget *unoui_add_canvas  (unoui_window *, int x, int y, int w, int h, unoui_canvas *c);

/* widget state flags: UI_F_DEFAULT UI_F_PRESSED UI_F_FOCUS UI_F_DISABLED
                       UI_F_CHECKED UI_F_CARET UI_F_HOT */

unoui: editable text

Fields and text areas edit a buffer the app owns; the toolkit tracks caret and selection in place.

/* editable text: the APP owns the char buffer; the toolkit edits it in place */
typedef struct {
    char *buf; int cap; int len; int caret; int sel;
    int scroll_x; int scroll_y; int multiline;
} unoui_text;

void unoui_text_init(unoui_text *t, char *buf, int cap, int multiline);
void unoui_text_set (unoui_text *t, const char *s);

unoui: the event model

This is the portability contract. A platform adapter produces unoui_events; unoui_handle returns an unoui_action describing what changed.

typedef enum {
    UI_EV_NONE = 0,
    UI_EV_MOUSE_DOWN, UI_EV_MOUSE_UP, UI_EV_MOUSE_MOVE,
    UI_EV_KEY,    /* virtual key (UI_KEY_*)  */
    UI_EV_CHAR,   /* printable char (.ch)    */
    UI_EV_WHEEL,  /* scroll (.wheel notches) */
    UI_EV_TICK    /* frame tick, drives caret blink */
} ui_event_kind;

enum { UI_MOD_SHIFT = 1, UI_MOD_CTRL = 2, UI_MOD_ALT = 4 };

enum {  /* virtual keys, kept above ASCII so CHAR vs KEY split cleanly */
    UI_KEY_LEFT = 0x100, UI_KEY_RIGHT, UI_KEY_UP, UI_KEY_DOWN,
    UI_KEY_HOME, UI_KEY_END, UI_KEY_PGUP, UI_KEY_PGDN,
    UI_KEY_BACKSPACE, UI_KEY_DELETE, UI_KEY_ENTER, UI_KEY_TAB, UI_KEY_ESC
};

typedef struct {                 /* one input event */
    ui_event_kind kind;
    int x, y, button;            /* mouse position (screen) + button */
    int key;                     /* UI_KEY_* for UI_EV_KEY   */
    int ch;                      /* ASCII for UI_EV_CHAR     */
    int mods;                    /* UI_MOD_* bitmask         */
    int wheel;                   /* +down / -up              */
} unoui_event;

typedef struct {                 /* result of feeding one event */
    int changed;                 /* nonzero => id/kind/value are meaningful */
    int id;                      /* the widget's app id      */
    int kind;                    /* the widget's kind, or UI_ACT_CLOSE */
    int value;                   /* new value / selection / z-index    */
} unoui_action;

#define UI_ACT_CLOSE 9999        /* close box clicked; action.value = z-index */

unoui: theming

A theme is a semantic colour palette plus metrics plus an optional vtable of chrome painters; a NULL painter falls back to the portable default, so the same widgets render on 1-bit through 32-bit targets. Ten themes ship: theme_aurora_light, theme_aurora_dark, theme_unodos, theme_macos7, theme_macplus, theme_win31, theme_amiga, theme_c64, theme_apple2, theme_next. Switch live with unoui_ui_theme(&ui, &theme_c64).

Framebuffer (fb)

The software drawing surface underneath the toolkit; canvas apps draw with it directly.

typedef uint32_t fb_px;

void fb_clear(fb_px c);
void fb_fill_rect(int x,int y,int w,int h,fb_px c);
void fb_frame_rect(int x,int y,int w,int h,fb_px c);
void fb_pixel(int x,int y,fb_px c);
void fb_hline(int x,int y,int w,fb_px c);
void fb_vline(int x,int y,int h,fb_px c);
void fb_invert_rect(int x,int y,int w,int h);
void fb_set_clip(int x,int y,int w,int h);   /* confine drawing */
void fb_reset_clip(void);
void fb_blend_pixel(int x,int y,fb_px c,int a);          /* alpha 0..255 */
void fb_blend_rect(int x,int y,int w,int h,fb_px c,int a);
void fb_grad_v(int x,int y,int w,int h,fb_px top,fb_px bot);
void fb_round_rect(int x,int y,int w,int h,int rad,fb_px c);
void fb_set_font(const fb_font *f);
int  fb_text(int x,int y,const char *s,fb_px fg,long bg);   /* bg = -1 => transparent */
int  fb_text_w(const char *s);
int  fb_text_h(void);                        /* line height of the active font */
void fb_get_clip(int *x,int *y,int *w,int *h);   /* save/restore the clip */
int  fb_big_text(int x,int y,const char *s,fb_px fg,long bg,int scale);

/* FB_RGB(r,g,b); named colors UNO_WHITE UNO_BLACK UNO_BLUE UNO_CYAN UNO_MAG
   corner masks FB_CORNER_TL/TR/BL/BR/ALL; externs fb[], uno_fb_w, uno_fb_h */

Platform subsystems

Names and roles (see the corresponding .c for exact prototypes):

3D (uno3d)

A small write-once 3D pipeline with a software rasteriser (Gouraud shading, no textures). Runner3D drives it directly.

typedef struct { float x, y, z; } u3d_vec3;
typedef struct { float x, y, z; unsigned char r, g, b; } u3d_vert;

void u3d_init(int w, int h);
void u3d_shutdown(void);
void u3d_begin(unsigned char r, unsigned char g, unsigned char b);  /* clear */
void u3d_perspective(float fov_deg, float aspect, float znear, float zfar);
void u3d_load_identity(void);
void u3d_translate(float x, float y, float z);
void u3d_scale(float x, float y, float z);
void u3d_rotate_x(float deg);
void u3d_rotate_y(float deg);
void u3d_rotate_z(float deg);
void u3d_triangles(const u3d_vert *verts, int tri_count);   /* Gouraud, no textures */
void u3d_end(void);
void u3d_present(void);

uno: the Python app module

The surface a Python app codes against. import uno, subclass uno.App, and reach the platform through the module and the Canvas passed to your build/draw. A machine-readable stub ships in SDK\uno.pyi.

import uno

uno.rgb(r, g, b)                 # pack a colour (0-255 each) -> int

# --- Canvas (passed to build() and draw(); coords are canvas-relative) ---
cv.width(); cv.height()          # your drawable size, in pixels
cv.clear(color)                  # fill the whole canvas
cv.fill_rect(x, y, w, h, color)  # filled / outline rectangle
cv.rect(x, y, w, h, color)
cv.pixel(x, y, color)
cv.hline(x, y, w, color); cv.vline(x, y, h, color)
cv.text(x, y, "string", color)

# --- Sound (the shared UnoSound voice) ---
uno.beep(midi, ticks)            # square-wave note, ticks ~= 1/60 s
uno.quiet()

# --- Files (vol defaults to 0, the boot volume) ---
uno.read(name) -> bytes                 # whole (small) file
uno.read_at(vol, name, off, n) -> bytes # stream a big file a slice at a time
uno.size(name) -> int                   # bytes, or -1 if missing
uno.write(name, data) -> bool           # to a writable volume
uno.mkdir(vol, name) -> bool            # create one directory (parent must exist)

# --- Devices: what hardware is on this machine (read-only) ---
uno.devices() -> str                    # the device tree, one line per PCI function:
                                        #   "bb:dd.f ven:dev cc/ss class driver|UNCLAIMED"
uno.pci() -> list                       # the same, parsed for filtering:
                                        #   [(loc, ven, dev, cls, subcls, progif, driver_or_None), ...]

This is the app-authoring module. The separate unoauto module below is the system-automation surface (probe, inject input, drive the machine), present in every build and gated by privilege. The full per-call contract is in the Python SDK reference.

unoauto: automation (Python, on the device)

import unoauto from any Python app to observe and drive the system - the automation half of unoautomate. The surface ships in every build; each call checks the caller's privilege, and a capability you don't hold makes the call return its inert value (False, [], None) rather than raise - so available() answers False on a machine that grants you nothing. In a debug OS everything is allowed.

UnoAutoLink: driving from your PC (Python)

From pc64/tools/unoauto_remote.py. Construct one, call listen(), and the device dials in (wait_connected()). Every command method blocks for the reply and raises on a device error or timeout.

The C contract underneath (unoauto_log, unoauto_probe, unoauto_sink_add, unoauto_test_run, the hook taps and unoauto_remote_*) is in pc64/unoauto.h; the wire protocol is in REMOTE.md.