C API reference

#define RAVEN_VERSION_MAJOR 0

#define RAVEN_VERSION_MINOR 1

#define RAVEN_VERSION_PATCH 0

#define RAVEN_API_VERSION "0.1"

#define R_FALSE 0

#define R_TRUE 1

#define R_INVALID_ID ((Rid)-1)

typedef enum RBackend

typedef enum RError

typedef enum RSeverity

typedef struct RInitDesc

Optional settings for Rinit_ex. A zero-initialized structure selects the default for every field, so new fields can be added without breaking code.

typedef struct RAllocator

Memory functions of the application, to replace the allocator of Raven. See Rset_allocator.

typedef struct RMemoryStats

What the library holds. See Rmemory_get_stats.

typedef struct RFrameStats

Timings and counters of the last frame produced for a window.

int Rinit(RBackend backend);

Starts the library with default settings on the given backend. The calling thread becomes the UI thread.

returns

R_TRUE on success. On failure, see Rerror_get_last.

int Rinit_ex(const RInitDesc* desc);

Starts the library with explicit settings.

desc

Settings, or NULL for the defaults.

void Rshutdown(void);

Destroys every window, widget and resource, stops the worker and render threads and releases the backend.

int Ris_initialized(void);

int Ris_free_edition(void);

@deprecated Raven no longer has editions: it is open source (Apache License 2.0) and never shows a watermark. Always R_FALSE.

const char* Rget_version(void);

returns

The library version, e.g. "0.1.0".

void Rset_allocator(const RAllocator* allocator);

Replaces the allocator of Raven with the functions of the application (an engine allocator, a tracker...). NULL selects the allocator of Raven again. Must be called before Rinit, and before any other function that allocates. The functions are called from several threads; alloc must return memory aligned for any type (16 bytes).

const RAllocator* Rallocator_get_system(void);

returns

An allocator that forwards to malloc, realloc and free of the C runtime: Rset_allocator(Rallocator_get_system()) is how memory tools that follow malloc (Valgrind, heap profilers) see the blocks of Raven. The environment variable RAVEN_ALLOCATOR=system does the same without recompiling, and it is the default in a build with AddressSanitizer.

void* Rmemory_alloc(size_t size);

Memory from the allocator of Raven (or from the one given to Rset_allocator), for the application: custom widgets, pixel buffers. Aligned on 16 bytes. Never returns NULL: running out of memory is a fatal error. Thread-safe.

void* Rmemory_realloc(void* ptr, size_t size);

Resizes a block, keeping its content. A NULL block is allocated. Thread-safe.

void Rmemory_free(void* ptr);

Frees a block. NULL is ignored. Thread-safe.

void Rmemory_get_stats(RMemoryStats* stats);

What the library holds right now. Thread-safe.

int Rmemory_check(void);

Walks the whole heap of Raven and verifies its structure.

returns

R_FALSE when it is corrupted (a buffer overrun wrote over a block header). Slow: for tests and for hunting a bug. Thread-safe.

void Rmemory_trim(void);

Returns to the OS the regions of the heap that hold nothing. Thread-safe.

int Rdraw_frame(void);

Produces one frame: processes the pending OS events without waiting, runs the posted tasks and the timers, then lays out, paints and submits every window that changed. A window in which nothing changed is not drawn again, so the call is cheap when the UI is idle.

returns

R_FALSE once Rquit was called or the last window is closed.

int Rwait_frame(double timeout_seconds);

Same as Rdraw_frame, but first sleeps until there is something to do: an OS event, a posted task, a timer, an animation, a pending redraw.

timeout_seconds

Longest sleep. Negative sleeps without limit, 0 does not sleep.

void Rquit(int exit_code);

Makes Rdraw_frame and Rwait_frame return R_FALSE. Thread-safe.

int Rget_exit_code(void);

returns

The code given to Rquit, 0 when the last window was closed.

int Ris_running(void);

returns

R_FALSE once Rquit was called or every window is closed.

void Rpoll_events(void);

Processes the pending OS events without producing a frame. Rdraw_frame does it already: only useful to keep the windows responsive during a long operation.

void Rwait_events(double timeout_seconds);

Sleeps until an OS event, a posted task, a timer or a pending redraw, and processes the OS events. Rwait_frame does it already.

timeout_seconds

Maximum wait. Negative waits without limit.

typedef void (*RFrameCallback)(double delta_seconds, void* user_data);

Registers a function called once per frame, before the layout. The body of your loop does the same job; the callback is also called while the OS keeps the thread in a loop of its own (on Windows, while the user moves or resizes a window), when your loop is not running.

void Rset_frame_callback(RFrameCallback callback, void* user_data);

double Rget_delta_time(void);

returns

Seconds between the last two frames.

double Rget_time(void);

returns

Seconds elapsed since Rinit, from a monotonic clock. Thread-safe.

void Rset_ui_scale(float scale);

Scale of the whole interface, on top of the one of the monitor (RInitDesc.ui_scale at start): every window is laid out again. 0.25 .. 4.

void Rset_vsync(int enabled);

R_TRUE: every frame waits for the vertical synchronization of the screen (no tearing, no wasted frames); R_FALSE: as fast as possible (RInitDesc.disable_vsync at start). Takes effect at the next frame.

int Rget_vsync(void);

float Rget_ui_scale(void);

void Rset_animations_enabled(int enabled);

R_FALSE makes every change immediate: for users who ask for reduced motion (Raccessibility_set_reduce_motion), and for tests that read the state right after an input.

int Rget_animations_enabled(void);

void Rset_animation_speed(float speed);

Multiplies the speed of every animation. 1 is the default, 0.25 a slow motion.

float Rget_animation_speed(void);

void Rset_animation_time_step(double seconds);

When positive, each frame advances the animations by exactly this many seconds instead of the time really elapsed: frames rendered one by one for a video or a screenshot, deterministic tests. 0 follows the clock.

typedef void (*RTaskCallback)(void* user_data);

typedef void (*RParallelRangeCallback)(Ruint begin, Ruint end, void* user_data);

void Rtask_post(RTaskCallback task, void* user_data);

Queues a function to run on the UI thread during the next frame and wakes Rwait_frame. Thread-safe: this is how worker threads touch the UI.

void Rtask_run_async(RTaskCallback task, void* user_data);

Runs a function on a worker thread of the job system. Thread-safe.

void Rparallel_for(Ruint count, Ruint grain, RParallelRangeCallback function, void* user_data);

Splits [0, count) into ranges of at most grain items and runs them on the worker threads and the calling thread. Returns when all are done.

void Rwake_up(void);

Wakes Rwait_frame and Rwait_events from any thread.

int Rget_worker_thread_count(void);

int Ris_ui_thread(void);

typedef void (*RTimerCallback)(Rid timer, void* user_data);

Rid Rtimer_create(double interval_seconds, int repeat, RTimerCallback callback, void* user_data);

Calls a function on the UI thread after interval_seconds.

repeat

R_TRUE to fire repeatedly, R_FALSE to fire once and delete itself.

void Rtimer_destroy(Rid timer);

int Rtimer_is_valid(Rid timer);

typedef void (*RActionCallback)(Rid sender, const char* action, void* user_data);

Actions connect widgets to application code by name. A widget carries an action name (set from XML with OnClicked="file.save", or from C with Rwidget_set_action); when its main event fires, the function bound to that name is called. Names are resolved when the event fires, so actions can be bound before or after the widgets are created.

void Raction_bind(const char* name, RActionCallback callback, void* user_data);

void Raction_unbind(const char* name);

void Raction_fire(const char* name, Rid sender);

Fires an action as a widget would: the function bound to the name is called, or the default handler. What a tool bar button, a script or a test uses to do what a menu item does.

sender

Passed to the function; R_INVALID_ID when there is none.

void Raction_set_default_handler(RActionCallback callback, void* user_data);

Receives every action that has no bound function (e.g. a script bridge).

int Ropen_url(const char* url);

Opens an address with the program the user has for it: a web page in the browser, a mailto: in the mail program, a file in its application. Returns at once.

returns

R_FALSE when the OS could not be asked (nothing tells whether a program then really opened it).

void Rclipboard_set_text(const char* text);

const char* Rclipboard_get_text(void);

returns

The clipboard text, or "" when empty. Valid until the next call.

RError Rerror_get_last(const char** detail, RSeverity* severity);

Retrieves and clears the last recorded error.

detail

Optional output: human-readable description.

severity

Optional output: severity of the error.

returns

R_NO_ERROR when nothing was recorded.

const char* Rerror_to_string(RError error);

const char* Rseverity_to_string(RSeverity severity);

typedef void (*RErrorCallback)(RError code, RSeverity severity, const char* detail);

Registers a function called whenever an error is raised. The function may be registered before Rinit. It is called on the thread that raised the error: errors of the renderer (and the messages of the Vulkan validation layers) come from the render thread.

void Rerror_set_callback(RErrorCallback callback);

void Rwindow_get_frame_stats(Rid window, RFrameStats* stats);

typedef enum RWindowFlags

typedef enum RBackdrop

What is seen behind a window created with R_WINDOW_TRANSPARENT.

Windows 11 every value Windows 10 TRANSPARENT, BLUR, ACRYLIC (MICA gives ACRYLIC) macOS TRANSPARENT; other backdrops fall back to transparency X11 TRANSPARENT with any compositing manager; BLUR where

                      the compositor blurs on request (KWin; picom and
                      others with their own settings); ACRYLIC and MICA
                      give BLUR

no compositor nothing: the window stays opaque

typedef enum RWindowSystem

typedef struct RNativeWindow

Native handles of a window or of a native viewport. Win32 : display = HINSTANCE, window = HWND X11 : display = Display*, window = Window (XID), visual = VisualID Cocoa : display = NSWindow*, window = CAMetalLayer* for Vulkan presentation

typedef enum RWindowEdge

Edges and corners of a window, for Rwindow_begin_resize.

typedef enum RMouseButton

typedef enum RModifier

typedef enum RCursor

typedef enum RKey

Keyboard keys. Printable keys use their upper-case ASCII code.

typedef enum REventType

typedef struct REvent

Input event delivered to a widget. Mouse and key events bubble from the target widget to its parents until one of them handles the event.

typedef enum RDropPhase

Moments of a drag coming from another application (files from the file manager, text...).

typedef struct RDropEvent

What a drop target receives. The files and the text are only known when the drop happens (R_DROP_DROPPED), and are valid during the callback.

typedef int (*RDropCallback)(Rid target, const RDropEvent* event, void* user_data);

Called for a drop target (a widget, or a window: target is its handle). Return R_TRUE to accept: while the pointer is over the target this shows the "can drop here" cursor and highlights the target; for R_DROP_DROPPED it tells the source that the data was taken.

Rid Rwindow_create(const char* title, int width, int height, Ruint flags);

Opens a top-level window.

width,height

Client size in logical units.

flags

Bitmask of RWindowFlags.

void Rwindow_destroy(Rid window);

Closes a window and deletes its content widgets.

int Rwindow_is_valid(Rid window);

void Rwindow_set_content(Rid window, Rid widget);

Sets the root widget of the window. The window takes ownership of the widget; the previous content is deleted.

Rid Rwindow_get_content(Rid window);

void Rwindow_set_title(Rid window, const char* title);

const char* Rwindow_get_title(Rid window);

void Rwindow_set_size(Rid window, int width, int height);

void Rwindow_get_size(Rid window, int* width, int* height);

void Rwindow_set_min_size(Rid window, int width, int height);

void Rwindow_set_position(Rid window, int x, int y);

void Rwindow_get_position(Rid window, int* x, int* y);

void Rwindow_get_framebuffer_size(Rid window, int* width, int* height);

Size of the drawable area in pixels.

float Rwindow_get_scale(Rid window);

returns

Pixels per logical unit (monitor scale x global UI scale).

void Rwindow_show(Rid window);

void Rwindow_hide(Rid window);

void Rwindow_maximize(Rid window);

void Rwindow_minimize(Rid window);

void Rwindow_restore(Rid window);

int Rwindow_is_maximized(Rid window);

int Rwindow_is_minimized(Rid window);

int Rwindow_is_active(Rid window);

returns

R_TRUE while the window is the one the user is working in.

void Rwindow_close(Rid window);

Asks to close the window, as the close button of its title bar does: the close callback is asked first and may refuse.

void Rwindow_begin_move(Rid window);

Custom headers. Call these from a mouse-down handler, while the left button is held: the window follows the pointer until the button is released (the widget does not receive the release). A R_WIDGET_HEADER_BAR and the widgets given to Rwidget_set_window_drag do it by themselves.

void Rwindow_begin_resize(Rid window, RWindowEdge edge);

void Rwindow_set_icon(Rid window, const uint8_t* rgba, int width, int height);

Icon of the window (title bar, task bar), from tightly packed RGBA8 pixels; NULL goes back to the default: on Windows the first icon of the executable, when it has one. Windows and X11.

void Rwindow_set_clear_color(Rid window, float r, float g, float b, float a);

void Rwindow_set_background(Rid window, Rid texture);

Image drawn behind the content, scaled to cover the window: what the glass of a glass theme looks through. R_INVALID_ID removes it.

int Rwindow_set_backdrop(Rid window, RBackdrop backdrop);

Chooses what shows behind a window created with R_WINDOW_TRANSPARENT (see RBackdrop). With anything but R_BACKDROP_NONE the window is not cleared with its color and the wallpaper of the theme is not drawn: only what the widgets draw hides the screen. In XML: <Window Backdrop="Blur">.

returns

R_TRUE when the window system does it; R_FALSE (the window then stays as it was) without R_WINDOW_TRANSPARENT, or when it cannot.

RBackdrop Rwindow_get_backdrop(Rid window);

int Rwindow_set_opacity(Rid window, float opacity);

Opacity of the whole window, its frame included, from 0 to 1: a window that fades, a tool that lets what is under it show.

returns

R_FALSE when the window system cannot do it.

float Rwindow_get_opacity(Rid window);

int Rwindow_set_topmost(Rid window, int topmost);

Keeps the window above the other windows (splash screens, tools).

returns

R_FALSE when the window system cannot do it.

void Rwindow_center(Rid window);

Centers the window on the work area of its monitor (no task bar).

void Rwindow_request_redraw(Rid window);

Asks for a new frame even if no widget changed. Thread-safe.

void Rwindow_set_continuous_redraw(Rid window, int enabled);

R_TRUE redraws the window every frame (games, live viewports).

typedef int (*RWindowCloseCallback)(Rid window, void* user_data);

Called when the user asks to close the window. Return R_TRUE to let the window close, R_FALSE to keep it open.

void Rwindow_set_close_callback(Rid window, RWindowCloseCallback callback, void* user_data);

typedef void (*RWindowResizeCallback)(Rid window, int width, int height, void* user_data);

Called after the window was resized. Sizes are in logical units.

void Rwindow_set_resize_callback(Rid window, RWindowResizeCallback callback, void* user_data);

void Rwindow_set_drop_callback(Rid window, RDropCallback callback, void* user_data);

Takes what is dropped on the window from other applications, where no widget takes it (Rwidget_set_drop_callback). NULL removes it.

void Rwindow_set_user_handle(Rid window, void* handle);

void* Rwindow_get_user_handle(Rid window);

int Rwindow_get_native_handle(Rid window, RNativeWindow* native);

Fills native with the OS handles of the window.

uint8_t* Rwindow_capture(Rid window, int* width, int* height);

Reads back the last rendered frame as tightly packed RGBA8 pixels. Blocks until the frame is rendered. Free the result with Rpixels_free. The alpha is 255, except for a window that is seen through (R_WINDOW_TRANSPARENT): its pixels are then premultiplied by their alpha, as the window system receives them.

returns

NULL when the backend cannot capture.

Rid Rwindow_get_focused_widget(Rid window);

Widget that has the keyboard focus in the window, or R_INVALID_ID.

Rid Rwindow_get_hovered_widget(Rid window);

Deepest widget under the cursor, or R_INVALID_ID.

void Rwindow_get_mouse_position(Rid window, float* x, float* y);

int Rwindow_get_watermark_rect(Rid window, float* x, float* y, float* width, float* height);

@deprecated Raven no longer shows a watermark. Always R_FALSE, with zeros.

void Rwindow_inject_mouse_move(Rid window, float x, float y);

Inject input as if it came from the OS. Positions are in logical units. Useful for automated tests, replays and when Raven is driven by a host application.

