On this page

Pinch zoom

A trackpad pinch magnifies the page the way a browser does. Nothing is laid out again: the shell draws the same tree through a zoom, so text and vector shapes are rasterised at the zoomed size and stay sharp.

What the shell does

  • The page. The zoom covers the page, the view under the title bar. The title bar is drawn a second time at 1x on top, so it never zooms. With chrome off or in full screen the page is the whole window.
  • Pinch. A pinch zooms the page about the point between the fingers. The page cannot go below 1x or past the deepest zoom, but a pinch can stretch past either end with some resistance, and when the fingers lift it springs back in 0.28 seconds.
  • Smart zoom. On macOS a two finger double tap fits the element under the pointer: the innermost one at least a quarter of the page wide and under 90 percent of it, with 16 units of margin on each side. If none fits, it zooms to 2x. A second double tap goes back to 1x.
  • Panning. While zoomed, a scroll pans the zoomed view first. Only what is left over once it reaches the edge of the page scrolls the views under the pointer.
  • Input. Pointer positions over the page are turned back into page units before the tree sees them, so hover, clicks and drags hit the same boxes they would at 1x. Widgets need no change.

The deepest zoom is isolen_app_desc::max_zoom. Zero, or anything up to 1, means five times. It is also capped so the window's longest side times the zoom stays within 16384 pixels.

On the CPU backend zoomed text samples its glyphs on a lattice, so panning a page zoomed to 3x takes 8.35 ms a frame, down from 33.5 ms.

Turning it off

no_zoom in isolen_app_desc turns the page zoom off. Every pinch then goes to the ui as input::pinch, and a smart zoom does nothing. Without it, input::pinch stays 0 unless an element keeps the pinch.

To switch it while the app runs, isolen_set_zoom_enabled(a, false) turns it off and eases a zoomed page back to 1x, and isolen_set_zoom_enabled(a, true) turns it back on. isolen_zoom_enabled reads the current state. The two are the live form of no_zoom, which they read and write, so the desc and the calls never disagree.

An element that keeps the pinch

A canvas, a map or a 3D model viewer wants the pinch for itself. Call ui::take_pinch(u) right after declaring it, the same way take_wheel keeps the wheel. A pinch that starts over it, or over anything inside it, does not zoom the page, and the element reads input::pinch as a scale step each frame. The model viewer does this.

CallDoes
void take_pinch(ctx* u)The element just declared keeps a pinch that starts over it.
bool pinch_taken_at(const ctx* u, float x, float y)True when a pinch starting at x y lands on an element, or inside one, that took it last frame. The shell asks this when a pinch begins.
bool fit_box_at(const ctx* u, float x, float y, float min_w, lay_box* out)The innermost element under x y last frame that is at least min_w wide. False when nothing that wide is there. This is what a smart zoom fits to.
void set_zoom(ctx* u, float zoom)Tells the context the page magnification. The shell calls it every frame.
float zoom_of(const ctx* u)That magnification, 1 when not zoomed.

A widget that renders its own pixels, such as an offscreen texture, scales its target by zoom_of(u) so it stays sharp when the page is zoomed. The model viewer renders at the zoom rounded up to a half step, and keeps its longest side within 4096 pixels.

plans.cpp
#include "isolenui/app/app.h"
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

#include <stdio.h>

// a floor plan that keeps the pinch for itself while the page around it zooms
struct plan {
    float scale = 1.0f;
};

static void plan_view(isolen_frame* f, void* user)
{
    plan* p = static_cast<plan*>(user);
    ui::ctx* u = f->ui;

    isolen_zoom_info z = {};
    isolen_zoom_get(f->app, &z);

    ui_box(u, ui::col().width(lay_pct(1.0f)).height(lay_grow(1.0f)).pad(16.0f).gap(12.0f))
    {
        char line[64];
        snprintf(line, sizeof(line), "page at %.2fx", double(f->zoom));
        ui::text(u, line, ui::body(u));
        if (z.zoom > 1.0f && !z.pinching && ui::button(u, "back to 1x")) {
            isolen_reset_zoom(f->app, true);
        }
        if (ui::button(u, "show the legend")) {
            // the content point x y lands on the top left of the page
            isolen_set_zoom(f->app, 2.0f, z.page[0], z.page[1] + 400.0f, true);
        }

        ui_box(u, ui::col().width(lay_pct(1.0f)).height(320.0f).bg("#202020").round(8.0f))
        {
            snprintf(line, sizeof(line), "plan at %.2fx", double(p->scale));
            ui::text(u, line, ui::body(u));
        }
        // a pinch that starts over the plan scales the plan, the page stays put
        ui::take_pinch(u);
        p->scale *= 1.0f + f->input->pinch;
    }
}

