On this page

Pagers, carousels, tabs and tiles

Containers that show one page of several at a time. The pager is the base, and the carousel, the swiping tab view and the tile view are built on it.

Pager, pages that snap as you swipe or page, drawn by isolenPager, pages that snap as you swipe or page, drawn by isolen

They live in isolenui/kit/containers.h and come in through isolenui/kit/kit.h. See the component kit.

Pairing

Each container opens with a *_begin call that returns true when it opened. Only then declare its pages and call the matching *_end. A false return has already closed whatever it opened. It returns false when index is null, count is zero, the containers of one kind nest deeper than 8, or the tree dropped the box.

Inside, each page opens with a call that returns true only when that page is to be declared. The ui_page, ui_slide, ui_tab_pane and ui_tile block macros pair it with its end for you. A begin left open at the end of a frame is dropped with a warning.

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

struct tour {
    uint32_t page = 0u;
    uint32_t slide = 0u;
    uint32_t tab = 0u;
    uint32_t col = 0u;
    uint32_t row = 0u;
};

static const char* const tabs[] = { "general", "audio", "video" };

static void tour_view(ui::ctx* u, tour* t)
{
    // three onboarding pages, swipe or arrow keys, page follows the view
    if (ui::pager_begin(u, "intro", ui::col().height(240.0f), 3u, &t->page, ui::pager())) {
        for (uint32_t i = 0; i < 3u; ++i) {
            // only pages near the view are declared
            ui_page(u, i)
            {
                ui::textf(u, ui::head(u), "step %u", i + 1u);
            }
        }
        ui::pager_end(u);
    }

    // two slides a view, moving on every four seconds with arrows and dots
    const ui::carousel_spec c = ui::carousel().showing(2.0f).spaced(12.0f).plays(4.0f);
    if (ui::carousel_begin(u, "gallery", ui::col().height(200.0f), 8u, &t->slide, c)) {
        for (uint32_t i = 0; i < 8u; ++i) {
            ui_slide(u, i)
            {
                ui::textf(u, ui::body(u), "photo %u", i + 1u);
            }
        }
        ui::carousel_end(u);
    }

    // a tab bar on the left, only the chosen pane is declared
    if (ui::tab_view_begin(u, "settings", ui::col().grow(), tabs, 3u, &t->tab, ui::tabs_left)) {
        ui_tab_pane(u, 0u) { ui::text(u, "general settings"); }
        ui_tab_pane(u, 1u) { ui::text(u, "audio settings"); }
        ui_tab_pane(u, 2u) { ui::text(u, "video settings"); }
        ui::tab_view_end(u);
    }

    // a two by two grid of full view tiles
    if (ui::tile_view_begin(u, "board", ui::col().height(300.0f), 2u, 2u, &t->col, &t->row)) {
        for (uint32_t r = 0; r < 2u; ++r) {
            for (uint32_t c2 = 0; c2 < 2u; ++c2) {
                ui_tile(u, c2, r)
                {
                    ui::textf(u, ui::body(u), "tile %u %u", c2, r);
                }
            }
        }
        ui::tile_view_end(u);
    }
}

pager

pager_begin(u, label, style, count, &index, spec) lays pages across a view that snaps to them. index follows the view, and the view follows index: set it from your code and the pager scrolls there. On the first frame it jumps, and after that it eases. Pages open with pager_page(u, i), and pager_page_end closes one. pager_end closes the pager.

Only pages within one page of what is on screen are declared, so a pager over hundreds of pages costs the few near the view. Before the pager knows its size, on its first frame, only the page at index is declared and one more frame is asked for.

pager_spec fieldChainDefaultMeaning
colsacross(n)0Pages to a row. Zero, or a count at least count, puts every page in one row. One stacks them in a column. Anything else makes a grid.
per_viewshowing(pages)1Pages visible at once in a row or a column. At least 1. A grid always shows one.
gapspaced(px)0Space between pages in a row or a column.
swipeswipes(on)trueA drag moves the pages.
looploops(on)falseArrow keys wrap from the last page to the first.
keyskeyed(on)trueThe pager joins the tab order and takes its keys.