void Rwindow_inject_mouse_button(Rid window, RMouseButton button, int pressed);

void Rwindow_inject_mouse_wheel(Rid window, float wheel_x, float wheel_y);

void Rwindow_inject_key(Rid window, RKey key, int pressed, Ruint modifiers);

void Rwindow_inject_text(Rid window, const char* text);

int Rwindow_inject_drag(Rid window, float x, float y, int inside);

A drag from another application moves over the window (inside R_TRUE) or leaves it.

returns

R_TRUE when a drop at this position would be accepted.

int Rwindow_inject_drop(Rid window, float x, float y, const char*const* paths, int path_count, const char* text);

Drops files and / or text at a position. Returns R_TRUE when a target took them.

int Rwindow_is_key_down(Rid window, RKey key);

R_TRUE while the key is held down in the window (cleared when the window loses the keyboard).

int Rwindow_is_mouse_button_down(Rid window, RMouseButton button);

R_TRUE while the mouse button is held down over (or captured by) the window.

Ruint Rwindow_get_modifiers(Rid window);

Modifiers (RModifier) of the last input event.

int Rwindow_is_mouse_inside(Rid window);

R_TRUE while the pointer is over the client area.

int Rwindow_wants_text_input(Rid window);

R_TRUE when the keyboard focus is in a text input, spin box or text editor.

int Rwindow_has_popup(Rid window);

R_TRUE while a menu, list or dialog is open over the window.

void Rwindow_set_tab_navigation(Rid window, int enabled);

R_FALSE: Tab no longer moves the keyboard focus (the application uses it as a shortcut). Default R_TRUE.

typedef int (*RWindowEventHook)(Rid window, const REvent* event, void* user_data);

Sees every input event of the window (mouse, wheel, keys, text) before any widget, with target set to the widget under the pointer. Returning R_TRUE consumes the event: the widgets do not get it. The state read by Rwindow_is_key_down is updated either way.

void Rwindow_set_event_hook(Rid window, RWindowEventHook hook, void* user_data);

int Rdrag_begin(Rid source, const char* type, const char* data, const char* label);

Starts dragging data from source (call it while a mouse button is held, typically from a mouse-move event once the pointer has moved a few units). Until the button is released, the widgets with a drop callback (Rwidget_set_drop_callback) under the pointer receive R_DROP_ENTER / MOVE / LEAVE and, on release, R_DROP_DROPPED, with drag_type set and text = data. Returning R_FALSE from the callback refuses the drop there. Escape cancels. label follows the pointer.

returns

R_FALSE when the widget is not in a window.

int Rdrag_is_active(Rid window);

R_TRUE while a drag started by Rdrag_begin is in progress in the window.

const char* Rdrag_get_type(Rid window);

Type of the drag in progress, or NULL.

const char* Rdrag_get_data(Rid window);

Data of the drag in progress, or NULL.

void Rdrag_cancel(Rid window);

Ends the drag in progress without dropping (the target receives R_DROP_LEAVE).

void Rwindow_register_shortcut(Rid window, RKey key, Ruint modifiers, const char* action);

void Rwindow_unregister_shortcut(Rid window, RKey key, Ruint modifiers);

typedef enum RTheme

typedef enum RMaterial

What surfaces are made of, from the clearest to the most opaque. A theme has one material for everything (Rtheme_set_material); any widget can be given its own (Rwidget_set_material, Material="..." in XML).

The three glasses share the same anatomy (a tint over what is behind, a rim that bends it and catches the light, a shadow) and differ by how much they let through. Within one material, surfaces are also told apart by their height above the window: bars lie flat, panels float a little, controls a little more, menus and dialogs highest; each level has a brighter rim and a deeper shadow than the one below.

typedef enum RColorRole

Color roles. The comment lists the widgets reading each role.

typedef enum RMetric

Sizes, in logical units.

void Rtheme_apply(RTheme theme);

Switches to a built-in theme: replaces every theme color and metric. Colors and metrics changed with Rtheme_set_color and Rtheme_set_metric are lost; per-widget overrides are kept.

void Rtheme_set_color(RColorRole role, float r, float g, float b, float a);

void Rtheme_get_color(RColorRole role, float* r, float* g, float* b, float* a);

void Rtheme_set_metric(RMetric metric, float value);

float Rtheme_get_metric(RMetric metric);

void Rtheme_set_material(RMaterial material);

Material of every widget that was not given one with Rwidget_set_material. Rtheme_apply sets it: solid for the flat themes, frosted glass for the glass themes.

RMaterial Rtheme_get_material(void);

void Rtheme_set_font(Rid font);

Font used by widgets that have no font of their own.

Rid Rtheme_get_font(void);

void Rtheme_set_accent(float r, float g, float b);

Sets the accent color and everything that follows from it: its hovered and pressed shades, the focus outline, the selection, the links.

void Rtheme_set_dark(int dark);

Tells whether the theme is a dark one. It decides the tint of the glass, the colors of the code and which wallpaper the glass themes use. Rtheme_apply and the theme files set it.

int Rtheme_is_dark(void);

void Rtheme_set_wallpaper(Rid texture);

Image drawn behind the content of the windows that have no background of their own, or R_INVALID_ID for none (the window color).

Rid Rtheme_get_wallpaper(void);

void Rtheme_set_style_color(const char* widget, const char* style_class, RColorRole role, float r, float g, float b, float a);

Gives a color to the widgets of a type and / or of a class, instead of the color of the theme.

When several styles give the same value to a widget, the one with a type and a class wins over the one with a class, which wins over the one with a type; between equals, the last one set wins.

widget

Tag of a type of widget ("Button"), or NULL for every type.

style_class

A class (Rwidget_set_class, Class="..."), or NULL for the widgets of the type whatever their classes.

void Rtheme_set_style_metric(const char* widget, const char* style_class, RMetric metric, float value);

void Rtheme_set_style_material(const char* widget, const char* style_class, RMaterial material);

R_MATERIAL_DEFAULT removes the material of the style.

void Rtheme_clear_styles(void);

Removes every style of the theme. Rtheme_apply and Rtheme_use do it too.

const char* Rtheme_load(const char* path);

Reads a theme file and keeps the theme under its name (the Name attribute, else the name of the file). It does not change the theme in use unless a theme of that name is the one in use.

The file is watched like the interface files (Rxml_set_live_reload): saving it updates every widget that uses the theme.

returns

The name of the theme, valid until Rshutdown, or NULL after reporting an error.

const char* Rtheme_load_from_memory(const char* xml, size_t size);

Same, from a text. size may be 0 for a null-terminated text.

int Rtheme_use(const char* name);

Makes a named theme the theme of the application: "Dark", "Light", "GlassDark", "GlassLight", or a theme given by Rtheme_load. Values changed with Rtheme_set_... are lost.

returns

R_FALSE, after reporting an error, when no theme has that name.

const char* Rtheme_get_name(void);

Name of the theme in use ("Dark" at start).

int Rtheme_get_count(void);

Number of named themes, the four built-in ones included.

const char* Rtheme_get_name_at(int index);

Name of the index-th one, or NULL.

int Rtheme_save(const char* path, const char* name);

Writes the theme in use, with every change made since it was applied, as a theme file.

name

Name given to the theme in the file; NULL keeps the current one.

typedef enum RFontStyle

The styles of a font (Rfont_get_variant).

typedef enum RFilterType

Rid Rfont_create(const char* data, size_t data_size);

Creates a font from the content of a .ttf / .otf file. The buffer is copied. Glyphs are rasterized on demand, at the exact pixel size needed by each window scale, into a shared atlas.

returns

R_INVALID_ID on failure.

Rid Rfont_create_from_file(const char* path);

void Rfont_destroy(Rid font);

int Rfont_is_valid(Rid font);

Rid Rfont_get_default(void);

returns

The font embedded in the library (Roboto, Latin and Latin Extended-A).

Rid Rfont_get_monospace(void);

returns

The fixed-width font embedded in the library (Roboto Mono, same characters), used by default by the text editors. In XML: Font="monospace".

void Rfont_set_fallback(Rid font, Rid fallback);

Font used for the characters missing from font (symbols, icons, other scripts). Fallbacks can be chained.

void Rfont_set_variant(Rid font, RFontStyle style, Rid variant);

Gives a font the font to use for one of its styles: the bold file of the same family, its italic file. Formatted text (Markdown labels, the Markdown of the text editor) uses them.

A font that was given none still has the three styles: Raven draws its glyphs thicker for bold and slanted for italic, keeping their advances, so that text does not move when its style changes.

variant

R_INVALID_ID goes back to the style Raven derives.

Rid Rfont_get_variant(Rid font, RFontStyle style);

returns

The font drawn for a style of font: the one given with Rfont_set_variant, else the one Raven derives from it (made on first use; it lives as long as font and cannot be deleted by itself). Usable wherever a font is: Rlabel_set_font, Rdraw_text...

void Rfont_measure_text(Rid font, float size, const char* text, float* width, float* height);

Measures a UTF-8 string, in logical units, at scale 1.

font

R_INVALID_ID uses the theme font.

size

Font size; 0 uses R_METRIC_FONT_SIZE.

Rid Rtexture_create(const char* data, size_t data_size);

Creates a texture from the content of an image file (PNG, JPEG, BMP, TGA, GIF, PSD). Decoding happens on the calling thread.

returns

R_INVALID_ID on failure.

Rid Rtexture_create_async(const char* data, size_t data_size);

Same as Rtexture_create, decoded on a worker thread. The handle is usable at once; widgets showing it draw nothing until it is ready. The buffer is copied.

Rid Rtexture_create_from_file(const char* path);

Rid Rtexture_create_from_file_async(const char* path);

Reads and decodes the file on a worker thread.

Rid Rtexture_create_from_pixels(const uint8_t* rgba, int width, int height);

Creates a texture from tightly packed RGBA8 pixels (straight alpha).

void Rtexture_update(Rid texture, const uint8_t* rgba, int width, int height);

Replaces the pixels of a texture. The size may change. Use it to show frames produced on the CPU or read back from another renderer.

uint8_t* Rimage_decode(const void* data, size_t data_size, int* width, int* height);

Decodes an image file held in memory (PNG, JPEG, BMP, TGA) into tightly packed RGBA8 pixels, without making a texture: for pictures that arrive one after the other and go to Rtexture_update. Thread-safe, so that the decoding can be done away from the UI thread.

returns

The pixels, to release with Rpixels_free; NULL when the data is not an image Raven can read.

void Rpixels_free(uint8_t* pixels);

Releases pixels returned by Raven (Rimage_decode, Rwindow_capture). Thread-safe.

int Rtexture_is_ready(Rid texture);

returns

R_TRUE once an asynchronous texture is decoded (or failed).

void Rtexture_wait(Rid texture);

Blocks until an asynchronous texture is ready.

void Rtexture_destroy(Rid texture);

int Rtexture_is_valid(Rid texture);

void Rtexture_get_size(Rid texture, int* width, int* height);

void Rtexture_set_filter(Rid texture, RFilterType filter);

typedef enum RWidgetType

typedef enum RHAlign

typedef enum RVAlign

typedef enum RVisibility

typedef enum RTransition

How a widget arrives. A transition animates what the widget and its children draw; the layout is not affected, the widget is in place from the first frame for its neighbours and for the mouse.

typedef enum ROrientation

Rid Rwidget_create(RWidgetType type);

Creates a widget. It is not shown until it is added to a parent that belongs to a window (Rwidget_add_child, Rwindow_set_content).

void Rwidget_destroy(Rid widget);

Deletes a widget and all its descendants.

int Rwidget_is_valid(Rid widget);

RWidgetType Rwidget_get_type(Rid widget);

Rid Rwidget_add_child(Rid parent, Rid child);

Appends a child to a panel. The parent takes ownership. A widget that already has a parent is moved.

returns

child, so calls can be nested: Rid ok = Rwidget_add_child(row, Rbutton_create("OK"));

Rid Rwidget_insert_child(Rid parent, Rid child, int index);

void Rwidget_remove_child(Rid parent, Rid child);

Detaches a child without deleting it. The caller owns it again.

void Rwidget_clear_children(Rid parent);

Deletes every child of a panel.

Rid Rwidget_get_parent(Rid widget);

int Rwidget_get_child_count(Rid widget);

Rid Rwidget_get_child(Rid widget, int index);

Rid Rwidget_get_window(Rid widget);

returns

The window showing the widget, or R_INVALID_ID.

void Rwidget_set_name(Rid widget, const char* name);

const char* Rwidget_get_name(Rid widget);

Rid Rwidget_find(Rid scope, const char* name);

Finds a widget by name.

scope

A window or a widget; the search covers its whole subtree.

returns

R_INVALID_ID when no widget has that name.

void Rslot_set_padding(Rid child, float left, float top, float right, float bottom);

Space kept around the child, inside its slot. All panels.

void Rslot_set_halign(Rid child, RHAlign align);

Alignment of the child inside its slot. Default: fill. All panels.

void Rslot_set_valign(Rid child, RVAlign align);

void Rslot_set_auto(Rid child);

The slot takes the desired size of the child along the panel direction (Slate AutoWidth / AutoHeight). This is the default. VBox, HBox.

void Rslot_set_fill(Rid child, float coefficient);

The slot shares the space left by the auto slots, in proportion to coefficient (Slate FillWidth / FillHeight). VBox, HBox. In a Splitter, the coefficient is the relative size of the pane.

void Rslot_set_max_size(Rid child, float max_size);

Upper bound of the slot along the panel direction. 0 = none. VBox, HBox.

void Rslot_set_grid(Rid child, int column, int row);

Cell of the child. Grid, UniformGrid.

void Rslot_set_grid_span(Rid child, int column_span, int row_span);

void Rslot_set_anchors(Rid child, float min_x, float min_y, float max_x, float max_y);

Canvas placement. Anchors are fractions of the canvas size (0..1). - anchors equal on an axis: the child is at anchor + position, with

    the slot size (or its desired size when the slot size is <= 0);

- anchors different on an axis: the child stretches between them,

    position and size are then the near and far margins.

Alignment is the pivot of the child (0,0 = top-left, 0.5,0.5 = center).

void Rslot_set_position(Rid child, float x, float y);

void Rslot_set_size(Rid child, float width, float height);

void Rslot_set_alignment(Rid child, float x, float y);

void Rslot_set_title(Rid child, const char* title);

Title of the tab showing the child. TabView.

void Rwidget_set_visibility(Rid widget, RVisibility visibility);

RVisibility Rwidget_get_visibility(Rid widget);

void Rwidget_set_enabled(Rid widget, int enabled);

A disabled widget ignores input and is drawn dimmed, with its descendants.

int Rwidget_is_enabled(Rid widget);

void Rwidget_set_hit_testable(Rid widget, int hit_testable);

R_FALSE lets mouse events pass through the widget (not its children).

void Rwidget_set_opacity(Rid widget, float opacity);

Opacity multiplier applied to the widget and its descendants (0..1).

void Rwidget_set_transition(Rid widget, RTransition transition, float delay_seconds);

Gives the widget a transition that plays each time it appears: when its window is first drawn, when it is added to a window that is shown, and when it becomes visible again (Rwidget_set_visibility, a tab or a switcher showing it). In XML: Appear="FlyUp" AppearDelay="0.1".

delay_seconds

Time before it starts. Give growing delays to the items of a group to make them arrive one after the other.

void Rwidget_play_transition(Rid widget, RTransition transition, float delay_seconds);

Plays a transition once, now, whatever the widget was given with Rwidget_set_transition.

void Rwidget_set_clipping(Rid widget, int clip);

R_TRUE clips the descendants to the bounds of the widget.

void Rwidget_set_tooltip(Rid widget, const char* text);

Text shown when the cursor rests on the widget. NULL removes it.

const char* Rwidget_get_tooltip(Rid widget);

returns

The tooltip text of the widget, "" when it has none.

void Rwidget_set_cursor(Rid widget, RCursor cursor);

void Rwidget_set_size(Rid widget, float width, float height);

Size constraints, in logical units. They apply to the desired size the widget reports to its parent. A negative value removes the constraint on that axis.

void Rwidget_set_min_size(Rid widget, float width, float height);

void Rwidget_set_max_size(Rid widget, float width, float height);

void Rwidget_get_rect(Rid widget, float* x, float* y, float* width, float* height);

