On this page

Portals and popovers

A portal is a box you declare anywhere in the tree that lays out, paints and hit tests as if it were declared at the root. A popover is a portal placed against a trigger after the tree is solved.

Portal, a box that escapes every clip and scroll, drawn by isolenPortal, a box that escapes every clip and scroll, drawn by isolen

Portals

ui::portal(u, style) opens a floating box under the root, whatever box is open at the time. Close it with ui::close, or use the ui_portal(u, style) block macro, which closes it for you. Inside, you declare children as usual.

  • It sizes against the overlay area and sits at its origin. The overlay area is the whole view unless the app sets one, and the shell sets it to the view below the title bar, see below. Use offset or a size to place it. See floating and shift.
  • No clip or scroll from the boxes it was declared inside reaches it. A portal declared deep in a scrolled view does not move with that view.
  • It paints above the whole tree and its scroll bars. Portals keep their declaration order among themselves.
  • It takes the pointer before anything under it, and a press on it never reaches the tree below. A portal that covers the view takes every press, which is what a scrim wants.
  • For focus and scopes it still counts as part of the box it was declared in, so a list opened from a field is inside that field's scope. The first 32 portals in a frame get this, and later ones count as outside every scope, with a warning.
  • After it closes, ui::last_id reads the element declared before the portal, so a widget that opened one still reads as its trigger.

portal returns false when the element cap or the depth limit dropped the box. Call close anyway, as with ui::open.

Popovers

ui::popover(u, style, anchor) opens a portal and places it against its anchor once the tree is solved. Close it with ui::close, or use ui_popover(u, style, anchor). It returns a const ui::placement*, which is filled during ui::end and stays valid until the next ui::begin.

Placement is seeded from where the trigger was last frame, so in the steady state one solve is enough. When the popover changes size to fit, the tree is solved a second time. Popovers are placed in declaration order, so a nested one reads a trigger that has already moved. The first 16 popovers in a frame are placed. Later ones open as plain portals at the origin and return an empty placement, with a warning.

sort_menu.cpp
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

struct sort_menu {
    bool open = false;
    uint32_t pick = 0;
};

static bool pointer_over(const ui::ctx* u, uint64_t id)
{
    const lay_box r = ui::rect_of(u, id);
    const ui::input* in = ui::input_of(u);
    return in->mouse_x >= r.x && in->mouse_y >= r.y && in->mouse_x < r.x + r.w
        && in->mouse_y < r.y + r.h;
}

static void sort_button(ui::ctx* u, sort_menu* m)
{
    const ui::theme* t = ui::theme_of(u);
    if (ui::button(u, "sort by")) {
        m->open = !m->open;
    }
    const uint64_t trigger = ui::last_id(u);
    if (!m->open) {
        return;
    }

    // below the button and at least as wide, flipped above when it lacks the room
    const ui::style panel = ui::col().pad(6.0f).gap(2.0f).bg(t->menu)
                                .border(1.0f, t->menu_edge).round(t->radius);
    ui_popover(u, panel, ui::anchor(trigger).gap(4.0f).with(ui::anchor_min_width))
    {
        // escape and a press outside come back as events on the scope
        ui::scope_events ev = {};
        ui::scope_begin(u, "sort scope", ui::col(), ui::scope_escape | ui::scope_outside, &ev);
        static const char* const names[] = { "name", "date", "size" };
        for (uint32_t i = 0; i < 3u; ++i) {
            if (ui::button(u, names[i])) {
                m->pick = i;
                m->open = false;
            }
        }
        ui::scope_end(u);
        // a press on the trigger is outside too, the button toggles it instead
        if (ev.escape || (ev.outside && !pointer_over(u, trigger))) {
            m->open = false;
        }
    }
}

Anchors

ui::anchor(id) sits against an element declared this frame. The element just declared is the cheapest, since it is bound at once. Anything else is looked up after the tree is declared. ui::anchor(box) sits against a rectangle in view units, such as a point on a chart.

Both start below the trigger, start aligned, with no gap, an 8 unit margin inside the overlay area, and anchor_flip | anchor_shift. Chain these to change them:

MethodSets
on(side, align)The side of the trigger and the alignment along that edge: lay_align_start, lay_align_centre or lay_align_end. Align defaults to start.
gap(px)The distance off the trigger.
along(px)A slide along the trigger's edge after aligning.
within(px)The margin kept from the overlay area's edges.
with(flags), without(flags)Adds or removes anchor_flag bits.

ui::side is side_bottom, side_top, side_right, side_left, side_start and side_end. Start and end are left and right, and swap when the trigger reads right to left. See direction and bidi.

