On this page

The app icon

isolenui/platform/appicon.h drives the app's icon outside its window: the taskbar button on Windows and the Dock tile on mac. It can show progress, a badge, a request for attention, thumbnail toolbar buttons, jump list tasks and recent documents.

Calls that act on one window take a window*. An app gets it from isolen_window(a). A feature one platform lacks returns false or does nothing, and logs once.

Platform support

FeatureWindowsmac
ProgressThe taskbar button's progress barDrawn on the Dock icon
Overlay badgeThe taskbar overlay iconDrawn in the Dock icon's bottom right corner
FlashFlashes the window and its taskbar buttonBounces the Dock icon
Thumbnail buttonsUp to 7 in the thumbnail toolbarReturns false and logs once
Jump list tasksUser tasks in the jump listReturns false and logs once
Recent documentsThe shell's recent items, which jump lists draw onThe app's recent documents list

On mac a count of zero is still accepted, so clearing the buttons or the tasks returns true everywhere. appicon_take_clicks returns 0 and appicon_has_clicks returns false.

Progress

appicon_set_progress takes a mode and a fraction from 0 to 1. The fraction is clamped, and a mode past appicon_progress_error is ignored.

ModeShows
appicon_progress_noneNo bar. Set this when the job ends.
appicon_progress_normalThe fraction, in the normal colour.
appicon_progress_indeterminateBusy with no known end. The fraction is ignored, and on mac the bar is drawn full.
appicon_progress_pausedThe fraction, in yellow.
appicon_progress_errorThe fraction, in red.

Overlay badge

appicon_set_overlay takes a square RGBA icon with straight alpha, size by size pixels, and a description that Windows reads out for accessibility. A null rgba clears the badge. It returns false when the icon cannot be built.

Flash

appicon_flash(w, true) asks for attention until the window takes the focus or appicon_flash(w, false) turns it off. Use it when a long job finishes while the app is in the background.

Thumbnail toolbar

appicon_set_buttons replaces the whole toolbar with up to APPICON_MAX_BUTTONS (7) appicon_button entries. A longer list is cut to 7 with a warning. Each button has your id, an optional RGBA icon of size pixels (16 or 20 suits the bar), a tooltip and flags.

FlagEffect
APPICON_BUTTON_DISABLEDShown greyed out and not clickable.
APPICON_BUTTON_DISMISSCloses the thumbnail preview when clicked.
APPICON_BUTTON_HIDDENNot shown.
APPICON_BUTTON_NO_BACKGROUNDNo button frame, only the icon.
APPICON_BUTTON_NON_INTERACTIVEShown enabled but does not react, for a status icon.

The shell only accepts buttons once the taskbar button exists. Buttons set before then are kept and added as soon as it appears, so it is safe to set them on the first frame. Progress and the overlay are replayed at the same moment.

Clicks are queued per window, up to 16. appicon_take_clicks copies up to cap ids into your array and empties the queue, so clicks past cap are lost. appicon_has_clicks is true while clicks are waiting.

A click wakes an idle app. The shell checks appicon_has_clicks when it decides whether a frame is needed, so take the clicks every frame. Clicks left in the queue keep the app running frames. See frames on demand.

Example

A player with a play and pause button in the thumbnail toolbar and an export job that shows its progress on the icon. The toolbar button and the in window button flip the same state. When the export ends the bar clears and the icon flashes.

player.cpp
#include "isolenui/app/app.h"
#include "isolenui/platform/appicon.h"

#include <stdint.h>
#include "isolenui/kit/kit.h"

enum : uint32_t { button_play = 1 };

struct player {
    bool playing;
    bool tried;
    bool has_bar;
    float job;
    uint8_t play_icon[16 * 16 * 4];
    uint8_t pause_icon[16 * 16 * 4];
};

// straight alpha rgba, a triangle for play and two bars for pause
static void paint_icons(player* p)
{
    for (uint32_t y = 0; y < 16; ++y) {
        for (uint32_t x = 0; x < 16; ++x) {
            const uint32_t i = (y * 16 + x) * 4;
            const int32_t dy = int32_t(y) - 8;
            const bool tri = x >= 4 && x < 13 && (dy < 0 ? -dy : dy) * 2 <= int32_t(x) - 4;
            const bool bars = y >= 3 && y < 13 && ((x >= 4 && x < 7) || (x >= 9 && x < 12));
            for (uint32_t c = 0; c < 3; ++c) {
                p->play_icon[i + c] = 255;
                p->pause_icon[i + c] = 255;
            }
            p->play_icon[i + 3] = tri ? 255 : 0;
            p->pause_icon[i + 3] = bars ? 255 : 0;
        }
    }
}