Bounds of the widget in its window, in logical units, after the last layout.

void Rwidget_get_desired_size(Rid widget, float* width, float* height);

int Rwidget_is_hovered(Rid widget);

void Rwidget_set_focusable(Rid widget, int focusable);

void Rwidget_focus(Rid widget);

Gives the keyboard focus to the widget.

int Rwidget_is_focused(Rid widget);

void Rwidget_set_user_handle(Rid widget, void* handle);

void* Rwidget_get_user_handle(Rid widget);

typedef void (*RWidgetDestroyCallback)(Rid widget, void* user_data);

Called once when the widget is gone: deleted by the application, with its parent or its window, or by Rshutdown. The place to release what belonged to it (a texture, a connection). The handle it receives names nothing any more: it is only there to tell widgets apart. Called on the UI thread, shortly after the deletion.

void Rwidget_set_destroy_callback(Rid widget, RWidgetDestroyCallback callback, void* user_data);

typedef int (*RWidgetEventCallback)(Rid widget, const REvent* event, void* user_data);

Receives the input events of a widget before the widget itself. Return R_TRUE to consume the event (the widget and its parents will not see it), R_FALSE to let it continue.

void Rwidget_set_event_callback(Rid widget, RWidgetEventCallback callback, void* user_data);

void Rwidget_set_action(Rid widget, const char* action);

Name of the action fired by the main event of the widget: button click, value change, text commit, item activation (see Raction_bind).

const char* Rwidget_get_action(Rid widget);

void Rwidget_set_drop_callback(Rid widget, RDropCallback callback, void* user_data);

Makes the widget a target for what is dragged from other applications: files from the file manager, text. It is highlighted while a drop on it would be accepted. NULL removes the callback.

void Rwidget_set_window_drag(Rid widget, int enabled);

In a window created with R_WINDOW_CUSTOM_HEADER: dragging the widget moves the window and a double click maximizes it, as a title bar does. The buttons, fields and other controls inside it keep working. In XML: WindowDrag="true".

Rid Rwidget_hit_test(Rid root, float x, float y);

Deepest widget of a subtree under a point of its window, or R_INVALID_ID.

Rid Rwidget_pick(Rid root, float x, float y);

Deepest visible widget of a subtree under a point of its window, whether it reacts to the pointer or not: a label, a panel, a disabled button. What a design tool selects with a click.

void Rwidget_set_context_menu(Rid widget, Rid menu);

Menu opened by a right click on the widget. The widget does not own it.

void Rwidget_invalidate(Rid widget);

Asks for the widget to be laid out and painted again.

void Rwidget_set_color(Rid widget, RColorRole role, float r, float g, float b, float a);

Overrides a theme color for one widget. R_COLOR_TEXT is also inherited by its descendants.

void Rwidget_clear_color(Rid widget, RColorRole role);

void Rwidget_get_color(Rid widget, RColorRole role, float* r, float* g, float* b, float* a);

The color the widget is drawn with for a role: its own, else the one of the styles of its theme that apply to it, else the one of its theme. What a custom widget should draw itself with.

void Rwidget_set_material(Rid widget, RMaterial material);

Gives one widget a material of its own, whatever the theme: a solid button in a glass window, a panel of clear glass in a flat one. A widget that draws no surface (a box, a label) gets one of this material behind it: any widget can become a panel of glass. In XML: Material="Glass | FrostedGlass | TintedGlass | Solid".

material

R_MATERIAL_DEFAULT follows the theme again.

RMaterial Rwidget_get_material(Rid widget);

returns

The material the widget is drawn with: its own, or the one of the theme.

void Rwidget_set_metric(Rid widget, RMetric metric, float value);

Overrides a theme metric for one widget.

void Rwidget_clear_metric(Rid widget, RMetric metric);

float Rwidget_get_metric(Rid widget, RMetric metric);

returns

The metric the widget uses: its own, else the one of a style, else the one of its theme.

void Rwidget_set_class(Rid widget, const char* classes);

Classes of the widget, separated by spaces ("danger large"): the styles of the theme made for these classes apply to it (Rtheme_set_style_color, <Style Class="danger" .../> in a theme file). In XML: Class="...". NULL or "" removes them.

const char* Rwidget_get_class(Rid widget);

returns

The classes, "" when it has none. Valid until they change.

void Rwidget_add_class(Rid widget, const char* style_class);

void Rwidget_remove_class(Rid widget, const char* style_class);

int Rwidget_has_class(Rid widget, const char* style_class);

int Rwidget_set_theme(Rid widget, const char* name);

Gives the widget and everything inside it a theme of their own, by name ("Dark", "GlassLight", or a theme of Rtheme_load): a dark side bar in a light window, a preview of another theme. Menus and lists opened from inside follow. In XML: Theme="...".

name

NULL or "" follows the parent (the application theme) again.

returns

R_FALSE, after reporting an error, when no theme has that name.

const char* Rwidget_get_theme(Rid widget);

returns

Name of the theme the widget is drawn with.

typedef enum RBlurStyle

The looks of a R_WIDGET_BACKGROUND_BLUR. The first three are drawn by Raven from what the window shows behind the widget; the last one is the blur of the OS, which sees what is behind the window itself.

void Rpanel_set_spacing(Rid panel, float spacing);

Gap inserted between neighbouring children.

float Rpanel_get_spacing(Rid panel);

void Rgrid_set_column_fill(Rid grid, int column, float coefficient);

Lets a column / row grow to take a share of the free space (Slate FillColumn / FillRow). 0 sizes it to its content (default).

void Rgrid_set_row_fill(Rid grid, int row, float coefficient);

void Runiform_grid_set_columns(Rid grid, int columns);

Places children automatically, left to right then top to bottom, in the given number of columns. 0 uses the grid cell of each slot (default).

void Runiform_grid_set_min_cell_size(Rid grid, float width, float height);

void Rborder_set_padding(Rid border, float left, float top, float right, float bottom);

Space between the outline and the child.

void Rborder_set_background(Rid border, float r, float g, float b, float a);

Background color (R_COLOR_PANEL of this widget). Alpha 0 draws no background.

void Rborder_set_outline(Rid border, float width, float r, float g, float b, float a);

Outline width and color. Width 0 draws no outline (default).

void Rborder_set_corner_radius(Rid border, float top_left, float top_right, float bottom_right, float bottom_left);

void Rborder_set_shadow(Rid border, float blur, float offset_x, float offset_y);

Soft drop shadow behind the border. Blur 0 disables it (default).

void Rborder_set_material(Rid border, RMaterial material);

What the border is made of. R_MATERIAL_GLASS turns it into a panel of glass tinted by its background color (the alpha of the color is the strength of the tint): floating tool bars, side bars, cards.

void Rsize_box_set_aspect_ratio(Rid size_box, float ratio);

Keeps the child at a fixed width / height ratio, as large as fits. 0 disables it (default). The fixed, minimum and maximum sizes are set with Rwidget_set_size, Rwidget_set_min_size and Rwidget_set_max_size.

void Rspacer_set_size(Rid spacer, float width, float height);

void Rscroll_box_set_orientation(Rid scroll_box, ROrientation orientation);

Direction in which children are stacked and scrolled. Default: R_VERTICAL.

void Rscroll_box_set_scroll_both(Rid scroll_box, int enabled);

R_TRUE also scrolls across the stacking direction when the content is too large.

void Rscroll_box_set_offset(Rid scroll_box, float x, float y);

void Rscroll_box_get_offset(Rid scroll_box, float* x, float* y);

void Rscroll_box_scroll_to_end(Rid scroll_box);

void Rwidget_scroll_into_view(Rid widget);

Scrolls every ScrollBox above the widget so that the widget is visible.

void Rsplitter_set_orientation(Rid splitter, ROrientation orientation);

R_HORIZONTAL puts the panes side by side (default), R_VERTICAL stacks them.

void Rsplitter_set_min_pane_size(Rid splitter, float size);

Rid Rbackground_blur_create(void);

Creates a panel that shows what is behind it out of focus, with one child over it. In XML:

<BackgroundBlur Style="Frosted" Radius="24" CornerRadius="18" Padding="16">

      <Label>Over a blurred view of the window</Label>

</BackgroundBlur>

It works in any theme and with any material: it is not the glass of the glass themes (which bends and reflects), but the looks of RBlurStyle. Unlike the opacity of a widget, it does not let what is behind show sharp.

void Rbackground_blur_set_style(Rid blur, RBlurStyle style);

RBlurStyle Rbackground_blur_get_style(Rid blur);

void Rbackground_blur_set_radius(Rid blur, float radius);

How far what is behind goes out of focus, in logical units: 4 softens, 20 hides the details, 60 leaves only colors. A negative value (the default) uses R_METRIC_BLUR_RADIUS of the theme.

float Rbackground_blur_get_radius(Rid blur);

void Rbackground_blur_set_tint(Rid blur, float r, float g, float b, float a);

Color laid over the blur; its alpha is how much of it. Without one, R_BLUR_PLAIN has none and the other styles take theirs from the theme (R_COLOR_PANEL).

void Rbackground_blur_clear_tint(Rid blur);

Removes the tint given with Rbackground_blur_set_tint.

void Rbackground_blur_set_saturation(Rid blur, float saturation);

Saturation of what is seen through: 1 = as it is, 0 = gray, 1.5 = vivid. Negative = the one of the style.

void Rbackground_blur_set_grain(Rid blur, float grain);

Fine grain over the blur, 0 = none .. 1. Negative = the one of the style.

void Rbackground_blur_set_corner_radius(Rid blur, float top_left, float top_right, float bottom_right, float bottom_left);

void Rbackground_blur_set_padding(Rid blur, float left, float top, float right, float bottom);

Space between the edge and the child.

void Rbackground_blur_set_shadow(Rid blur, float shadow_blur);

Soft shadow under the panel; blur 0 = none (default).

void Rswitcher_set_index(Rid switcher, int index);

int Rswitcher_get_index(Rid switcher);

int Rtab_view_add_tab(Rid tab_view, const char* title, Rid content);

Adds a page. Same as Rwidget_add_child followed by Rslot_set_title.

returns

The index of the new tab, or -1.

void Rtab_view_set_active(Rid tab_view, int index);

int Rtab_view_get_active(Rid tab_view);

typedef void (*RTabChangedCallback)(Rid tab_view, int index, void* user_data);

void Rtab_view_set_changed_callback(Rid tab_view, RTabChangedCallback callback, void* user_data);

void Rtab_view_set_documents(Rid tab_view, int documents);

Documents mode: the major tabs of an application (the level, then one tab per open asset, as in Unreal): tabs on the left with an icon and a close button (a middle click closes too), shrinking when they do not fit, no slide between pages. XML: Documents="true".

int Rtab_view_get_tab_count(Rid tab_view);

Rid Rtab_view_get_tab(Rid tab_view, int index);

The page of a tab, R_INVALID_ID if none.

int Rtab_view_find_tab(Rid tab_view, Rid content);

Index of the tab of a page, -1 if none.

void Rtab_view_set_tab_title(Rid tab_view, Rid content, const char* title);

void Rtab_view_set_tab_icon(Rid tab_view, Rid content, Rid texture, float u0, float v0, float u1, float v1, int tint);

Icon before the title (documents). R_INVALID_ID removes it; tint: a mask in the text color.

void Rtab_view_set_tab_closable(Rid tab_view, Rid content, int closable);

R_FALSE: no close button (documents ; the level tab). Tabs can be closed by default.

void Rtab_view_show_tab(Rid tab_view, Rid content);

Shows the tab of a page (the changed callback is called).

typedef int (*RTabCloseCallback)(Rid tab_view, int index, Rid content, void* user_data);

The user closes a tab (its button, a middle click). Return R_TRUE to delete its page now, R_FALSE to keep it (the application may ask to save, then delete the page itself with Rwidget_destroy).

void Rtab_view_set_close_callback(Rid tab_view, RTabCloseCallback callback, void* user_data);

void Rexpander_set_title(Rid expander, const char* title);

const char* Rexpander_get_title(Rid expander);

void Rexpander_set_expanded(Rid expander, int expanded);

int Rexpander_is_expanded(Rid expander);

typedef void (*RExpanderChangedCallback)(Rid expander, int expanded, void* user_data);

void Rexpander_set_changed_callback(Rid expander, RExpanderChangedCallback callback, void* user_data);

typedef enum RDirection

void Rset_layout_direction(RDirection direction);

Direction of every window: R_DIRECTION_AUTO (the default), _LTR or _RTL.

RDirection Rget_layout_direction(void);

The direction the windows use now: R_DIRECTION_LTR or _RTL.

void Rwidget_set_direction(Rid widget, RDirection direction);

Direction of a part of a window: R_DIRECTION_INHERIT, _LTR or _RTL.

RDirection Rwidget_get_direction(Rid widget);

The direction the widget is laid out in: R_DIRECTION_LTR or _RTL.

typedef enum RTextAlign

typedef enum RButtonStyle

typedef enum RCheckboxStyle

typedef enum RStretch

Rid Rlabel_create(const char* text);

Shortcut for Rwidget_create(R_WIDGET_LABEL) + Rlabel_set_text.

void Rlabel_set_text(Rid label, const char* text);

Sets the text. '\n' starts a new line.

const char* Rlabel_get_text(Rid label);

void Rlabel_set_font(Rid label, Rid font);

R_INVALID_ID uses the theme font.

void Rlabel_set_text_size(Rid label, float size);

Font size in logical units. 0 uses R_METRIC_FONT_SIZE.

void Rlabel_set_text_align(Rid label, RTextAlign align);

void Rlabel_set_wrap(Rid label, int wrap);

R_TRUE wraps the text on the width given by the parent.

void Rlabel_set_color(Rid label, float r, float g, float b, float a);

Text color (R_COLOR_TEXT of this widget).

void Rlabel_set_markdown(Rid label, int enabled);

R_TRUE reads the text as Markdown and shows it formatted (Markdown="true" in XML):

# titles, **strong**, *emphasis*, code, ~~struck~~, [links](url), lists and lists in lists, - [x] task lists, > quotes, --- rules, | tables |, images alone on their line, and `` blocks of code with the colors of their language (`c, ``python...: the languages of the text editor, raven_text_editor.h).

The text wraps on the width of the label unless Rlabel_set_wrap said otherwise; put the label in a scroll box for a long document. Strong and emphasized text use the bold and italic of the font (Rfont_set_variant), which Raven derives from the font itself when it was given none. The colors come from the theme: R_COLOR_LINK, R_COLOR_CODE, R_COLOR_SEPARATOR, R_COLOR_ACCENT.

int Rlabel_get_markdown(Rid label);

typedef void (*RLabelLinkCallback)(Rid label, const char* url, void* user_data);

Called when the user clicks a link of a Markdown label.

Without a callback, a link written [Save](action:file.save) fires the action "file.save" (Raction_bind), and http, https and mailto links open in the browser or the mail program of the user (Ropen_url).

void Rlabel_set_link_callback(Rid label, RLabelLinkCallback callback, void* user_data);

const char* Rlabel_get_plain_text(Rid label);

The text of a Markdown label without its marks, as a reader sees it. Valid until the next call.

Rid Rbutton_create(const char* text);

Shortcut for Rwidget_create(R_WIDGET_BUTTON) + Rbutton_set_text.

void Rbutton_set_text(Rid button, const char* text);

Sets the content of the button to a label. A button can instead hold any single child widget (Rwidget_add_child), e.g. an HBox with an icon.

void Rbutton_set_style(Rid button, RButtonStyle style);

typedef void (*RButtonClickedCallback)(Rid button, void* user_data);

void Rbutton_set_clicked_callback(Rid button, RButtonClickedCallback callback, void* user_data);

Rid Rcheckbox_create(const char* text);

void Rcheckbox_set_text(Rid checkbox, const char* text);

const char* Rcheckbox_get_text(Rid checkbox);

void Rcheckbox_set_checked(Rid checkbox, int checked);

int Rcheckbox_is_checked(Rid checkbox);

void Rcheckbox_set_style(Rid checkbox, RCheckboxStyle style);

typedef void (*RCheckboxChangedCallback)(Rid checkbox, int checked, void* user_data);

void Rcheckbox_set_changed_callback(Rid checkbox, RCheckboxChangedCallback callback, void* user_data);

void Rslider_set_range(Rid slider, float minimum, float maximum);

