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
| Feature | Windows | mac |
|---|---|---|
| Progress | The taskbar button's progress bar | Drawn on the Dock icon |
| Overlay badge | The taskbar overlay icon | Drawn in the Dock icon's bottom right corner |
| Flash | Flashes the window and its taskbar button | Bounces the Dock icon |
| Thumbnail buttons | Up to 7 in the thumbnail toolbar | Returns false and logs once |
| Jump list tasks | User tasks in the jump list | Returns false and logs once |
| Recent documents | The shell's recent items, which jump lists draw on | The 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.
| Mode | Shows |
|---|---|
appicon_progress_none | No bar. Set this when the job ends. |
appicon_progress_normal | The fraction, in the normal colour. |
appicon_progress_indeterminate | Busy with no known end. The fraction is ignored, and on mac the bar is drawn full. |
appicon_progress_paused | The fraction, in yellow. |
appicon_progress_error | The 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.
| Flag | Effect |
|---|---|
APPICON_BUTTON_DISABLED | Shown greyed out and not clickable. |
APPICON_BUTTON_DISMISS | Closes the thumbnail preview when clicked. |
APPICON_BUTTON_HIDDEN | Not shown. |
APPICON_BUTTON_NO_BACKGROUND | No button frame, only the icon. |
APPICON_BUTTON_NON_INTERACTIVE | Shown 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.
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.
#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.
#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.