On this page

app.h

The app shell. It covers the window, the device, the ui context and the frame loop at three levels of control.

#include "isolenui/app/app.h". The guide starts at Overview.

Pinch zoom

Explained in Pinch zoom.

isolen_zoom_infoisolen_zoom_getisolen_set_zoomisolen_reset_zoomisolen_set_zoom_enabledisolen_zoom_enabledisolen_app_desc::no_zoomisolen_app_desc::max_zoomisolen_frame::zoom

Transparent windows

Explained in Transparent windows.

isolen_backdropisolen_backdrop_noneisolen_backdrop_micaisolen_backdrop_acrylicisolen_backdrop_vibrancyisolen_shadowisolen_shadow_autoisolen_shadow_onisolen_shadow_offisolen_hit_fnisolen_app_desc::transparentisolen_app_desc::shadowisolen_set_transparentisolen_transparentisolen_set_backdropisolen_set_shadowisolen_set_window_opacityisolen_set_click_throughisolen_set_hit_testisolen_set_hit_elements

Describing an app

Explained in Overview.

isolen_app_descisolen_app_defaultsisolen_view_fnISOLEN_MONITOR_SMALLESTisolen_app_desc::lists

Level 0

Explained in Level 0, a view.

isolen_run

Level 1

Explained in Level 1, your loop.

isolen_appisolen_frameisolen_openisolen_next_frameisolen_closeisolen_args

Level 2

Explained in Level 2, native handles.

isolen_flush_ui

Runtime control

Explained in Overview.

isolen_set_vsyncisolen_vsyncisolen_statusisolen_quitisolen_deviceisolen_windowisolen_fontisolen_set_themeisolen_set_imeisolen_app_desc::ime

Frame rate cap

Explained in Overview.

isolen_app_desc::fps_capisolen_set_fps_capisolen_fps_cap

Frame stats

Explained in Overview.

isolen_statsisolen_stats_get

Frames on demand

Explained in Overview.

isolen_app_desc::continuousisolen_redrawisolen_redraw_afterisolen_wake

Backend switching

Explained in Switching live.

isolen_set_backendisolen_backend

Window chrome

Explained in Window chrome.

isolen_app_desc::drawn_chromeisolen_app_desc::start_fullscreenisolen_app_desc::backdropisolen_frame::fullscreenisolen_frame::maximizedisolen_frame::window_changedisolen_set_fullscreenisolen_fullscreenisolen_set_maximizedisolen_maximizedisolen_minimizeisolen_restore

Example

app_desc.cpp
#include "isolenui/app/app.h"
#include "isolenui/kit/kit.h"

// every field of the description, from a side panel another program spawns
// on the smallest display to a full screen show that renders every tick
static isolen_app_desc side_panel(isolen_view_fn view, void* user)
{
    isolen_app_desc d = isolen_app_defaults();
    d.title = "levels";
    d.width = 420;
    d.height = 900;
    d.monitor = ISOLEN_MONITOR_SMALLEST;
    // shows without taking the focus away from the program that spawned it
    d.background = true;
    // no title bar of ours, the root the view declares into is then a view
    d.chrome = false;
    d.view = view;
    d.user = user;
    return d;
}

static isolen_app_desc stage_show(isolen_view_fn view, const ui::theme* theme)
{
    isolen_app_desc d = isolen_app_defaults();
    d.title = "stage";
    d.fullscreen = true;
    // an animated backdrop wants a frame every display tick, the default
    // only runs a frame when something changed
    d.continuous = true;
    d.vsync = true;
    // the target encodes on write, so the clear colour is given linear
    d.srgb = true;
    d.clear[0] = 0.0f;
    d.clear[1] = 0.0f;
    d.clear[2] = 0.0f;
    d.clear[3] = 1.0f;
    d.theme = theme;
    d.font = "assets\\objectivity.atlas";
    d.log = "stage.log";
    d.view = view;
    return d;
}

// runtime control from inside a view, all of it takes effect at the frame
// boundary so nothing changes under the frame that is being declared
static void settings(isolen_frame* f, void* user)
{
    (void)user;
    ui::ctx* u = f->ui;

    // an idle app sleeps, a clock that only changes once a second asks for
    // exactly one frame a second rather than setting continuous
    ui::textf(u, ui::mono(u), "up %.0f s", f->time);
    isolen_redraw_after(f->app, 1.0f);

    bool vsync = isolen_vsync(f->app);
    if (ui::toggle(u, "vsync", &vsync)) {
        isolen_set_vsync(f->app, vsync);
        isolen_status(f->app, "vsync %s", vsync ? "on" : "off");
    }
    if (ui::button(u, "quit")) {
        isolen_quit(f->app);
    }
}

int main(int argc, char** argv)
{
    const isolen_app_desc d = side_panel(settings, nullptr);
    return isolen_run(&d, argc, argv);
}

Last updated 23 October 2026