ui::pager() returns the defaults: one row, one page a view, swipe and keys on.

  • Swipe. A drag past 5 units moves the pages under the pointer. On release it carries on by its speed and lands on a page, at most one view of pages from where it was let go.
  • Wheel. A notch moves one page. Notches in quick succession count from the page it is already heading to, and a notch during a swipe takes over its speed.
  • Trackpad. The pages follow the fingers one to one, a logical pixel per point, each axis on its own, so a grid moves on a diagonal and a row leaves the other axis to the views around it. index follows the page it would rest on while the fingers are still down, and it only changes once that lands well past half a page from the last, so a wobbly speed does not flicker it.
  • Letting go. The first frame a trackpad event is due and missing, the view springs to the page nearest to where its speed would carry it. The operating system already coasts a flick, so the spring adds only its own short reach. The snap is the fast spring the roller uses: critically damped with a 0.2 second response, resting within a quarter pixel. There is no idle timer to wait out, and the spring is solved exactly, so it lands the same at any frame rate. A wheel notch lands on the same spring, while an animated scroll_to eases.
  • Slow events. When the trackpad sends events less often than frames are drawn, the view coasts at most one event ahead between them, so it moves smoothly without running off. An event within about twice the recent gap, and never less than 50 ms, carries on the same swipe even if the spring has started. A later one starts a new swipe from where the spring has the view, so it never jumps back.
  • Keys. With focus, Left and Right move a page in a row, Up and Down in a column, and all four in a grid. Home and End go to the first and last page, or to the ends of the row in a grid.

carousel_begin(u, label, style, count, &index, spec) is a pager with previous and next arrows over it and a row of dots under it. Slides open with slide and slide_end, or ui_slide, and carousel_end draws the arrows and dots and closes it.

carousel_spec fieldChainDefaultMeaning
per_viewshowing(slides)1Slides visible at once.
gapspaced(px)0Space between slides.
autoplayplays(seconds)0Seconds a slide stays before moving on. Zero never moves on its own.
looploops(on)falseThe arrows and keys wrap round.
arrowsarrowed(on)truePrevious and next buttons over the ends.
dotsdotted(on)trueOne dot per place the view can start, up to 32. The current one is a pill 2.2 dots long with fully round ends.
  • Autoplay moves one slide on and goes back to the first after the last. It rests while the pointer is over the carousel or a button is held, and the timer restarts whenever the slide changes. It wakes the app with redraw_after, so an idle app still moves on time.
  • Without loop an arrow at its end is disabled. The arrows are tab stops that take Enter and Space, and each has a tooltip.
  • When the slide changes, the pill eases from the old dot to the new one, the old one shrinking as the new one grows, so the row keeps its width and nothing shifts. Each dot's box grows with it, so the pill never touches a clip at its ends.
  • A click on a dot goes to that slide. More than one slide is needed for arrows, dots or autoplay.

kit.conf: carousel needs pager.

tab view

tab_view_begin(u, label, style, items, count, &index, at, swipe) is a tab bar with one pane per tab. Panes open with tab_pane and tab_pane_end, or ui_tab_pane, and tab_view_end closes it. Without swipe, only the chosen pane is declared.

tab_bar_atBar
tabs_top (default)A tabs strip above the panes.
tabs_bottomThe same strip below them.
tabs_left, tabs_rightA tabs_vertical column as wide as the widest label, before or after the panes.

With swipe the panes lie on a pager, so a drag or a wheel moves between them and the tab follows. The pager's own keys are off there, since the tab strip already takes the arrows. See buttons and choices for tabs.

kit.conf: tab_view needs pager tabs.

tile view

tile_view_begin(u, label, style, cols, rows, &col, &row) is a grid of full view tiles shown one at a time, a pager with cols pages to a row. tile(u, col, row) and tile_end, or ui_tile, declare a tile. The arrow keys, a swipe or the wheel move one tile in any direction, and col and row follow. Out of range values are clamped.

kit.conf: tile_view needs pager.

Right to left

In a right to left box, rows of pages run from the right, a swipe reads the pointer along the reading direction, and Left and Right swap so Right goes back. The carousel's arrows swap sides and point the other way, and a tabs_left bar sits at the start of the row, which is the right. See direction and bidi.

A pager is a view that snaps, so what overflow and views says about snap and scroll_to applies. Its own bars are hidden. The trackpad rules above belong to any view that snaps, and while the fingers are down scroll_of gives the step it is heading to as to_x or to_y.

Last updated 6 October 2026