void Rslider_set_value(Rid slider, float value);

float Rslider_get_value(Rid slider);

void Rslider_get_range(Rid slider, float* minimum, float* maximum, float* step);

The range given with Rslider_set_range and the step (NULL for what is not wanted).

void Rslider_set_step(Rid slider, float step);

Snaps the value to multiples of step. 0 = continuous (default).

void Rslider_set_orientation(Rid slider, ROrientation orientation);

typedef void (*RSliderChangedCallback)(Rid slider, float value, void* user_data);

void Rslider_set_changed_callback(Rid slider, RSliderChangedCallback callback, void* user_data);

void Rprogress_bar_set_value(Rid progress_bar, float value);

Progress between 0 and 1.

float Rprogress_bar_get_value(Rid progress_bar);

void Rimage_set_texture(Rid image, Rid texture);

void Rimage_set_tint_color(Rid image, float r, float g, float b, float a);

void Rimage_set_tint_text(Rid image, int enabled);

R_TRUE: the image is tinted with the text color around it (white icons that follow the theme). XML: TintText.

void Rimage_set_stretch(Rid image, RStretch stretch);

void Rimage_set_region(Rid image, float min_u, float min_v, float max_u, float max_v);

Part of the texture to show, in UV coordinates. Default: 0, 0, 1, 1.

void Rimage_set_corner_radius(Rid image, float radius);

void Rtext_input_set_text(Rid text_input, const char* text);

const char* Rtext_input_get_text(Rid text_input);

void Rtext_input_set_placeholder(Rid text_input, const char* text);

Dimmed text shown while the input is empty.

void Rtext_input_set_password(Rid text_input, int password);

int Rtext_input_is_password(Rid text_input);

int Rtext_input_is_read_only(Rid text_input);

void Rtext_input_set_read_only(Rid text_input, int read_only);

void Rtext_input_set_max_length(Rid text_input, int max_length);

Maximum number of characters. 0 = no limit (default).

void Rtext_input_select_all(Rid text_input);

typedef void (*RTextChangedCallback)(Rid text_input, const char* text, void* user_data);

void Rtext_input_set_changed_callback(Rid text_input, RTextChangedCallback callback, void* user_data);

Called on every edit.

void Rtext_input_set_committed_callback(Rid text_input, RTextChangedCallback callback, void* user_data);

Called when Enter is pressed. This also fires the action of the widget.

void Rspin_box_set_range(Rid spin_box, double minimum, double maximum);

void Rspin_box_set_value(Rid spin_box, double value);

double Rspin_box_get_value(Rid spin_box);

void Rspin_box_get_range(Rid spin_box, double* minimum, double* maximum, double* step);

The range and the step (NULL for what is not wanted).

void Rspin_box_set_step(Rid spin_box, double step);

void Rspin_box_set_decimals(Rid spin_box, int decimals);

Digits shown after the decimal point. Default: 2.

typedef void (*RSpinBoxChangedCallback)(Rid spin_box, double value, void* user_data);

void Rspin_box_set_changed_callback(Rid spin_box, RSpinBoxChangedCallback callback, void* user_data);

int Rcombo_box_add_item(Rid combo_box, const char* text);

returns

The index of the new item.

void Rcombo_box_clear_items(Rid combo_box);

int Rcombo_box_get_item_count(Rid combo_box);

const char* Rcombo_box_get_item_text(Rid combo_box, int index);

void Rcombo_box_set_selected(Rid combo_box, int index);

Selects an item. -1 selects nothing.

int Rcombo_box_get_selected(Rid combo_box);

typedef void (*RComboBoxChangedCallback)(Rid combo_box, int index, void* user_data);

void Rcombo_box_set_changed_callback(Rid combo_box, RComboBoxChangedCallback callback, void* user_data);

void Rseparator_set_orientation(Rid separator, ROrientation orientation);

R_HORIZONTAL draws a horizontal line (default).

int Rlist_view_add_item(Rid list_view, const char* text);

returns

The index of the new item.

void Rlist_view_set_item_text(Rid list_view, int index, const char* text);

const char* Rlist_view_get_item_text(Rid list_view, int index);

void Rlist_view_remove_item(Rid list_view, int index);

void Rlist_view_clear_items(Rid list_view);

int Rlist_view_get_item_count(Rid list_view);

typedef const char* (*RListItemTextCallback)(Rid list_view, int index, void* user_data);

Virtual mode, for large or computed data: the list stores nothing and asks for the text of the rows it draws. The returned string must stay valid until the next call.

void Rlist_view_set_virtual_items(Rid list_view, int count, RListItemTextCallback callback, void* user_data);

void Rlist_view_set_selected(Rid list_view, int index);

Selects a row. -1 selects nothing.

int Rlist_view_get_selected(Rid list_view);

void Rlist_view_scroll_to_item(Rid list_view, int index);

typedef void (*RListEventCallback)(Rid list_view, int index, void* user_data);

void Rlist_view_set_selection_changed_callback(Rid list_view, RListEventCallback callback, void* user_data);

void Rlist_view_set_activated_callback(Rid list_view, RListEventCallback callback, void* user_data);

Called on double click or Enter. This also fires the action of the widget.

Rid Rtree_view_add_item(Rid tree_view, Rid parent_item, const char* text);

Adds an item.

parent_item

Item to add under, or R_INVALID_ID for a top-level item.

returns

The handle of the new item.

void Rtree_item_destroy(Rid item);

Deletes an item and its descendants.

void Rtree_view_clear_items(Rid tree_view);

int Rtree_item_is_valid(Rid item);

void Rtree_item_set_text(Rid item, const char* text);

const char* Rtree_item_get_text(Rid item);

void Rtree_item_set_expanded(Rid item, int expanded);

int Rtree_item_is_expanded(Rid item);

void Rtree_item_set_user_handle(Rid item, void* handle);

void* Rtree_item_get_user_handle(Rid item);

int Rtree_view_get_item_count(Rid tree_view);

Top-level items of a tree.

Rid Rtree_view_get_item(Rid tree_view, int index);

Rid Rtree_item_get_parent(Rid item);

returns

The parent item, or R_INVALID_ID for a top-level item.

int Rtree_item_get_child_count(Rid item);

Rid Rtree_item_get_child(Rid item, int index);

void Rtree_view_set_selected_item(Rid tree_view, Rid item);

Selects an item. R_INVALID_ID selects nothing.

Rid Rtree_view_get_selected_item(Rid tree_view);

typedef void (*RTreeEventCallback)(Rid tree_view, Rid item, void* user_data);

void Rtree_view_set_selection_changed_callback(Rid tree_view, RTreeEventCallback callback, void* user_data);

void Rtree_view_set_activated_callback(Rid tree_view, RTreeEventCallback callback, void* user_data);

Called on double click or Enter. This also fires the action of the widget.

void Rtree_item_set_icon(Rid item, Rid texture, float u0, float v0, float u1, float v1);

Icon drawn before the text of the item (a region u0,v0,u1,v1 of the texture). R_INVALID_ID removes it.

void Rtree_item_set_text_color(Rid item, float r, float g, float b, float a);

Color of the text of the item; alpha 0 goes back to the theme.

void Rtree_view_set_multi_select(Rid tree_view, int enabled);

Several items can be selected: Ctrl + click adds or removes one, Shift + click selects a range. The selection callback receives the item clicked last (the primary one, Rtree_view_get_selected_item).

void Rtree_item_set_selected(Rid item, int selected);

int Rtree_item_is_selected(Rid item);

void Rtree_view_clear_selection(Rid tree_view);

int Rtree_view_get_selection_count(Rid tree_view);

Selected items, top to bottom.

Rid Rtree_view_get_selection(Rid tree_view, int index);

void Rtree_view_scroll_to_item(Rid tree_view, Rid item);

typedef void (*RTreeContextCallback)(Rid tree_view, Rid item, float x, float y, void* user_data);

Right click: item is the item under the pointer (selected first), or R_INVALID_ID in the empty space; x, y in the window, for Rmenu_open.

void Rtree_view_set_context_callback(Rid tree_view, RTreeContextCallback callback, void* user_data);

void Rtree_view_set_drag_type(Rid tree_view, const char* type);

Items can be dragged: the selection is given to Rdrag_begin with this type and, as data, the handles of the items in decimal separated by spaces. NULL: no drag (default).

Rid Rtree_view_get_item_at(Rid tree_view, float local_x, float local_y);

Item at a point relative to the tree (drop callbacks give local_x, local_y), or R_INVALID_ID.

void Rtree_view_set_drop_highlight(Rid tree_view, Rid item, int whole_tree);

Highlights where a drop would go: an item, or the whole tree (whole_tree). R_INVALID_ID, 0 removes it.

Rid Rmenu_add_menu(Rid menu_bar_or_menu, const char* title);

Creates a menu inside a menu bar or as a sub-menu of another menu.

void Rmenu_set_title(Rid menu, const char* title);

Rid Rmenu_add_item(Rid menu, const char* text);

Rid Rmenu_add_separator(Rid menu);

void Rmenu_item_set_text(Rid item, const char* text);

const char* Rmenu_item_get_text(Rid item);

void Rmenu_item_set_shortcut(Rid item, RKey key, Ruint modifiers);

Shows a shortcut next to the item and triggers the item when the keys are pressed in the window of its menu bar.

void Rmenu_item_set_checkable(Rid item, int checkable);

void Rmenu_item_set_checked(Rid item, int checked);

void Rmenu_item_set_icon(Rid item, Rid texture, float u0, float v0, float u1, float v1, int tint);

Icon drawn before the text of a menu item (after the check mark column).

texture

R_INVALID_ID removes it. u0, v0, u1, v1 : region of the texture.

tint

R_TRUE: the texture is a mask drawn in the text color (monochrome icons).

int Rmenu_item_is_checked(Rid item);

typedef void (*RMenuItemClickedCallback)(Rid item, void* user_data);

void Rmenu_item_set_clicked_callback(Rid item, RMenuItemClickedCallback callback, void* user_data);

void Rmenu_open(Rid menu, Rid window, float x, float y);

Opens a menu as a popup at a position of the window (logical units).

void Rwindow_close_popups(Rid window);

Closes every open menu and popup of the window.

typedef struct RTileItem

What a tile shows, filled by the application when the tile is drawn.

typedef void (*RTileItemCallback)(Rid tile_view, int index, RTileItem* item, void* user_data);

Fills item for tile index. Called on the UI thread, only for the tiles in view.

typedef void (*RTileEventCallback)(Rid tile_view, int index, void* user_data);

Selection change (index: the current tile, or -1) and activation (double click, Enter).

typedef void (*RTileContextCallback)(Rid tile_view, int index, float x, float y, void* user_data);

Right click: the tile under the pointer (selected first), or -1 in the empty space; x, y in the window.

void Rtile_view_set_items(Rid tile_view, int count, RTileItemCallback callback, void* user_data);

Gives the tiles: count of them, described by callback. The selection is cleared.

void Rtile_view_refresh(Rid tile_view);

Draws the tiles again (their description changed, not their number).

int Rtile_view_get_count(Rid tile_view);

void Rtile_view_set_tile_size(Rid tile_view, float width, float height, float icon_size);

Size of a tile (its name included) and of its icon. Default 112 x 112, icon 64.

void Rtile_view_set_empty_text(Rid tile_view, const char* text);

void Rtile_view_set_selected(Rid tile_view, int index, int selected);

int Rtile_view_is_selected(Rid tile_view, int index);

void Rtile_view_clear_selection(Rid tile_view);

void Rtile_view_select_only(Rid tile_view, int index);

int Rtile_view_get_current(Rid tile_view);

The tile clicked last, or -1.

int Rtile_view_get_selection_count(Rid tile_view);

int Rtile_view_get_selection(Rid tile_view, int nth);

Index of the nth selected tile, in order.

void Rtile_view_scroll_to(Rid tile_view, int index);

int Rtile_view_get_item_at(Rid tile_view, float local_x, float local_y);

Tile at a point relative to the widget (drop callbacks give local_x, local_y), or -1.

void Rtile_view_set_drop_highlight(Rid tile_view, int index);

Highlights the tile a drop would go to; -1 removes it.

void Rtile_view_set_drag_type(Rid tile_view, const char* type);

Tiles can be dragged: the selected tiles are given to Rdrag_begin with this type and, as data, their indices separated by spaces.

typedef const char* (*RTileDragDataCallback)(Rid tile_view, void* user_data);

The data of a drag, given by the application (paths of files...) instead of the indices: the dragged tiles are the selected ones (Rtile_view_get_selection). The text returned is copied; NULL keeps the indices.

void Rtile_view_set_drag_data_callback(Rid tile_view, RTileDragDataCallback callback, void* user_data);

void Rtile_view_set_selection_changed_callback(Rid tile_view, RTileEventCallback callback, void* user_data);

void Rtile_view_set_activated_callback(Rid tile_view, RTileEventCallback callback, void* user_data);

void Rtile_view_set_context_callback(Rid tile_view, RTileContextCallback callback, void* user_data);

typedef enum RSyntax

Shorthands of Rtext_editor_set_language for two languages.

typedef enum RLanguageFlags

typedef struct RLanguageDesc

What the editor knows of a language. Every field but the name may be NULL. Lists of words are separated by spaces.

typedef enum RToken

What a part of the text is, for the language of the editor (Rtext_editor_get_token).

typedef enum RMarkerKind

What a marker says about the text it underlines.

Rid Rtext_editor_create(const char* text);

text

Initial content, or NULL.

void Rtext_editor_set_text(Rid editor, const char* text);

Replaces the whole text. The history of undo is cleared; the changed callback is not called.

const char* Rtext_editor_get_text(Rid editor);

returns

The whole text, lines separated by '\n'. Valid until the next call or the next edit.

int Rtext_editor_get_length(Rid editor);

returns

The number of bytes of Rtext_editor_get_text.

int Rtext_editor_get_line_count(Rid editor);

const char* Rtext_editor_get_line(Rid editor, int line);

returns

One line, without its line break. Valid until the next edit. NULL when line is out of range.

void Rtext_editor_insert_text(Rid editor, const char* text);

Types a text at the cursor, replacing the selection, as the user would: it can be undone and the changed callback is called.

void Rtext_editor_set_cursor(Rid editor, int line, int column);

void Rtext_editor_get_cursor(Rid editor, int* line, int* column);

void Rtext_editor_select(Rid editor, int from_line, int from_column, int to_line, int to_column);

Selects from one position to another; the cursor is on the second.

void Rtext_editor_select_all(Rid editor);

int Rtext_editor_get_selection(Rid editor, int* from_line, int* from_column, int* to_line, int* to_column);

Start and end of the selection, in the order of the text. Returns R_FALSE when nothing is selected.

const char* Rtext_editor_get_selected_text(Rid editor);

returns

The selected text, "" when there is none. Valid until the next call or the next edit.

void Rtext_editor_scroll_to_line(Rid editor, int line);

Scrolls so that a line is visible.

void Rtext_editor_undo(Rid editor);

void Rtext_editor_redo(Rid editor);

int Rtext_editor_can_undo(Rid editor);

int Rtext_editor_can_redo(Rid editor);

void Rtext_editor_set_read_only(Rid editor, int read_only);

A read-only editor can still be scrolled, selected and copied.

void Rtext_editor_set_word_wrap(Rid editor, int enabled);

Long lines continue on the next row instead of scrolling sideways. Off by default.

void Rtext_editor_set_line_numbers(Rid editor, int enabled);

Shows the line numbers in a margin. Off by default.

void Rtext_editor_set_tab_size(Rid editor, int spaces);

Width of a tab, in spaces (4 by default).

void Rtext_editor_set_tab_inserts_spaces(Rid editor, int enabled);

R_TRUE makes the Tab key insert spaces instead of a tab character. Off by default.

void Rtext_editor_set_syntax(Rid editor, RSyntax syntax);

The same as Rtext_editor_set_language with "XML", "C" or NULL.

void Rtext_editor_set_font(Rid editor, Rid font, float size);

font

R_INVALID_ID uses the font of the theme (or the fixed-width font, with a language).

size

0 uses the font size of the theme.

void Rtext_editor_set_placeholder(Rid editor, const char* text);

Text shown, dimmed, while the editor is empty.

void Rtext_editor_set_zoom(Rid editor, float zoom);

