On this page

Ranges, arcs and scales

Value controls from isolenui/kit/inputs.h beyond the plain slider: two thumb and upright sliders, a circular arc slider, text set along a ring, and scales with ticks and labels.

Slider, picks a value along a track, drawn by isolenSlider, picks a value along a track, drawn by isolen
mixer.cpp
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

struct mixer {
    float low = 200.0f;
    float high = 4000.0f;
    float fader = 0.8f;
    float gain = 40.0f;
};

static void panel(ui::ctx* u, mixer* m)
{
    // two thumbs, the low one never passes the high
    ui::slider_range(u, "band", &m->low, &m->high, 20.0f, 20000.0f, "%.0f Hz");

    ui_box(u, ui::row().height(220.0f).gap(24.0f))
    {
        // a rail standing up, zero height grows to fill
        ui::slider_vertical(u, "fader", &m->fader, 0.0f, 1.0f, "%.2f");

        // a round scale behind a knob, both sweep 270 degrees from 135
        ui_box(u, ui::stack().width(160.0f).height(160.0f).centre())
        {
            ui::scale(u, ui::scale_of(ui::scale_round_out).nice(6u, 5u).format("%.0f"),
                      ui::row().width(lay_pct(1.0f)).height(lay_pct(1.0f)));
            ui::arc(u, "gain", &m->gain, 0.0f, 100.0f,
                    ui::arc_of().sized(120.0f).shows("%.0f").as(ui::arc_symmetric));
        }
    }

    // a straight axis with a red section at the top end
    static const ui::scale_section hot[] = { { 80.0f, 100.0f, 0xff3a3ae0u, 3.0f } };
    ui::scale(u, ui::scale_of().split(hot, 1u), ui::row().width(lay_grow(1.0f)).height(28.0f));

    // text laid along a ring, centred at the top
    ui::arc_label(u, "input level", ui::arc_label_of(270.0f), ui::row().width(160.0f).height(160.0f));
}

Range and vertical sliders

slider_range(u, label, &low, &high, lo, hi, fmt) puts two thumbs on one rail, and each thumb is its own tab stop. The low thumb never passes the high one, and values that arrive the wrong way round are swapped. A press on the rail grabs the nearer thumb. The readout prints both values with fmt, joined by a hyphen.

slider_vertical(u, label, &value, lo, hi, fmt, height) stands the rail up, with the label above and the readout below. A height of zero grows to fill, and the rail never goes below 44 units.

Both take their keys like slider: the arrows step a hundredth of the range and shift or the page keys a tenth, and home and end jump to the ends. On the vertical slider, up and page up raise it. Both return true when a value changed. See numeric input.

Arcs

arc(u, label, &value, lo, hi, spec) is a circular slider. A press within 8 units of the ring grabs it and drags along it, and the ends hold when the pointer crosses the gap. With focus it takes the same keys as the sliders. It returns true when the value changed. arc_of() starts it at 135 degrees with a 270 degree sweep, an 8 unit ring and a knob:

MethodFieldDefault and effect
from(start, sweep)angle, sweepDegrees. Zero points right, and angles turn clockwise.
thick(w)widthThe ring width, 8.
sized(d)sizeThe diameter. Zero takes five theme rows.
steps(s)stepWhat a key moves, and a drag snaps to it. Zero moves a hundredth of the range.
as(m)modeThe indicator grows from the start with arc_normal, from the end with arc_reverse, or out from the middle with arc_symmetric.
shows(fmt)fmtPrints the value in the middle. Null prints nothing.
bare()knobDrops the knob.

For your own canvas, arc_draw(l, box, spec, t, theme, shade) paints the ring with the indicator at t out of one, and arc_t_at(spec, box, x, y, was) turns a point into that fraction. The ring is curves and the knob a rect, and a layer draws its rects under its curves, so arc_draw puts the knob one layer above the list's current one and restores it after. Leave that layer free if you draw over an arc.

Arc labels

arc_label(u, text, spec, box) sets text along a circle centred in the box. Each glyph sits on the circle turned along it, kerned and advanced along the arc, so the text reads like type set on a curve. arc_label_of(angle) anchors the text at that angle, centred.

FieldEffect
angleWhere the text is anchored, in degrees clockwise from pointing right.
radiusThe circle the text meets. Zero fits the text inside the box.
px, colorZero takes the theme text size and colour.
alignarc_text_start, arc_text_centre or arc_text_end puts that part of the text on angle. Start and end follow the paragraph direction, so right to left text starts from the other side.
reverseRuns counter clockwise with the tops of the glyphs toward the centre, what text along the bottom of a ring wants.
insideThe text sits within the circle rather than around it.

arc_label_draw(l, box, text, spec, f, fh, face) is the canvas half. It lays the line with text_font_lay_dir and turns each glyph with gfx_glyph_turn, see laying a line to bend. It keeps the first 256 glyphs and logs a warning past that. Fallback glyphs draw from the fallback atlas like any other text.

Scales

scale(u, spec, box) draws an axis, with a line, minor and major ticks and labels on the majors. It is display only and takes no focus. The scale_mode is scale_bottom, scale_top, scale_left or scale_right for a straight line, or scale_round_in or scale_round_out for a ring with ticks inside or outside it. scale_of(mode) gives 0 to 100 in 21 ticks with a labelled major every 5, 5 and 9 unit ticks, a 1 unit line, and a round sweep of 270 degrees from 135, the same as arc_of.

MethodEffect
range(a, b)The values at the two ends. A reversed range counts down.
every(count, major)Exactly count ticks including both ends, with every majorth one labelled.
nice(most, split)Majors on 1, 2 and 5 steps from chart_ticks, aiming for at most most of them (6 when zero), each split into split minors.
arc(start, sweep), lengths(minor, major)The ring and the tick lengths.
format(fmt), named(texts, n)A printf format for labels, or one text per major tick. With neither, nice scales print just enough decimals and fixed ones use %g.
split(sections, n)Ranges of the line drawn in their own colour and width, such as a red zone.
bare()Ticks only, with no line and no labels.

Zero tick_color, label_color and label_px take the theme. The scale copies its sections, texts and format for the frame, so they need not outlive the call. scale_draw and scale_point are the canvas half, and scale_point gives the position and tick normal of a value, for a needle.

The rails, arcs and scales paint in physical coordinates. They do not mirror in a right to left box at this version. See direction and bidi.

kit.conf

scale needs chart, since its nice ticks come from chart_ticks. Switching chart off takes scale off too. The sliders and arcs need no line. See the component kit and charts.

Last updated 6 October 2026