FlagEffect
anchor_flipGoes to the opposite side when its own side lacks the room for its natural size and the other side has more.
anchor_shiftSlides back inside the overlay area, less the margin.
anchor_match_widthTakes the trigger's width.
anchor_min_widthIs at least as wide as the trigger.
anchor_fitIs held to the room on its side, the larger side when it can flip, so a view inside it scrolls instead of running off screen.
anchor_keepStays up when the trigger is clipped out of sight. Without it, a trigger scrolled out of its view hides the popover.

The kit's combo opens its list with anchor(id).with(anchor_min_width | anchor_fit), so the list is never narrower than the combo and scrolls when the window is short.

Placement

FieldMeaning
rectWhere the popover landed, in view units.
triggerThe trigger's rectangle.
atThe side it ended up on, after any flip. Start and end are already turned into left and right.
arrowWhere an arrow meets the trigger, measured along the facing edge from the popover's start: the middle of the overlap, or the trigger's centre when they do not overlap.
shownFalse when the trigger was not declared this frame, or was clipped out of sight without anchor_keep. The popover is then collapsed to nothing.
While you declare the popover, only trigger holds anything, last frame's rectangle. Read the rest from a canvas or a paint_on_top function, which run inside ui::end after placement.

paint_on_top

ui::paint_on_top(u, fn, box, user) queues a paint function that runs during ui::end after the tree, its bars and every portal, clipped to the overlay area, each on a layer of its own in queue order. It is for a canvas that draws a popup past its own box. The box is passed straight to fn, and user must outlive the frame. Up to 16 are taken per frame, and later ones are not painted.

overlays.cpp
#include "isolenui/ui/ui.h"

// a toast declared deep in a scrolling view still lays out against the whole
// window, paints above everything and takes the pointer first
static void saved_toast(ui::ctx* u, bool show)
{
    if (!show) {
        return;
    }
    const ui::theme* t = ui::theme_of(u);
    // a portal sits at the view origin, offset moves it from there
    ui_portal(u, ui::row().offset(16.0f, 16.0f).pad(12.0f, 8.0f).bg(t->menu)
                     .border(1.0f, t->menu_edge).round(t->radius))
    {
        ui::text(u, "preset saved", ui::body(u));
    }
}

// a canvas can read where its own popover landed, placement is filled once
// the tree is solved so paint in the same frame sees the final rect
struct tip_paint {
    const ui::placement* place;
    uint32_t colour;
};

static void paint_arrow(gfx_list* l, lay_box box, void* user)
{
    const tip_paint* p = static_cast<const tip_paint*>(user);
    if (!p->place->shown) {
        return;
    }
    const lay_box r = p->place->rect;
    const float x = r.x + p->place->arrow;
    const float y = p->place->at == ui::side_bottom ? r.y - 4.0f : r.y + r.h;
    gfx_fill(l, x - 4.0f, y, 8.0f, 4.0f, p->colour);
    (void)box;
}

static void help_tip(ui::ctx* u, uint64_t trigger, tip_paint* p)
{
    const ui::theme* t = ui::theme_of(u);
    p->colour = t->menu;
    p->place = ui::popover(u, ui::col().width(220.0f).pad(10.0f).bg(t->menu).round(t->radius),
                           ui::anchor(trigger).gap(8.0f).on(ui::side_bottom, lay_align_centre));
    ui::text(u, "drag a band to move it", ui::caption(u));
    ui::close(u);
    // p must outlive the frame, paint runs inside ui::end
    ui::paint_on_top(u, paint_arrow, lay_box{ 0.0f, 0.0f, 0.0f, 0.0f }, p);
}

The overlay area

Every overlay lives in one rect, the overlay area. Portals lay out and clip inside it, placement flips and slides against its edges, toasts centre in it, and shadows, focus rings and paint_on_top never reach past it. It is the whole view by default.

CallDoes
void ui::set_overlay_area(ctx* u, lay_box area)Sets the area for this frame. Call it after ui::begin and before any portal. It is clamped to the view.
lay_box ui::overlay_area(const ctx* u)The area this frame.

Under isolen_run the shell sets it every frame to the page rect, the view less the title bar, which is also the rect pinch zoom covers. With no bar, in full screen included, it is the whole view. A press outside the area, on the title bar, is never held by a modal or a blocking scope, never reported as an outside press, and never moves focus. The area the pointer is tested against is last frame's.

Underneath, in layout2

Two raw solver calls carry this. lay_open_root(c, style, spec) opens a floating box under the root whatever is open. It sizes against the portal area and no clip or scroll above it reaches it. lay_portal_area(c, area) sets that area after lay_begin, and it is the root by default. lay_translate(c, node, dx, dy) moves a solved subtree and clips it again against its new place, which is how popovers and pinned list rows move after the solve. See raw layout.

Last updated 6 October 2026