Zoom of the text: a factor of its font size, 1 = 100 % (0.5 .. 4). The user zooms with Ctrl + wheel (around the pointer), Ctrl + '+', Ctrl + '-' and Ctrl + 0 (back to 100 %), keypad included. Set by the program, the top of the view stays and the zoom callback is not called. XML: Zoom="1.25".

float Rtext_editor_get_zoom(Rid editor);

void Rtext_editor_set_zoomable(Rid editor, int zoomable);

R_FALSE: Ctrl + wheel and the keys do not zoom (the wheel scrolls). On by default. XML: Zoomable="false".

typedef void (*RTextEditorZoomCallback)(Rid editor, float zoom, void* user_data);

Called when the user zoomed (to zoom other editors the same, or to keep it for the next time).

void Rtext_editor_set_zoom_callback(Rid editor, RTextEditorZoomCallback callback, void* user_data);

int Rlanguage_register(const RLanguageDesc* desc);

Declares a language, or replaces the one that has this name: to add words to a built-in language, read it with Rlanguage_get, change what you want and register it again. The strings are copied.

int Rlanguage_get(const char* name, RLanguageDesc* desc);

Reads the description of a language. The strings belong to the library. Returns R_FALSE when it is unknown.

int Rlanguage_get_count(void);

const char* Rlanguage_get_name(int index);

const char* Rlanguage_for_file(const char* path);

returns

The name of the language of a file, from its extension, or NULL.

void Rtext_editor_set_language(Rid editor, const char* name);

Gives the editor a language, by name ("C++", "Python"...), by another usual name ("cpp", "js") or by the extension of its files ("rs"). NULL or "" removes it. An editor with a language uses the fixed-width font unless it was given a font.

const char* Rtext_editor_get_language(Rid editor);

returns

The name of the language of the editor, or "".

void Rtext_editor_set_markdown(Rid editor, int enabled);

R_TRUE makes the editor an editor of Markdown (the "Markdown" language; Markdown="true" in XML): the text stays as it is written, and what it formats shows while typing, strong text in bold, emphasized text in italic, titles in bold, code, links and marks in their colors. A label with Rlabel_set_markdown shows the same text formatted. R_FALSE removes the language.

int Rtext_editor_get_markdown(Rid editor);

RToken Rtext_editor_get_token(Rid editor, int line, int column);

What the language of the editor makes of the character at a position: the colors come from it. R_TOKEN_TEXT without a language.

void Rtext_editor_set_completion(Rid editor, int enabled);

R_FALSE stops the editor from proposing words by itself; Ctrl+Space still does. On by default.

void Rtext_editor_show_completions(Rid editor);

Proposes words for what is before the cursor, as Ctrl+Space does.

int Rtext_editor_is_completing(Rid editor);

typedef void (*RCompletionCallback)(Rid editor, const char* prefix, void* user_data);

Called each time the editor gathers its proposals, with the start of the word being typed: add your own with Rtext_editor_add_completion (the fields of a structure, the answers of a language server...). They are listed before the others.

void Rtext_editor_set_completion_callback(Rid editor, RCompletionCallback callback, void* user_data);

void Rtext_editor_add_completion(Rid editor, const char* text, const char* detail);

Adds a proposal. Only from a completion callback. Proposals that do not start with the prefix are left out; the others keep the order they were added in.

detail

A few words shown beside it ("function", "int"), or NULL.

void Rtext_editor_set_auto_pairs(Rid editor, int enabled);

R_FALSE stops the editor from closing brackets and quotes and from indenting after them. On by default; it only acts with a language.

void Rtext_editor_add_marker(Rid editor, int line, int from_column, int to_column, RMarkerKind kind, const char* message);

Underlines a part of a line and attaches a message to it, shown when the pointer rests there: an error of a compiler, a warning. Markers follow their line when text is added or removed above it, and go away when their own line is edited.

to_column

-1 for the end of the line.

void Rtext_editor_clear_markers(Rid editor);

int Rtext_editor_get_marker_count(Rid editor);

void Rtheme_set_token_color(RToken token, float r, float g, float b, float a);

Color of a kind of token in the theme in use, instead of the one Raven picks for dark and for light themes. Theme files set them with <Syntax Keyword="#FF7AB2" String="..."/>.

void Rtheme_get_token_color(RToken token, float* r, float* g, float* b, float* a);

void Rtheme_clear_token_colors(void);

Back to the colors Raven picks.

typedef void (*RTextEditorChangedCallback)(Rid editor, void* user_data);

Called after each change made by the user (typing, pasting, undoing...) or by Rtext_editor_insert_text. The action of the widget (OnChanged in XML) fires at the same time.

void Rtext_editor_set_changed_callback(Rid editor, RTextEditorChangedCallback callback, void* user_data);

typedef enum RHeaderButtons

Buttons of a header bar.

typedef enum RDockSide

Where a panel goes in a dock area, relative to another panel or to the whole area.

Rid Rheader_bar_create(const char* title);

title

Text shown in the bar; NULL shows the title of the window.

void Rheader_bar_set_title(Rid bar, const char* title);

title

NULL shows the title of the window.

void Rheader_bar_set_buttons(Rid bar, Ruint buttons);

buttons

Bitmask of RHeaderButtons. All by default; the maximize button only shows on a resizable window.

void Rheader_bar_set_button_side(Rid bar, RHAlign side);

side

R_HALIGN_RIGHT (default): minimize, maximize, close, as on Windows. R_HALIGN_LEFT: three round colored buttons, as on macOS.

void Rheader_bar_set_title_align(Rid bar, RHAlign align);

align

R_HALIGN_CENTER (default) or R_HALIGN_LEFT.

void Rheader_bar_set_title_notch(Rid bar, int notch);

R_TRUE: the title sits in a dark tab hanging from the top edge of the bar (slanted sides, round bottom corners). XML: TitleStyle="Notch".

void Rheader_bar_set_background(Rid bar, int enabled);

R_FALSE removes the background of the bar: for a header that floats above the content (in an Overlay) or sits inside a glass panel.

Rid Rdock_area_create(void);

void Rdock_area_add_panel(Rid area, Rid panel, const char* title, RDockSide side, Rid relative, float size);

Adds a panel. The dock area takes ownership of the widget.

title

Text of its tab.

side

Where it goes.

relative

A panel of the area to split or to share tabs with, or R_INVALID_ID for the whole area (with R_DOCK_TAB: the first group of tabs).

size

Part of the split space given to the new panel, 0..1 (0 = a half, or a quarter along the whole area).

void Rdock_area_move_panel(Rid area, Rid panel, RDockSide side, Rid relative, float size);

Moves a panel of the area somewhere else in it.

void Rdock_area_close_panel(Rid area, Rid panel);

Removes a panel and deletes it.

void Rdock_area_set_panel_title(Rid area, Rid panel, const char* title);

void Rdock_area_set_panel_icon(Rid area, Rid panel, Rid texture, float u0, float v0, float u1, float v1, int tint);

Icon drawn before the title of the tab of a panel (and on the chip while it is dragged).

texture

Texture of the icon, R_INVALID_ID removes it.

u0,v0,u1,v1

Region of the texture (0, 0, 1, 1 : all of it).

tint

R_TRUE: the texture is a mask drawn in the text color of the tab (monochrome icons).

void Rdock_area_set_panel_closable(Rid area, Rid panel, int closable);

R_FALSE removes the close button of the tab of a panel. Panels can be closed by default.

void Rdock_area_hide_panel(Rid area, Rid panel);

Takes a panel out of the arrangement without deleting it (a window of an application closed from its menu). Its tab disappears and its neighbours take its place; the area remembers where it was.

void Rdock_area_open_panel(Rid area, Rid panel);

Puts a hidden panel back where it was, and brings its tab to the front (also for a panel that is not hidden).

int Rdock_area_is_panel_open(Rid area, Rid panel);

returns

R_TRUE when the panel is in the arrangement (not hidden), shown or behind another tab.

void Rdock_area_set_close_hides(Rid area, int hides);

R_TRUE: the close button of a tab hides its panel (Rdock_area_hide_panel) instead of deleting it. XML: CloseHides="true". The close callback is asked first either way.

void Rdock_area_show_panel(Rid area, Rid panel);

Brings the tab of a panel to the front.

int Rdock_area_is_panel_shown(Rid area, Rid panel);

returns

R_TRUE when the panel is the one shown in its group of tabs.

void Rdock_area_set_movable(Rid area, int movable);

R_FALSE stops the user from moving the panels (the borders can still be dragged).

const char* Rdock_area_save_layout(Rid area);

Describes how the panels are arranged, as a short text to keep in a settings file. Panels are named by their widget name (Rwidget_set_name): unnamed panels are not part of the description.

returns

A string valid until the next call.

int Rdock_area_load_layout(Rid area, const char* layout);

Arranges the panels as a saved description says. Panels of the area that the description does not name keep a place; names it has that match no panel are ignored.

returns

R_FALSE when the text is not a layout (nothing is changed).

typedef int (*RDockCloseCallback)(Rid area, Rid panel, void* user_data);

Called when the user closes a panel, before it is deleted. Return R_FALSE to keep the panel.

void Rdock_area_set_close_callback(Rid area, RDockCloseCallback callback, void* user_data);

void Rdock_area_set_tearable(Rid area, int tearable);

Tearing: a tab dragged out of the area takes its panel to a window of its own (a floating area of the same family), and a tab dragged from such a window over the area docks it back where it is dropped. A double click on the tab of a floating window, or closing that window, puts its panels back where they were. Dragging the only tab of a floating window moves the window. R_TRUE by default; XML: Tearable="false". The functions of this area that take a panel also work on its panels that are in floating windows.

int Rdock_area_is_tearable(Rid area);

Rid Rdock_area_float_panel(Rid area, Rid panel, int x, int y);

Takes a panel to a window of its own, its top left corner at (x, y) on the screen. Returns the window.

void Rdock_area_dock_panel(Rid area, Rid panel);

A floating panel goes back where it was in the area.

Rid Rdock_area_get_panel_window(Rid area, Rid panel);

The window a floating panel is in, R_INVALID_ID when it is docked in the area.

typedef void (*RDockChangedCallback)(Rid area, void* user_data);

Called after the user moved, resized, showed or closed a panel.

void Rdock_area_set_changed_callback(Rid area, RDockChangedCallback callback, void* user_data);

Rid Risland_create(void);

void Risland_set_expanded(Rid island, int expanded);

Unfolds or folds the island. The changed callback is not called.

int Risland_is_expanded(Rid island);

void Risland_expand_for(Rid island, double seconds);

Unfolds the island, and folds it back by itself after a while: to tell something to the user. It stays open while the pointer is on it.

void Risland_set_expand_on_hover(Rid island, int enabled);

R_TRUE (default): the island unfolds under the pointer and folds back when it leaves.

void Risland_set_expand_on_click(Rid island, int enabled);

R_TRUE (default): a click on the island unfolds or folds it.

void Risland_set_attached(Rid island, int attached);

R_TRUE gives the island square upper corners: a notch that hangs from the edge it touches, instead of a capsule that floats under it.

typedef void (*RIslandChangedCallback)(Rid island, int expanded, void* user_data);

Called when the user unfolds or folds the island. The action of the widget (OnChanged) fires too.

void Risland_set_changed_callback(Rid island, RIslandChangedCallback callback, void* user_data);

void Rwindow_set_island(Rid window, Rid widget);

Shows a widget (usually an island) floating at the top of a window, in the middle, above its content. The window takes ownership; the previous one is deleted. R_INVALID_ID removes it. The padding of its slot (Rslot_set_padding) is its distance from the top edge.

Rid Rwindow_get_island(Rid window);

Rid Rcolor_picker_create(void);

void Rcolor_picker_set_color(Rid picker, float r, float g, float b, float a);

Sets the color (0..1 each). The callback is not called.

void Rcolor_picker_get_color(Rid picker, float* r, float* g, float* b, float* a);

void Rcolor_picker_set_hsv(Rid picker, float hue, float saturation, float value);

The same color as hue (0..360), saturation and value (0..1). The picker remembers the hue of a gray and the saturation of black, which red, green and blue cannot tell.

void Rcolor_picker_get_hsv(Rid picker, float* hue, float* saturation, float* value);

int Rcolor_picker_set_hex(Rid picker, const char* text);

Sets the color from text: "#RGB", "#RRGGBB", "#RRGGBBAA" (the '#' may be left out) or one of the color names of the XML attributes. A code without opacity leaves the opacity as it is.

returns

R_FALSE when the text is not a color (the color is unchanged).

const char* Rcolor_picker_get_hex(Rid picker);

returns

"#RRGGBB", or "#RRGGBBAA" when the opacity is shown and not full. Valid until the color changes.

void Rcolor_picker_set_alpha_enabled(Rid picker, int enabled);

R_TRUE (default) shows the opacity strip and the fourth number. R_FALSE: colors are opaque.

void Rcolor_picker_set_previous_color(Rid picker, float r, float g, float b, float a);

The color shown next to the current one, to compare with what was there before: clicking it comes back to it. Rcolor_picker_set_color does not change it; a popup picker takes it when it opens.

void Rcolor_picker_add_swatch(Rid picker, float r, float g, float b, float a);

Adds a color to the row of swatches: one click takes it.

void Rcolor_picker_clear_swatches(Rid picker);

int Rcolor_picker_get_swatch_count(Rid picker);

void Rcolor_picker_set_popup(Rid picker, int popup);

R_TRUE turns the widget into a swatch that opens the picker in a popup.

void Rcolor_picker_set_compact(Rid picker, int compact);

R_TRUE hides the code and the numbers: only the square, the strips and the swatches.

typedef void (*RColorChangedCallback)(Rid picker, float r, float g, float b, float a, void* user_data);

Called each time the user changes the color: while dragging, and when a code or a number is entered. The action of the widget (OnChanged in XML) fires too.

void Rcolor_picker_set_changed_callback(Rid picker, RColorChangedCallback callback, void* user_data);

void Rcolor_rgb_to_hsv(float r, float g, float b, float* hue, float* saturation, float* value);

Red, green, blue (0..1) to hue (0..360), saturation, value (0..1).

void Rcolor_hsv_to_rgb(float hue, float saturation, float value, float* r, float* g, float* b);

typedef enum RTimelineItem

What an item of a timeline is.

Rid Rtimeline_create(void);

void Rtimeline_set_duration(Rid timeline, double seconds);

Length of the sequence. The view and the playhead stay within 0 .. duration.

double Rtimeline_get_duration(Rid timeline);

void Rtimeline_set_time(Rid timeline, double seconds);

Moves the playhead. The time callback is not called.

double Rtimeline_get_time(Rid timeline);

void Rtimeline_set_frame_rate(Rid timeline, double frames_per_second);

Frames per second. With a frame rate the ruler counts in frames ("2:12" is second 2, frame 12) and everything snaps to frames; 0 (default) counts in seconds and snaps to the marks of the ruler.

double Rtimeline_get_frame_rate(Rid timeline);

void Rtimeline_set_snapping(Rid timeline, int enabled);

R_FALSE lets items be placed anywhere (holding Alt while dragging does it for one move).

void Rtimeline_set_view(Rid timeline, double start, double end);

The part of the sequence that is shown. Zooming is showing less.

void Rtimeline_get_view(Rid timeline, double* start, double* end);

void Rtimeline_set_playing(Rid timeline, int playing);

Makes the playhead run by itself, at the speed of the clock, calling the time callback at each frame; at the end it stops, or starts again with Rtimeline_set_loop.

int Rtimeline_is_playing(Rid timeline);

void Rtimeline_set_loop(Rid timeline, int loop);

int Rtimeline_add_track(Rid timeline, const char* name);

returns

The track, or 0. Tracks are shown in the order they were added.

void Rtimeline_remove_track(Rid timeline, int track);

Removes a track and everything on it.

int Rtimeline_get_track_count(Rid timeline);

int Rtimeline_get_track(Rid timeline, int index);

returns

The index-th track from the top, or 0.

void Rtimeline_set_track_name(Rid timeline, int track, const char* name);

const char* Rtimeline_get_track_name(Rid timeline, int track);

void Rtimeline_set_track_color(Rid timeline, int track, float r, float g, float b);

Color of the clips and keys of the track that have none of their own.

void Rtimeline_set_track_height(Rid timeline, int track, float height);

Height of the track in logical units; 0 = the default.

void Rtimeline_set_track_locked(Rid timeline, int track, int locked);