int run_plan(int argc, char** argv)
{
    static plan p;
    isolen_app_desc d = isolen_app_defaults();
    d.title = "plans";
    // three times at most, zero keeps the default of five
    d.max_zoom = 3.0f;
    d.view = plan_view;
    d.user = &p;
    return isolen_run(&d, argc, argv);
}

From code

CallDoes
void isolen_zoom_get(const isolen_app* a, isolen_zoom_info* out)Fills the current zoom.
void isolen_set_zoom(isolen_app* a, float zoom, float x, float y, bool animated)Zooms so the page point x y lands on the top left of the page. The zoom is clamped to 1 and the deepest zoom, and the point to the page. Animated eases there in 0.28 seconds, otherwise it jumps.
void isolen_reset_zoom(isolen_app* a, bool animated)Back to 1x.
void isolen_set_zoom_enabled(isolen_app* a, bool on)Turns the page zoom on or off while the app runs. Off also eases any zoom back to 1x. Setting the state it already has does nothing.
bool isolen_zoom_enabled(const isolen_app* a)True while the page zoom is on, false when no_zoom is set or it was switched off.
isolen_zoom_info fieldMeaning
zoomThe magnification, 1 when not zoomed.
x, yThe page point that sits on the top left of the page.
pageThe page box it magnifies, x y w h in logical units.
pinchingA pinch is zooming the page now. False while an element has the pinch.
animatingAn eased zoom, a smart zoom or a spring back is running.

Each frame also carries isolen_frame::zoom, the magnification that frame is drawn at.

Where the pinch comes from

  • macOS. Every trackpad has pinch and smart zoom.
  • Windows. A precision touchpad's pan and pinch come through Direct Manipulation, turned into the same smooth scroll and pinch steps a mac sends. If it cannot start, a touchpad pinch stays a Ctrl wheel, which steps the ui scale as before. There is no smart zoom on Windows.

For code that works with the platform window directly:

  • window::magnify is the pinch since the last frame as a scale step, cleared by the reader.
  • window::magnify_phase: bit 0 is set when a pinch began and bit 1 when it ended since the last frame. The shell also ends a pinch after 0.25 seconds with no steps.
  • window::smart_zoom is true when a two finger double tap asked for a smart zoom, cleared by the reader.
  • window_enable_gestures(w) turns on touchpad pan and pinch. The shell calls it when the window opens. On a mac it does nothing, since they are always on.

Level two and your own device

The shell draws the page with gfx_frame_draw_view and a gfx_view, the zoom, the origin and the page box as the clip. A level two pass that draws in page coordinates applies the same mapping itself: a page point p lands at (p - (x, y)) * zoom + (page[0], page[1]) from isolen_zoom_get, clipped to page. Set no_zoom when that is not worth it. Code that drives a device on its own can call gfx_frame_draw_view directly.

In the log

LineWhen
app pinch began at X Y, the page zoomsA pinch starts. It says the element under it takes it when an element kept it.
app pinch ended at Z, settling on ZThe fingers lift and the zoom springs to a legal value.
app smart zoom to Zx around X Y, app smart zoom back to 1x from ZA two finger double tap.
app page zoom on, app page zoom offisolen_set_zoom_enabled changed the state.
app zoom set to Zx at X Y animatedisolen_set_zoom or isolen_reset_zoom.
dmanip up on a WxH viewport, touchpad pan and pinch come through itWindows, when Direct Manipulation starts. A warning says when it failed.
The zoom is visual only. The layout stays at the window's size, so a zoomed page shows less of the same layout, not a reflowed one. Use the ui scale to make everything larger and lay it out again.

Last updated 23 October 2026