static bool set_buttons(window* w, const player* p)
{
    const appicon_button b = {
        button_play,
        p->playing ? p->pause_icon : p->play_icon,
        16,
        p->playing ? "pause" : "play",
        0,
    };
    return appicon_set_buttons(w, &b, 1);
}

static void view(isolen_frame* f, void* user)
{
    player* p = static_cast<player*>(user);
    window* w = isolen_window(f->app);
    bool toggled = false;

    // false on mac, the dock has no thumbnail toolbar
    if (!p->tried) {
        p->tried = true;
        p->has_bar = set_buttons(w, p);
    }

    // take every click each frame, clicks left in the queue keep the app awake
    // and clicks past cap are discarded, the queue holds sixteen
    uint32_t ids[16];
    const uint32_t n = appicon_take_clicks(w, ids, 16);
    for (uint32_t i = 0; i < n; ++i) {
        toggled ^= ids[i] == button_play;
    }

    ui::ctx* u = f->ui;
    ui_box(u, ui::col().pad(24.0f).gap(12.0f))
    {
        ui::text(u, p->playing ? "playing" : "paused", ui::head(u));
        if (ui::button(u, p->playing ? "pause" : "play")) {
            toggled = !toggled;
        }
        if (p->job < 0.0f && ui::button(u, "export")) {
            p->job = 0.0f;
        }
        if (p->job >= 0.0f) {
            ui::progress(u, p->job);
            ui::textf(u, ui::caption(u), "exporting, %.0f%%", p->job * 100.0f);
        }
    }

    if (toggled) {
        p->playing = !p->playing;
        if (p->has_bar) {
            set_buttons(w, p);
        }
    }

    if (p->job >= 0.0f) {
        p->job += f->dt * 0.25f;
        if (p->job < 1.0f) {
            appicon_set_progress(w, appicon_progress_normal, p->job);
            isolen_redraw(f->app);
        } else {
            p->job = -1.0f;
            appicon_set_progress(w, appicon_progress_none, 0.0f);
            appicon_flash(w, true);
        }
    }
}

int main(int argc, char** argv)
{
    static player p = {};
    p.job = -1.0f;
    paint_icons(&p);

    isolen_app_desc d = isolen_app_defaults();
    d.title = "isolen player";
    d.view = view;
    d.user = &p;
    return isolen_run(&d, argc, argv);
}

Jump list tasks

appicon_set_tasks sets the user tasks in the jump list. Each appicon_task has a title, a description shown as its tooltip, a program with its args, and an icon file with an icon_index. A null program means this executable, and a null icon means the program's own icon. A count of 0 clears the list. Tasks belong to the shell rather than a window, so they stay after the app exits.

Recent documents

appicon_add_recent adds a file path to the recent documents: the shell's recent items on Windows, and the app's recent documents list on mac. A null or empty path is ignored.

appicon_shell.cpp
#include "isolenui/platform/appicon.h"

#include <stdint.h>

// jump list tasks live with the shell, not a window, so they outlast the process
void register_tasks(void)
{
    const appicon_task tasks[] = {
        { "New deck", "open an empty deck", nullptr, "--new", nullptr, 0 },
        { "Rehearse", "start the last deck in rehearsal mode", nullptr, "--rehearse", nullptr, 0 },
    };
    appicon_set_tasks(tasks, 2);
}

void clear_tasks(void)
{
    appicon_set_tasks(nullptr, 0);
}

void opened(const char* path)
{
    appicon_add_recent(path);
}

void show_unread(window* w, const uint8_t* badge_rgba, uint32_t count)
{
    if (count) {
        appicon_set_overlay(w, badge_rgba, 16, "unread messages");
    } else {
        appicon_set_overlay(w, nullptr, 0, nullptr);
    }
}

void job_failed(window* w, float fraction)
{
    // error keeps the fraction, flash stops by itself once the window takes the focus
    appicon_set_progress(w, appicon_progress_error, fraction);
    appicon_flash(w, true);
}

Window proc hooks

On Windows the platform window calls appicon_is_created_message, appicon_button_created and appicon_clicked from its window procedure, and appicon_release when it closes. An app built on isolen_app never calls them. On mac, appicon_release stops a flash and gives the Dock its plain icon back.

Last updated 6 October 2026