A locked track shows its items but does not let the user change them.

void Rtimeline_set_track_muted(Rid timeline, int track, int muted);

A muted track is drawn dimmed; what muting means is up to the application.

int Rtimeline_is_track_muted(Rid timeline, int track);

int Rtimeline_add_clip(Rid timeline, int track, double start, double length, const char* label);

returns

The clip, or 0 when the track does not exist.

int Rtimeline_add_key(Rid timeline, int track, double time);

returns

The key, or 0.

int Rtimeline_add_marker(Rid timeline, double time, const char* label);

A named moment of the whole sequence, shown on the ruler and across the tracks.

void Rtimeline_remove_item(Rid timeline, int item);

void Rtimeline_clear(Rid timeline);

Removes every track, clip, key and marker.

RTimelineItem Rtimeline_get_item_type(Rid timeline, int item);

int Rtimeline_get_item_track(Rid timeline, int item);

returns

The track of a clip or of a key; 0 for a marker.

double Rtimeline_get_item_start(Rid timeline, int item);

double Rtimeline_get_item_length(Rid timeline, int item);

returns

The length of a clip; 0 for a key or a marker.

void Rtimeline_set_item(Rid timeline, int item, int track, double start, double length);

Moves an item: to another track (0 = keep), another start, another length (clips; negative = keep).

void Rtimeline_set_item_label(Rid timeline, int item, const char* label);

const char* Rtimeline_get_item_label(Rid timeline, int item);

void Rtimeline_set_item_color(Rid timeline, int item, float r, float g, float b);

int Rtimeline_get_item_count(Rid timeline);

int Rtimeline_get_item(Rid timeline, int index);

returns

The index-th item, in the order they were added, or 0.

void Rtimeline_select(Rid timeline, int item, int add);

Selects an item, alone or (add) with the ones already selected.

void Rtimeline_clear_selection(Rid timeline);

int Rtimeline_is_selected(Rid timeline, int item);

int Rtimeline_get_selection_count(Rid timeline);

int Rtimeline_get_selected(Rid timeline, int index);

typedef void (*RTimelineTimeCallback)(Rid timeline, double seconds, void* user_data);

The playhead moved: scrubbed by the user, or running by itself.

void Rtimeline_set_time_callback(Rid timeline, RTimelineTimeCallback callback, void* user_data);

typedef void (*RTimelineItemCallback)(Rid timeline, int item, void* user_data);

Something happened to an item; which thing depends on the function the callback was given to.

void Rtimeline_set_changed_callback(Rid timeline, RTimelineItemCallback callback, void* user_data);

Called for each item the user moved, stretched or retimed, as it happens. The action of the widget (OnChanged in XML) fires once per gesture, when the button is released.

void Rtimeline_set_selection_callback(Rid timeline, RTimelineItemCallback callback, void* user_data);

Called when the selection changed; item is the item just clicked, or 0.

void Rtimeline_set_activated_callback(Rid timeline, RTimelineItemCallback callback, void* user_data);

Called when an item is double-clicked.

void Rtimeline_set_removed_callback(Rid timeline, RTimelineItemCallback callback, void* user_data);

Called when the user deletes an item (the Delete key), before it is removed: its values can still be read. Without this callback the Delete key does nothing: the application decides what can be deleted.

Rid Rnode_graph_create(void);

int Rnode_graph_add_node(Rid graph, const char* title, float x, float y);

x,y

Top-left corner of the node, in the units of the canvas.

void Rnode_graph_remove_node(Rid graph, int node);

Removes a node, its pins, their links, and the widget it holds.

void Rnode_graph_clear(Rid graph);

int Rnode_graph_get_node_count(Rid graph);

int Rnode_graph_get_node(Rid graph, int index);

void Rnode_graph_set_node_title(Rid graph, int node, const char* title);

const char* Rnode_graph_get_node_title(Rid graph, int node);

void Rnode_graph_set_node_position(Rid graph, int node, float x, float y);

void Rnode_graph_get_node_position(Rid graph, int node, float* x, float* y);

void Rnode_graph_get_node_size(Rid graph, int node, float* width, float* height);

Size of a node on the canvas: Raven works it out from its title, its pins and its content.

void Rnode_graph_set_node_color(Rid graph, int node, float r, float g, float b);

Color of the header of the node; without one it takes the accent color of the theme.

void Rnode_graph_set_node_content(Rid graph, int node, Rid widget);

Puts a widget inside the node, under its pins: the graph owns it from now on. R_INVALID_ID removes (and deletes) the one it had.

Rid Rnode_graph_get_node_content(Rid graph, int node);

void Rnode_graph_set_node_name(Rid graph, int node, const char* name);

Name of the node, the Name of its XML element: what <Link From="name.pin"> and Rnode_graph_find_node look for. Not shown.

const char* Rnode_graph_get_node_name(Rid graph, int node);

int Rnode_graph_find_node(Rid graph, const char* name);

returns

The node of that name, or 0.

void Rnode_graph_set_node_user_data(Rid graph, int node, void* user_data);

Value the application attaches to a node.

void* Rnode_graph_get_node_user_data(Rid graph, int node);

int Rnode_graph_add_input(Rid graph, int node, const char* label, const char* type);

type

Free text, or NULL for a pin that links to any type. @return The pin, or 0.

int Rnode_graph_add_output(Rid graph, int node, const char* label, const char* type);

void Rnode_graph_remove_pin(Rid graph, int pin);

int Rnode_graph_get_pin_node(Rid graph, int pin);

int Rnode_graph_is_pin_output(Rid graph, int pin);

const char* Rnode_graph_get_pin_label(Rid graph, int pin);

const char* Rnode_graph_get_pin_type(Rid graph, int pin);

void Rnode_graph_set_pin_name(Rid graph, int pin, const char* name);

Name of the pin for Rnode_graph_find_pin and for the links of XML; a pin without one answers to its label.

int Rnode_graph_find_pin(Rid graph, int node, const char* name);

returns

The pin of a node with that name (or label), or 0.

void Rnode_graph_get_pin_position(Rid graph, int pin, float* x, float* y);

Where a pin is on the canvas (the middle of its dot).

int Rnode_graph_get_input(Rid graph, int node, int index);

returns

The index-th input (or output) of a node, or 0.

int Rnode_graph_get_output(Rid graph, int node, int index);

void Rnode_graph_set_type_color(Rid graph, const char* type, float r, float g, float b);

Color of the pins of a type and of the links between them.

int Rnode_graph_connect(Rid graph, int output_pin, int input_pin);

Links an output to an input, as the user does by dragging. The connect callback is not asked.

returns

The link; 0 when the pins cannot be linked (two inputs, the same node, different types).

void Rnode_graph_disconnect(Rid graph, int link);

int Rnode_graph_get_link_count(Rid graph);

int Rnode_graph_get_link(Rid graph, int index);

int Rnode_graph_get_link_output(Rid graph, int link);

int Rnode_graph_get_link_input(Rid graph, int link);

int Rnode_graph_get_input_link(Rid graph, int input_pin);

returns

The link that arrives at an input pin, or 0.

void Rnode_graph_set_view(Rid graph, float center_x, float center_y, float zoom);

What the middle of the widget shows: a point of the canvas, and how large (1 = one unit per logical unit).

void Rnode_graph_get_view(Rid graph, float* center_x, float* center_y, float* zoom);

void Rnode_graph_to_canvas(Rid graph, float x, float y, float* canvas_x, float* canvas_y);

Converts a point of the widget (from its corner, as in the events) to the canvas, and back, with the view as it is shown now.

void Rnode_graph_from_canvas(Rid graph, float canvas_x, float canvas_y, float* x, float* y);

void Rnode_graph_frame_all(Rid graph);

Moves and zooms so that every node shows.

void Rnode_graph_set_grid_visible(Rid graph, int visible);

R_FALSE hides the grid of dots (shown by default).

void Rnode_graph_set_flow_visible(Rid graph, int visible);

The pulses of light that run along the links, from output to input. By default they run while the pointer is over the graph, and the window rests the rest of the time. R_TRUE makes them run all the time (the window then draws without pause); R_FALSE stops them.

void Rnode_graph_set_read_only(Rid graph, int read_only);

R_TRUE: the user can look but not move, link or delete.

void Rnode_graph_select_node(Rid graph, int node, int add);

void Rnode_graph_clear_selection(Rid graph);

int Rnode_graph_is_node_selected(Rid graph, int node);

int Rnode_graph_get_selection_count(Rid graph);

int Rnode_graph_get_selected_node(Rid graph, int index);

typedef int (*RNodeGraphConnectCallback)(Rid graph, int output_pin, int input_pin, void* user_data);

Asked when the user is about to link two pins that may be linked: return R_FALSE to refuse (a loop, a rule of the application).

void Rnode_graph_set_connect_callback(Rid graph, RNodeGraphConnectCallback callback, void* user_data);

typedef void (*RNodeGraphItemCallback)(Rid graph, int item, void* user_data);

Something happened to a link or to a node; which thing depends on the function the callback was given to.

void Rnode_graph_set_linked_callback(Rid graph, RNodeGraphItemCallback callback, void* user_data);

Called after the user made a link, and before a link the user removed goes (its pins can still be read).

void Rnode_graph_set_unlinked_callback(Rid graph, RNodeGraphItemCallback callback, void* user_data);

void Rnode_graph_set_moved_callback(Rid graph, RNodeGraphItemCallback callback, void* user_data);

Called for each node the user moved, when the button is released.

void Rnode_graph_set_selection_callback(Rid graph, RNodeGraphItemCallback callback, void* user_data);

Called when the selection changed; item is the node just clicked, or 0.

void Rnode_graph_set_removed_callback(Rid graph, RNodeGraphItemCallback callback, void* user_data);

Called when the user deletes a node (the Delete key), before it is removed. Without this callback the Delete key only removes links: the application decides whether nodes can be deleted.

void Rnode_graph_set_activated_callback(Rid graph, RNodeGraphItemCallback callback, void* user_data);

Called when the user double-clicks a node (to open what it stands for).

typedef void (*RNodeGraphContextCallback)(Rid graph, int node, float x, float y, void* user_data);

Right click: node is the node under the pointer (selected first), or 0 on the empty canvas; x, y are in the widget (Rnode_graph_to_canvas). Without this callback the right button does nothing.

void Rnode_graph_set_context_callback(Rid graph, RNodeGraphContextCallback callback, void* user_data);

void Rnode_graph_set_pin_multiple(Rid graph, int pin, int multiple);

R_TRUE: this input keeps every link made to it (a state that several transitions enter) instead of one. Pulling a wire from it starts a new one.

void Rnode_graph_set_node_active(Rid graph, int node, int active);

R_TRUE: the node is running (live debug) : a soft ring breathes around it.

void Rnode_graph_set_node_active_color(Rid graph, int node, float r, float g, float b);

Color of that ring (the success color of the theme by default).

void Rnode_graph_set_node_deletable(Rid graph, int node, int deletable);

R_FALSE: the Delete key does not remove this node (the root of a tree, the output of a graph).

void Rnode_graph_set_node_badge(Rid graph, int node, const char* text);

A short text in a pill on the top right corner of the node ("1", "!"...); NULL or "" removes it.

typedef enum RBlockShape

typedef enum RBlockPlace

typedef void (*RBlockEditorCallback)(Rid editor, int block, void* user_data);

A block changed (0: several, or one was deleted), or a script was clicked (its top block).

typedef void (*RBlockEditorContextCallback)(Rid editor, int block, float x, float y, void* user_data);

Right click: on a block (0 on the canvas), at x, y in the widget.

Rid Rblock_editor_create(void);

int Rblock_editor_add_kind(Rid editor, const char* name, const char* label, RBlockShape shape, const char* category);

A kind of block, and its block in the palette. Returns its index, -1 on an error.

void Rblock_editor_set_category_color(Rid editor, const char* category, float r, float g, float b);

Color of the blocks of a category (Raven picks one from its name otherwise).

void Rblock_editor_set_palette_visible(Rid editor, int visible);

int Rblock_editor_add_block(Rid editor, const char* kind, float x, float y);

A new block, the top of a script of its own at x, y (canvas units). Returns it, 0 on an error.

void Rblock_editor_remove_block(Rid editor, int block);

Removes a block and everything that hangs under it.

void Rblock_editor_clear(Rid editor);

int Rblock_editor_attach(Rid editor, int block, int target, RBlockPlace place, int index);

Puts a block (with what is under it) at a place of another one. R_FALSE when it does not fit there.

void Rblock_editor_detach(Rid editor, int block, float x, float y);

Takes a block (with what is under it) out: a script of its own at x, y.

int Rblock_editor_get_script_count(Rid editor);

int Rblock_editor_get_script(Rid editor, int index);

The top block of a script.

const char* Rblock_editor_get_kind(Rid editor, int block);

int Rblock_editor_get_next(Rid editor, int block);

The block under it, 0 if none.

int Rblock_editor_get_mouth_count(Rid editor, int block);

int Rblock_editor_get_body(Rid editor, int block, int mouth);

The first block in a mouth of a C block, 0 if empty.

int Rblock_editor_get_slot_count(Rid editor, int block);

int Rblock_editor_get_input(Rid editor, int block, int slot);

The value block in a slot, 0 if the slot holds a typed value.

const char* Rblock_editor_get_value(Rid editor, int block, int slot);

The typed value of a slot.

void Rblock_editor_set_value(Rid editor, int block, int slot, const char* value);

int Rblock_editor_get_parent(Rid editor, int block, RBlockPlace* place, int* index);

Where a block hangs: the block it hangs from (0: the top of a script).

void Rblock_editor_get_position(Rid editor, int block, float* x, float* y);

void Rblock_editor_set_block_glow(Rid editor, int block, int glow);

R_TRUE: the block is running: a halo breathes around it.

const char* Rblock_editor_save(Rid editor);

Every script as text (valid until the next call).

int Rblock_editor_load(Rid editor, const char* text);

Replaces the scripts with those of a text from Rblock_editor_save.

void Rblock_editor_set_changed_callback(Rid editor, RBlockEditorCallback callback, void* user_data);

void Rblock_editor_set_clicked_callback(Rid editor, RBlockEditorCallback callback, void* user_data);

void Rblock_editor_set_context_callback(Rid editor, RBlockEditorContextCallback callback, void* user_data);

void Rblock_editor_set_slot_options(Rid editor, const char* kind, int slot, const char* options);

The choices of a %m slot of a kind, separated by '\n' ("" : the slot is typed in).

void Rblock_editor_set_kind_visible(Rid editor, const char* kind, int visible);

R_FALSE: the kind is not in the palette (its blocks stay where they are).

int Rblock_editor_set_kind_label(Rid editor, const char* kind, const char* label);

A new label for a kind (a function that takes one more input...). The blocks of that kind keep the values of the slots that are still there.

void Rblock_editor_set_block_deletable(Rid editor, int block, int deletable);

R_FALSE: the user cannot delete the block (the entry of a function). Not saved.

int Rblock_editor_get_selection_count(Rid editor);

int Rblock_editor_get_selected(Rid editor, int index);

void Rblock_editor_select(Rid editor, int block, int add);

Selects a block (add: R_FALSE clears the selection first ; block 0 : only clears).

void Rblock_editor_get_view(Rid editor, float* x, float* y, float* zoom);

Pan (canvas units at the top left) and zoom.

void Rblock_editor_set_view(Rid editor, float x, float y, float zoom);

typedef struct RFileFilter

A kind of file in a file dialog.

typedef enum RFileDialogFlags

typedef struct RFileDialogDesc

Every field may be left to zero.

typedef enum RFileBrowserMode

typedef enum RMessageButtons

typedef enum RMessageResult

typedef void (*RDialogClosedCallback)(Rid content, int result, void* user_data);

Called when a dialog closes. result is the value given to Rdialog_close, 0 when dismissed.

void Rdialog_open(Rid window, Rid content, RDialogClosedCallback closed, void* user_data);

Shows a widget as a dialog of a window. The window takes ownership of content: it is deleted when the dialog closes, so read what you need from it before, or in closed. The Escape key dismisses the dialog (result 0).

void Rdialog_close(Rid widget, int result);

Closes the dialog that contains a widget (the content itself or anything inside it: the button that was clicked).

result

Passed to the closed callback and returned by Rdialog_run.

int Rdialog_run(Rid window, Rid content);

Shows a dialog and waits until it closes. Returns its result.

int Rwindow_has_dialog(Rid window);

returns

R_TRUE while a dialog is shown in the window.

RMessageResult Rmessage_box(Rid window, const char* title, const char* text, RMessageButtons buttons);

Shows a message with buttons and waits for the answer.

window

R_INVALID_ID: the first window of the application.

title

May be NULL.

const char* Rfile_dialog_open(const RFileDialogDesc* desc);

Asks for a file to open.

desc

May be NULL.

returns

The path (UTF-8), valid until the next file dialog, or NULL when the user cancelled.

const char* Rfile_dialog_save(const RFileDialogDesc* desc);

Asks where to save a file. An existing file was confirmed by the user.

const char* Rfile_dialog_select_folder(const RFileDialogDesc* desc);

Asks for a folder.

int Rfile_dialog_get_result_count(void);

What the last file dialog returned: several paths with R_FILE_DIALOG_MULTIPLE.

const char* Rfile_dialog_get_result(int index);

int Rfile_register_memory(const char* path, const void* data, size_t size, int copy);

Registers a file held in memory under a path: every file Raven reads (XML documents and their Include, Source and Font attributes, themes, textures, fonts, Rfile_read) is looked up here first, so that resources embedded in the executable need no file beside it. A relative path names the file as it is written in the XML once joined to the folder of the document that names it (Rxml_set_base_path for a document given as text), e.g. "ui/editor.xml". Paths compare with '/' and '\\' alike. Memory files are not watched for live reload. Call it after Rinit; Rshutdown forgets every file.

copy

R_TRUE: Raven keeps a copy; R_FALSE: data must outlive Raven (static data).

void Rfile_unregister_memory(const char* path);

int Rfile_is_memory(const char* path);

R_TRUE when path is a file registered with Rfile_register_memory.

char* Rfile_read(const char* path, size_t* size);

Whole files, with UTF-8 paths on every platform.

returns

Rfile_read: the content followed by a '\0', to release with Rmemory_free; NULL when the file cannot be read. size may be NULL.

int Rfile_write(const char* path, const void* data, size_t size);

Rid Rfile_browser_create(void);

void Rfile_browser_set_mode(Rid browser, RFileBrowserMode mode);

int Rfile_browser_set_directory(Rid browser, const char* path);

Shows a folder. "~" is the home of the user. Returns R_FALSE when it cannot be read.

const char* Rfile_browser_get_directory(Rid browser);

void Rfile_browser_refresh(Rid browser);

Reads the folder again.

void Rfile_browser_set_filters(Rid browser, const RFileFilter* filters, int count);

Kinds of files the user chooses from; the first one is active. The strings are copied.

void Rfile_browser_set_show_hidden(Rid browser, int show);

void Rfile_browser_set_multiple(Rid browser, int multiple);

R_TRUE lets several files be selected (Ctrl and Shift with a click).

void Rfile_browser_set_controls_visible(Rid browser, int visible);

R_FALSE hides the name field, the filter list and the buttons: what remains is an explorer to put in a side panel. Shown by default.

void Rfile_browser_set_places_visible(Rid browser, int visible);

R_FALSE hides the list of places on the left.

void Rfile_browser_set_file_name(Rid browser, const char* name);

Name typed in the name field (save mode).

void Rfile_browser_set_default_extension(Rid browser, const char* extension);

Added to a name typed without extension, in save mode.

int Rfile_browser_get_selection_count(Rid browser);

Paths of the selected entries. The strings are valid until the selection or the folder changes.

const char* Rfile_browser_get_selection(Rid browser, int index);

void Rfile_browser_select(Rid browser, const char* name);

Selects an entry of the folder by its name.

typedef void (*RFileBrowserCallback)(Rid browser, const char* path, void* user_data);

Called when the user chooses: a double click or Enter on a file, the Open / Save button. path is the first chosen path; with several files, read them with Rfile_browser_get_selection. The action of the widget (OnActivated in XML) fires at the same time.

void Rfile_browser_set_accepted_callback(Rid browser, RFileBrowserCallback callback, void* user_data);

void Rfile_browser_set_cancelled_callback(Rid browser, RFileBrowserCallback callback, void* user_data);

Called by the Cancel button.

void Rfile_browser_set_selection_changed_callback(Rid browser, RFileBrowserCallback callback, void* user_data);

Called when the selection changes; path is the entry under the cursor, or NULL.

typedef struct RViewportDrawInfo

Passed to the draw callback of a viewport. Sizes are in pixels.

void Rviewport_set_texture(Rid viewport, Rid texture);

Shows a texture. R_INVALID_ID shows nothing.

void Rviewport_set_stretch(Rid viewport, RStretch stretch);

How the texture is fitted in the widget. Default: R_STRETCH_FILL.

void Rviewport_set_flip_y(Rid viewport, int flip);

R_TRUE flips the texture vertically (OpenGL framebuffers are bottom-up).

typedef void (*RViewportDrawCallback)(const RViewportDrawInfo* info, void* user_data);

Called on the render thread each time the window is rendered. State you bind (pipeline, descriptor sets, viewport, scissor) does not need to be restored. NULL removes the callback.

void Rviewport_set_draw_callback(Rid viewport, RViewportDrawCallback callback, void* user_data);

int Rviewport_set_native(Rid viewport, int enabled);

Creates (or destroys) the native child window of the viewport. The viewport must already be in a window.

returns

R_TRUE on success.

int Rviewport_get_native_handle(Rid viewport, RNativeWindow* native);

Fills native with the handles of the child window.

void Rviewport_get_pixel_size(Rid viewport, int* width, int* height);

Size of the viewport in pixels after the last layout.

typedef void (*RViewportResizeCallback)(Rid viewport, int width, int height, void* user_data);

Called on the UI thread when the pixel size changes: resize your render target here.

void Rviewport_set_resize_callback(Rid viewport, RViewportResizeCallback callback, void* user_data);

void Rviewport_set_realtime(Rid viewport, int realtime);

R_TRUE redraws the window every frame while the viewport is visible (game view). R_FALSE redraws only on Rwidget_invalidate (default).

typedef enum RMotion

How a spring moves. Animations in Raven are springs, as on iOS: a value is pulled toward its target and may run past it before settling, which is what makes a control feel alive rather than mechanical.

typedef struct RSpring

State of one animated value. Zero-initialize it and keep it with the widget.

typedef void (*RPaintCallback)(Rid widget, RPainter* painter, float width, float height, void* user_data);

typedef void (*RMeasureCallback)(Rid widget, float* width, float* height, void* user_data);

void Rcustom_set_paint_callback(Rid widget, RPaintCallback callback, void* user_data);

void Rcustom_set_measure_callback(Rid widget, RMeasureCallback callback, void* user_data);

Reports the desired size of the widget. Without it the widget asks for 0 x 0.

void Rdraw_rect(RPainter* painter, float x, float y, float width, float height, float radius, float r, float g, float b, float a);

Filled rectangle with rounded corners (radius 0 = sharp).

void Rdraw_rect_outline(RPainter* painter, float x, float y, float width, float height, float radius, float thickness, float r, float g, float b, float a);

Outline of a rounded rectangle, drawn inside its bounds.

void Rdraw_circle(RPainter* painter, float center_x, float center_y, float radius, float r, float g, float b, float a);

void Rdraw_line(RPainter* painter, float x0, float y0, float x1, float y1, float thickness, float r, float g, float b, float a);

Anti-aliased line with round caps.

void Rdraw_curve(RPainter* painter, float x0, float y0, float cx0, float cy0, float cx1, float cy1, float x1, float y1, float thickness, float r, float g, float b, float a);

Anti-aliased cubic Bezier curve from (x0, y0) to (x1, y1), pulled by two control points.

void Rdraw_triangle(RPainter* painter, float x0, float y0, float x1, float y1, float x2, float y2, float r, float g, float b, float a);

void Rdraw_image(RPainter* painter, Rid texture, float x, float y, float width, float height, float r, float g, float b, float a);

Texture stretched to a rectangle and multiplied by a tint color.

void Rdraw_text(RPainter* painter, Rid font, float size, float x, float y, const char* text, float r, float g, float b, float a);

Draws UTF-8 text; (x, y) is the top-left corner of the first line.

font

R_INVALID_ID uses the theme font.

size

0 uses R_METRIC_FONT_SIZE.

void Rdraw_glass(RPainter* painter, float x, float y, float width, float height, float radius, float r, float g, float b, float a);

Rounded rectangle of glass. It shows what was drawn before it, frosted and bent along its rim, under a tint: (r, g, b) is the color of the tint and a its strength (0 = clear glass, 1 = opaque color). Works with any theme. Needs a backend that implements glass (the Vulkan backend does).

float Rdraw_spring(RPainter* painter, RSpring* spring, float target, RMotion motion);

Animates a value from the paint callback of a custom widget. Moves the spring toward target by the time elapsed since the last frame and returns its value. While it moves, the window keeps drawing frames by itself. The first call puts the spring on its target.

    static RSpring size;                                  (zeroed)
    float s = Rdraw_spring(painter, &size, hovered ? 1.0f : 0.0f, R_MOTION_BOUNCY);
    Rdraw_circle(painter, cx, cy, 20.0f + 8.0f * s, ...);

void Rspring_kick(RSpring* spring, float velocity);

Pushes a spring away from its target (units per second): it bounces back.

void Rspring_set(RSpring* spring, float value);

Puts a spring at rest on a value, without animation.

void Rdraw_push_clip_rect(RPainter* painter, float x, float y, float width, float height);

Restricts the following draws to a rectangle, intersected with the current one.

void Rdraw_pop_clip_rect(RPainter* painter);

typedef enum REffect

The effects that come with Raven (Reffect_get).

typedef enum RShaderFlags

Flags of Rshader_create.

typedef struct RShaderLook

How an effect is drawn. Start from Rshader_look_init.

Rid Rshader_create(const void* spirv, size_t size, Ruint flags);

A shader from SPIR-V code (a fragment shader written with raven_effect.glsl, as in a .spv file): size bytes, copied. R_INVALID_ID when the code is not SPIR-V; a backend that refuses it reports an error and the effect is drawn as a rectangle.

Rid Rshader_create_from_file(const char* path, Ruint flags);

The same, from a .spv file (UTF-8 path, relative to the current folder).

void Rshader_destroy(Rid shader);

int Rshader_is_valid(Rid shader);

Ruint Rshader_get_flags(Rid shader);

Rid Reffect_get(REffect effect);

A built-in effect, created the first time it is asked for.

Rid Reffect_find(const char* name);

A built-in effect by its name ("aurora", "shimmer", "neon", "ripple", "plasma", "grain", "spotlight", "mesh"), or R_INVALID_ID.

const char* Reffect_get_name(REffect effect);

void Reffect_get_defaults(REffect effect, RShaderLook* look);

Its colors and parameters when nothing else is given (Rshader_look_init uses them).

void Rshader_look_init(RShaderLook* look);

White to white, no parameter, no texture, square corners, animated when the shader is.

void Rshader_look_defaults(Rid shader, RShaderLook* look);

Fills a look with the defaults of the shader when it is a built-in effect (else Rshader_look_init).

void Rdraw_shader(RPainter* painter, Rid shader, float x, float y, float width, float height, const RShaderLook* look);

From a paint callback: draws the effect over a rectangle of the widget (logical units, from its top left corner).

void Rborder_set_effect(Rid border, Rid shader, const RShaderLook* look);

The background of a border becomes an effect (its Background, if any, is drawn under it; its child over it). R_INVALID_ID removes it. XML: Effect="aurora" or Effect="file.spv", EffectColor, EffectColor2, EffectParams="a,b,c,d", EffectAnimate, EffectBackdrop (for a file).

Rid Rborder_get_effect(Rid border);

typedef struct RXmlError

Where and why a text could not be read (Rxml_document_parse).

typedef enum RXmlValueType

The kind of value an attribute takes.

typedef struct RXmlAttributeInfo

One attribute of a tag (Rxml_get_attribute_info). The strings belong to the library.

Rid Rwindow_create_from_xml(const char* xml, size_t size);

Creates a window from a document whose root element is <Window>.

xml

UTF-8 text. It does not need to be null-terminated.

size

Size of the text in bytes.

returns

The window, or R_INVALID_ID. Parse errors are reported with their line and column through the error callback (R_ERROR_XML).

Rid Rwindow_create_from_xml_file(const char* path);

Rid Rwidget_create_from_xml(const char* xml, size_t size);

Creates a widget tree from a document whose root element is a widget. The caller owns the returned widget until it is added to a parent.

Rid Rwidget_create_from_xml_file(const char* path);

typedef struct RXmlCompiledNode

Rid Rwindow_create_from_compiled(const RXmlCompiledNode* nodes, int count, const char* source);

Builds the window described by a compiled table whose root is <Window>. source names the file in the errors.

Rid Rwidget_create_from_compiled(const RXmlCompiledNode* nodes, int count, const char* source);

Builds the widget tree described by a compiled table.

void Rxml_set_base_path(const char* path);

Folder used to resolve relative paths found in XML (Source="...", Font="..."). The *FromXmlFile functions use the folder of the file.

void Rxml_set_live_reload(int enabled);

Turns live reload on or off. It is on by default; the environment variable RAVEN_LIVE_RELOAD=0 turns it off without rebuilding. When off, files are never looked at again.

int Rxml_get_live_reload(void);

typedef void (*RXmlReloadCallback)(const char* path, int ok, void* user_data);

Called each time a file was loaded again.

Widgets that had to be built again have new handles: this is the place to look them up again (Rwidget_find).

path

The file given when the interface was created.

ok

R_FALSE when the file could not be used (the interface is unchanged).

void Rxml_set_reload_callback(RXmlReloadCallback callback, void* user_data);

int Rxml_check_files(void);

Looks at the files now, without waiting for the next look (there are five per second), even when live reload is off.

returns

The number of files found changed.

int Rxml_register_widgets(const char* xml, size_t size);

Reads the <Widget Name="..."> declarations of a document (its root, or the children of a <Widgets> root) so that the tags they declare can be used in the documents loaded afterwards.

returns

The number of tags declared.

int Rxml_register_widgets_from_file(const char* path);

void Rxml_unregister_widget(const char* name);

int Rxml_is_widget_registered(const char* name);

int Rxml_get_registered_widget_count(void);

The declared tags, for tools that list them.

const char* Rxml_get_registered_widget_name(int index);

typedef Rid (*RXmlTagCreateCallback)(const char* tag, void* user_data);

Tags made by code. A library or an application that builds a widget of its own (a R_WIDGET_CUSTOM with its callbacks, or an assembly of widgets) can give it a tag: documents then write <MyWidget .../> as they write <Button/>.

create makes the widget and returns it. set_attribute (may be NULL) receives the attributes of the element before Raven looks at them: it returns R_TRUE for those it understands, R_FALSE to leave them to the widget (Name, Width, Slot..., and what its type knows). Rwidget_set_attribute goes through it too.

typedef int (*RXmlTagAttributeCallback)(Rid widget, const char* name, const char* value, void* user_data);

int Rxml_register_tag(const char* tag, RXmlTagCreateCallback create, RXmlTagAttributeCallback set_attribute, void* user_data);

Registers a tag (or replaces what it was registered with).

returns

R_FALSE when the name is the one of a widget of Raven, or when too many tags are registered (64).

void Rxml_unregister_tag(const char* tag);

int Rxml_is_tag_registered(const char* tag);

const char* Rxml_resolve_path(const char* path);

The path of a file named in a document: as the attributes Source of Raven read it, relative to the folder of the document being loaded (while it loads), else to the base path. For the attributes of the tags made by code that name files.

returns

The path; valid until the next call.

int Rwidget_set_attribute(Rid widget, const char* name, const char* value);

Sets a property from text, with the names and value syntax of the XML attributes. Handy for scripting and data-driven tools.

returns

R_TRUE when the attribute exists for this widget and the value is valid.

Rid Rxml_document_create(const char* root_tag);

A new document with one element.

Rid Rxml_document_parse(const char* xml, size_t size, RXmlError* error);

Reads a text into a document. Comments are kept.

error

When not NULL, a mistake in the text is described there and nothing is reported; when NULL it goes to the error callback.

returns

The document, or R_INVALID_ID.

Rid Rxml_document_load(const char* path);

Reads a file. The paths written in it are relative to its folder.

void Rxml_document_destroy(Rid document);

Releases a document and its nodes. What was built from it lives on.

int Rxml_document_is_valid(Rid document);

Rid Rxml_document_get_root(Rid document);

const char* Rxml_document_to_string(Rid document);

Writes the document as text, one element per line, indented with tabs. Rxml_node_get_line then says where each node was written.

returns

The text, valid until the next call for this document or its destruction.

int Rxml_document_save(Rid document, const char* path);

Rid Rxml_document_create_widget(Rid document);

Builds the widgets the document describes, as Rwidget_create_from_xml does. When the root is a <Window>, builds what the window would show (R_INVALID_ID when it is empty).

Rid Rxml_document_create_window(Rid document);

Builds the window the document describes, as Rwindow_create_from_xml does.

int Rxml_node_is_valid(Rid node);

Rid Rxml_node_get_document(Rid node);

const char* Rxml_node_get_tag(Rid node);

returns

The tag of an element, "" for a comment.

void Rxml_node_set_tag(Rid node, const char* tag);

int Rxml_node_is_comment(Rid node);

const char* Rxml_node_get_text(Rid node);

The text inside an element (<Label>this</Label>), or the text of a comment.

void Rxml_node_set_text(Rid node, const char* text);

Rid Rxml_node_get_parent(Rid node);

int Rxml_node_get_child_count(Rid node);

Rid Rxml_node_get_child(Rid node, int index);

int Rxml_node_get_index(Rid node);

returns

The place of a node among the children of its parent; 0 for the root.

Rid Rxml_node_add_child(Rid parent, const char* tag, int index);

index

Where among the children; -1 for the end.

Rid Rxml_node_add_comment(Rid parent, const char* text, int index);

Rid Rxml_node_add_xml(Rid parent, const char* xml, size_t size, int index);

Reads a piece of XML (one element and what it contains) and adds it: what a palette, a paste or a template inserts.

void Rxml_node_remove(Rid node);

Removes a node and what it contains. The root stays.

int Rxml_node_move(Rid node, Rid new_parent, int index);

Moves a node, with what it contains, under another parent of the same document or elsewhere under its own.

index

Where among the children of the new parent, counted once the node has left its place; -1 for the end.

returns

R_FALSE when it cannot be done (the root, or a parent that is inside the node).

Rid Rxml_node_duplicate(Rid node);

Copies a node and what it contains, right after it. Returns the copy.

const char* Rxml_node_to_string(Rid node);

The node as text. Valid until the next call for this document.

int Rxml_node_get_attribute_count(Rid node);

const char* Rxml_node_get_attribute_name(Rid node, int index);

const char* Rxml_node_get_attribute_value(Rid node, int index);

const char* Rxml_node_get_attribute(Rid node, const char* name);

returns

The value of an attribute (names are compared without case), or NULL when the node does not have it.

void Rxml_node_set_attribute(Rid node, const char* name, const char* value);

Sets an attribute, added after the others when it is new. A NULL value removes it.

int Rxml_node_get_line(Rid node);

returns

The line of the node, starting at 1, in the text the document was read from or last written to; 0 for a node added since.

Rid Rxml_node_get_widget(Rid node);

returns

The widget (the window, for a <Window>) the node became the last time the document was built, or R_INVALID_ID: never built, destroyed since, or not a widget (an <Item>, a comment). A tag declared with <Widget> gives the widget it stands for.

Rid Rwidget_get_xml_node(Rid widget);

returns

The node a widget was built from, or R_INVALID_ID: not built from a document, or the document is gone. The widgets inside a tag declared with <Widget> all come from the node where the tag is used.

int Rxml_get_tag_count(void);

The tags of the library, <Window> included. Those declared with <Widget> are listed by Rxml_get_registered_widget_name.

const char* Rxml_get_tag_name(int index);

const char* Rxml_get_tag_description(const char* tag);

returns

One line about a tag, "" when there is nothing to say.

int Rxml_get_tag_children(const char* tag);

returns

0: no child widget; 1: a single one; 2: any number. Declared and unknown tags give 2.

int Rxml_get_attribute_count(const char* tag);

The attributes of a tag: its own first, then those every widget has, then those of its place in its parent. For a tag declared with <Widget>, its own are its parameters.

int Rxml_get_attribute_info(const char* tag, int index, RXmlAttributeInfo* info);

int Rlocale_load_csv(const char* path);

Loads a CSV table of translations from a file. Returns the number of keys read, -1 on an error.

int Rlocale_load_csv_from_memory(const char* csv, size_t size);

Same, from text in memory (UTF-8).

void Rlocale_clear(void);

Forgets every table.

void Rlocale_set_text(const char* language, const char* key, const char* text);

Adds or replaces one text of one language.

int Rlocale_get_language_count(void);

Number of languages in the tables, and their codes, in the order of the columns.

const char* Rlocale_get_language_at(int index);

int Rlocale_set_language(const char* code);

Chooses the language: an exact code ("pt-BR"), or its first part ("pt") when the tables have no such column. Every widget that shows a key is updated, and the layout of the windows follows its direction (an Arabic, Hebrew, Persian or Urdu language is laid out from right to left, see Rset_layout_direction). Returns R_FALSE when no column matches (the language is set all the same: the texts fall back).

const char* Rlocale_get_language(void);

const char* Rlocale_get_system_language(void);

The language of the user, from the system ("fr-FR", "en-US"...).

void Rlocale_set_fallback_language(const char* code);

The language whose texts are shown when the current one has none (default: the first column).

int Rlocale_is_rtl(void);

R_TRUE when the language is written from right to left.

typedef void (*RLocaleChangedCallback)(const char* language, void* user_data);

void Rlocale_set_changed_callback(RLocaleChangedCallback callback, void* user_data);

Called after the language or the tables changed (the widgets are already updated).

const char* Rtr(const char* key);

The text of a key in the current language (see the fallbacks above). Never NULL.

int Rtr_exists(const char* key);

R_TRUE when the key has a text in the current language or the fallback one.

const char* Rtr_format(const char* key, const char*const* args, int arg_count);

The text of a key with its {0} {1} ... replaced by the arguments (translators may put them in any order). "{{" is a brace.

const char* Rtr_plural(const char* key, int count);

The plural form of a key for a count: the key followed by the CLDR category of the count in the current language (".zero", ".one", ".two", ".few", ".many", ".other"), else ".other", else the key itself. {n} is replaced by the count, written in the conventions of the language.

void Rwidget_set_text_key(Rid widget, const char* attribute, const char* key);

Makes a widget show a key: an attribute ("Text", "Tooltip", "Title", "Placeholder"... any attribute that takes a text) is set to the translation now and every time the language changes. NULL or "" stops it. Same as Rwidget_set_attribute(widget, attribute, "@key").

const char* Rlocale_format_number(double value, int decimals);

A number written in the conventions of the language: decimal separator and digit grouping ("1 234,5" in French).

void Raccessibility_set_text_scale(float scale);

Size of every text, 1 = as designed (0.5 to 4). Controls grow with their text.

float Raccessibility_get_text_scale(void);

void Raccessibility_set_high_contrast(int enabled);

Themes of high contrast: black and white, yellow focus, thick borders (the dark one, or the light one when the theme in use is light). R_FALSE goes back to the theme used before.

int Raccessibility_get_high_contrast(void);

void Raccessibility_set_focus_always_visible(int enabled);

R_TRUE: the focus ring is always shown (not only after the keyboard was used), and thicker.

int Raccessibility_get_focus_always_visible(void);

void Raccessibility_set_reduce_motion(int enabled);

Reduced motion, for the whole application: R_TRUE and nothing moves by itself. Changes are immediate (no spring, no slide, no bounce, no transition), and the effects (raven_shader.h) stand still; they still follow the pointer. Same as Rset_animations_enabled(R_FALSE).

int Raccessibility_get_reduce_motion(void);

typedef enum RColorFilter

void Raccessibility_set_color_filter(RColorFilter filter);

A filter on the colors of the interface (pictures and viewports keep theirs).

RColorFilter Raccessibility_get_color_filter(void);

typedef struct RAccessibilitySettings

What the system asks for.

void Raccessibility_get_system_settings(RAccessibilitySettings* settings);

void Raccessibility_follow_system(void);

Applies the settings of the system (text size, contrast, motion).

typedef enum RAccessibleRole

void Rwidget_set_accessible_name(Rid widget, const char* name);

What the screen reader says of the widget; NULL: what it shows (or the label before it).

const char* Rwidget_get_accessible_name(Rid widget);

The name the screen reader uses (given, or found). Valid until the next call.

void Rwidget_set_accessible_description(Rid widget, const char* description);

A longer explanation, read after the name.

void Rwidget_set_accessible_role(Rid widget, RAccessibleRole role);

RAccessibleRole Rwidget_get_accessible_role(Rid widget);

The role the screen reader sees (given, or the one of the type).

void Rwidget_set_accessible_hidden(Rid widget, int hidden);

R_TRUE: hidden from screen readers, with what it contains (decoration).

void Rwidget_set_accessible_labelled_by(Rid widget, Rid label);

The widget is named by another one (a label): its text is the name.

void Raccessibility_announce(const char* text, int assertive);

Has a message read (a save that ended, an error). assertive: interrupts what is being read.

int Raccessibility_is_screen_reader_active(void);

R_TRUE when a screen reader is reading the windows of the application.

typedef struct RSharedTextureInfo

Memory exported by Rvulkan_texture_create_shared.

const char*const* Rvulkan_get_required_instance_extensions(Ruint* count);

By default Raven creates its own VkInstance and VkDevice. To make Raven render with the device of the application (or of HRL), create the instance and the device with the extensions returned below, then pass them here.

const char*const* Rvulkan_get_required_device_extensions(Ruint* count);

void Rvulkan_set_external_device(void* instance, void* physical_device, void* device, void* queue, Ruint queue_family);

Makes Raven use an existing device. Raven does not destroy these objects.

instance

VkInstance

physical_device

VkPhysicalDevice

device

VkDevice

queue

VkQueue supporting graphics and presentation

queue_family

Family index of queue

typedef void (*RVulkanQueueLockCallback)(void* user_data);

A VkQueue must not be used by two threads at once. When the queue is shared with the application, Raven calls lock before and unlock after each use of the queue from its render thread.

void Rvulkan_set_queue_lock_callbacks(RVulkanQueueLockCallback lock, RVulkanQueueLockCallback unlock, void* user_data);

void* Rvulkan_get_instance(void);

Opaque VkInstance, or NULL before initialization / on another backend.

void* Rvulkan_get_physical_device(void);

Opaque VkPhysicalDevice.

void* Rvulkan_get_device(void);

Opaque VkDevice.

void* Rvulkan_get_graphics_queue(void);

Opaque VkQueue used for rendering and presentation.

Ruint Rvulkan_get_graphics_queue_family(void);

Rid Rvulkan_texture_create_from_image_view(uint64_t image_view, uint64_t sampler, int width, int height);

Wraps an application image so that widgets (Image, Viewport) can show it. The image must be in VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL whenever Raven renders, and must outlive the texture. Raven does not destroy it: destroy it after Rtexture_destroy, which returns once Raven no longer uses the image.

The values of the image are shown as they are (the UI is not color managed): use a UNORM view of an sRGB-encoded image. Alpha is honored, so clear the image with alpha 1 unless the viewport should be see-through.

image_view

Raw VkImageView handle (cast to uint64_t).

sampler

Raw VkSampler handle, or 0 for the Raven linear sampler.

void Rvulkan_texture_set_image_view(Rid texture, uint64_t image_view, uint64_t sampler, int width, int height);

Points an existing wrapped texture to another image view (after a resize). Returns once Raven no longer uses the previous view, which can then be destroyed.

Rid Rvulkan_texture_create_shared(int width, int height);

Creates an RGBA8 texture whose memory can be imported by another API or process (OpenGL GL_EXT_memory_object, another Vulkan device). Requires VK_KHR_external_memory_fd (POSIX) or _win32 (Windows).

returns

R_INVALID_ID when the device cannot export memory.

int Rvulkan_texture_get_shared_info(Rid texture, RSharedTextureInfo* info);

Exports the memory of a shared texture. Each call returns a new handle.

#define R_PRIM_RECT 0

#define R_PRIM_GLYPH 1

#define R_PRIM_SHADOW 2

#define R_PRIM_LINE 3

#define R_PRIM_TRIANGLE 4

#define R_PRIM_GLASS 5

#define R_PRIM_BLUR 6

#define R_PRIM_CURVE 7

#define R_PRIM_SHADER 8

#define R_PRIM_MASK 15

#define R_INSTANCE_TEXTURED 16

#define R_INSTANCE_NO_POINTER 32

typedef struct RDrawInstance

One primitive. All positions are in framebuffer pixels, origin top-left. Colors are 4 bytes R, G, B, A in memory order, straight (not premultiplied).

kind rect uv radii border_width RECT x0, y0, x1, y1 u0, v0, u1, v1 tl, tr, br, bl outline width GLYPH x0, y0, x1, y1 u0, v0, u1, v1 - - SHADOW x0, y0, x1, y1 - tl, tr, br, bl blur radius LINE ax, ay, bx, by - [0] = thickness - TRIANGLE ax, ay, bx, by - [0], [1] = cx, cy - GLASS x0, y0, x1, y1 see below tl, tr, br, bl bevel width BLUR x0, y0, x1, y1 see below tl, tr, br, bl outline width CURVE ax, ay, dx, dy see below bx, by, cx, cy thickness SHADER x0, y0, x1, y1 params 0..3 tl, tr, br, bl time (seconds)

Fragments outside clip (x0, y0, x1, y1) are discarded.

GLASS shows the *backdrop*: the frame as it was when the last R_DRAW_BACKDROP command was executed, sharp and blurred. Its fields are uv[0] frost, 0 = clear glass .. 1 = fully blurred uv[1] refraction: how far, in pixels, the rim bends the backdrop uv[2] saturation of the backdrop, 1 = unchanged uv[3] brightness added to the result (pressed / highlighted glass) color tint laid over the backdrop; its alpha is the strength border_color color of the light caught by the rim; its alpha is the intensity border_width width in pixels of the curved rim that refracts flags bits 8..15 = opacity of the whole primitive, 0..255 A backend without backdrop support may draw GLASS as a rounded rectangle filled with color.

CURVE is the cubic Bezier curve from a (rect[0], rect[1]) to d (rect[2], rect[3]) with the control points b and c (radii), drawn as a stroke with round ends: color color at a border_color color at d; the stroke shades from one to the other border_width thickness of the stroke, in pixels uv[0] radius of the halo around the stroke, in pixels (0 = none) uv[1] opacity of the halo next to the stroke, 0..1 uv[2] where the pulses are: they move from a to d as it grows (one pulse takes the place of the next every 1) uv[3] number of pulses along the curve (0 = none) flags bits 8..15 = how bright the pulses are, 0..255 A backend may draw it as a chain of LINE primitives.

BLUR shows the backdrop out of focus, flat (no rim, no bending): uv[0] radius of the blur, in pixels uv[1] grain, 0 = none .. 1 = frosted uv[2] saturation of the backdrop, 1 = unchanged uv[3] brightness added to the result color tint laid over the backdrop; its alpha is the strength border_color color of the outline, when border_width is not 0 flags bits 8..15 = opacity of the whole primitive, 0..255 A backend without backdrop support may draw it as a rounded rectangle filled with color.

SHADER is drawn by the fragment shader of its command (R_DRAW_SHADER), an effect of the application or of Raven (raven_shader.h): uv four parameters of the effect, as the application gave them color first color of the effect border_color second color of the effect border_width time of the frame, in seconds (for animated effects) flags bits 8..15 = opacity of the whole primitive, 0..255;

                bits 16..23 = how much the pointer is over it (hover), 0..255;
                bits 24..31 = how much it is pressed, 0..255;
                R_INSTANCE_NO_POINTER: the effect does not follow the pointer

The effect also gets RDrawData::pointer. A backend without custom shaders may draw it as a rounded rectangle filled with color.

In a window that can be seen through (RNativeWindow::transparent), the alpha of the frame is what the window system blends with: GLASS and BLUR keep the alpha of the backdrop where they are not tinted.

typedef enum RDrawCommandType

typedef struct RDrawCommand

typedef struct RDrawData

Everything needed to render one frame of one window.

typedef enum RTextureFormat