On this page

Direction and bidi

Boxes can read right to left and mirror their inline axis. The text layer adds UAX 9 bidi, Arabic joining and a fallback atlas for Hebrew, Arabic and Latin 1, all through direction aware forms of the draw calls.

Direction, right to left layout and text, drawn by isolenDirection, right to left layout and text, drawn by isolen

Direction in the ui

ui::dir is dir_inherit, dir_ltr or dir_rtl. Inherit follows the parent, and at the root it reads as left to right. The root direction comes from theme.direction. ui::direction(u, d) sets it over the theme from then on, and passing dir_inherit hands it back to the theme.

CallWhat it does
style::rtl(), style::ltr()Fix this box and everything inside it to one direction.
style::pad_inline(start, end)Start and end padding. They are left and right until the box reads right to left, and add to any physical pad.
ui::dir_of(u)What an element declared now resolves to, always dir_ltr or dir_rtl.

What mirrors

  • Flex rows and grids are placed left to right, then their children are turned about the content box so the left edge lands on the right. Wrapped columns mirror the same way. See flexbox.
  • The vertical scroll bar and its corner move to the left edge. A horizontal bar keeps its track against the right.
  • A horizontal scroll offset grows toward the left, so zero shows the start. The thumb, bar drags and the wheel all follow. lay_scroll_info::mirrored says so for a node. See overflow and views.
  • Virtual lists put their scroll bar gutter on the left when the bar is not an overlay.
  • Kit tabs, segmented rows and sidebar items lay out from the right, and the arrow keys follow the reading direction.
  • A portal takes the direction it was declared in, even though it lays out under the root.
  • An anchor at side_start or side_end resolves to left or right by the overlay's direction. Along a top or bottom edge, start and end alignment swap and the slide runs the inline way. See portals and popovers.

Paint runs after the frame, so a canvas or a widget that draws a side of its own reads dir_of while it is declaring and keeps the answer in its payload.

direction.cpp
#include "isolenui/app/app.h"
#include "isolenui/kit/kit.h"

// a marker the canvas draws on the start side, read while declaring
struct marker {
    ui::dir dir;
};

static void paint_marker(gfx_list* l, lay_box box, void* user)
{
    const marker* m = static_cast<const marker*>(user);
    const float x = m->dir == ui::dir_rtl ? box.x + box.w - 4.0f : box.x;
    gfx_fill(l, x, box.y, 4.0f, box.h, 0xffe0a060u);
}

static void view(isolen_frame* f, void* user)
{
    (void)user;
    ui::ctx* u = f->ui;
    static bool menu = false;
    static marker m[2];

    // the whole tree reads right to left from here on
    ui::direction(u, ui::dir_rtl);

    ui_box(u, ui::col().grow().pad(24.0f).gap(12.0f))
    {
        // start padding lands on the right in a right to left box
        ui_box(u, ui::row().gap(8.0f).pad_inline(16.0f, 4.0f))
        {
            m[0].dir = ui::dir_of(u);
            ui::canvas(u, ui::style().width(4.0f).height(20.0f), paint_marker, &m[0]);
            if (ui::button(u, "open")) {
                menu = !menu;
            }
            const uint64_t trigger = ui::last_id(u);
            if (menu) {
                // start means right here, below the trigger
                ui_popover(u, ui::col().pad(8.0f).bg(ui::theme_of(u)->menu),
                           ui::anchor(trigger).on(ui::side_bottom, lay_align_start))
                {
                    ui::text(u, "item");
                }
            }
        }

        // one subtree back to left to right inside it
        ui_box(u, ui::row().gap(8.0f).ltr())
        {
            m[1].dir = ui::dir_of(u);
            ui::canvas(u, ui::style().width(4.0f).height(20.0f), paint_marker, &m[1]);
            ui::text(u, "left to right");
        }
    }
}

int main(int argc, char** argv)
{
    isolen_app_desc d = isolen_app_defaults();
    d.title = "direction";
    d.view = view;
    return isolen_run(&d, argc, argv);
}

A ui::text element takes the direction of its box. Once its bytes are in, the core asks text_font_plain once, and a run that is not plain is measured, wrapped and painted with the direction aware calls below. So Hebrew and Arabic in ui::text are reordered and shaped, and text_font_start and text_font_end follow the box. Text fields run on the edit core, which walks bidi lines in visual order. See text editing and IME.

Labels the kit paints itself, such as button, tab and checkbox labels, still draw through the plain calls. A Hebrew or Arabic label there is not reordered or shaped yet, and start and end read as left and right.

The layout side

lay_direction is lay_direction_inherit, lay_direction_ltr or lay_direction_rtl. Inherit is zero, so every style made before direction existed follows its parent. lay_style::direction holds it, and ltr(), rtl() and pad_inline(start, end) set it and the pad_s and pad_e fields. lay_root_direction(c, d) sets what inherit means at the root, after lay_begin and before any open. lay_rtl(c, node) reads a node's resolved direction.

Direction aware text

text_dir is text_dir_ltr, text_dir_rtl or text_dir_auto, where the first strong letter decides and no strong letter means left to right. The _dir forms take one and otherwise match the plain calls on fonts and drawing.

CallWhat it does
text_font_plainTrue when the plain walk already draws the run right: ASCII, left to right text with nothing at or past U+0590 that reorders, and no glyph the fallback would stand in for. Right to left is never plain.
text_font_measure_dirThe width in visual order, fallback glyphs included.
text_font_draw_in_dirReorders, shapes and draws one line aligned in a width.
text_font_draw_fit_dirThe same, cut with a mark when it does not fit. The cut is logical, so the mark lands at the paragraph end, which is the left edge of a right to left one.
text_font_wrap_dirBreaks stay logical as UAX 9 wants, and each candidate line is priced in visual order.
text_font_min_width_dirThe widest unbreakable piece, priced the same way.
text_font_draw_line_dirOne wrapped line of a paragraph. The paragraph is resolved once and kept while its pointer, length, bytes and direction stay the same.

Every one of them checks text_font_plain first and takes the plain path when it can, so Latin text pays for a byte scan and nothing more. text_font_start and text_font_end resolve against the paragraph level in these calls. The plain calls read them as left and right.

bidi_text.cpp
#include "isolenui/gfx/gfx.h"
#include "isolenui/text/text_font.h"
#include "isolenui/text/text_shape.h"

// a font you own with the fallback atlas behind it for hebrew and arabic
struct fonts {
    text_font main;
    text_font fallback;
    gfx_font main_h;
};

static bool fonts_open(fonts* t, gfx_device* dev)
{
    if (!text_font_load(&t->main, "assets/objectivity.atlas")) {
        return false;
    }
    t->main_h = gfx_font_bind(dev, &t->main);
    // missing glyphs are measured from here and drawn with its handle
    if (text_font_load(&t->fallback, "assets/fallback.atlas")) {
        t->main.fallback = &t->fallback;
        t->main.fallback_handle = gfx_font_bind(dev, &t->fallback);
    }
    return t->main_h != GFX_NONE;
}

// one line, reordered, shaped and aligned to its start side
static float draw_title(const fonts* t, gfx_list* out, const char* utf8, float x, float width,
                        float baseline)
{
    return text_font_draw_fit_dir(&t->main, out, t->main_h, 0u, utf8, TEXT_FONT_TERMINATED, x,
                                  width, baseline, 18.0f, 0.0f, 0xffe6e6e6u, text_font_start,
                                  text_dir_auto);
}

// breaks stay logical, each line is drawn in visual order off one analysis
static void draw_paragraph(const fonts* t, gfx_list* out, const char* utf8, uint32_t len, float x,
                           float y, float width)
{
    const float px = 16.0f;
    text_line lines[32];
    const uint32_t n = text_font_wrap_dir(&t->main, 0u, utf8, len, px, 0.0f, width, lines, 32u,
                                          text_dir_rtl);
    const float step = text_font_line_height(&t->main, px);
    float base = y + text_font_ascent(&t->main, px);
    for (uint32_t i = 0; i < n && i < 32u; ++i) {
        text_font_draw_line_dir(&t->main, out, t->main_h, 0u, utf8, len, lines[i].start,
                                lines[i].len, x, width, base, px, 0.0f, 0xffe6e6e6u,
                                text_font_start, text_dir_rtl);
        base += step;
    }
}

// shaping can be switched off at run time, arabic then draws unjoined
static void set_shaping(bool on)
{
    text_shape_enable(on);
}

Bidi

isolenui/text/text_bidi.h is the Unicode bidirectional algorithm, UAX 9, on tables that tools/bidi/gen.d generates from the Unicode data files (18.0.0 at this version). All scratch is one block per thread, made on first use.

  • text_bidi_needed is the quick test. Right to left always needs it. Left to right text is scanned for lead bytes at or past U+0590.
  • text_bidi_analyse resolves one UTF-8 paragraph into a text_bidi_para of code points, byte offsets, classes and levels. It stays valid until the next call on the thread, and serial moves on with every analysis.
  • text_bidi_runs gives the visual runs of a byte range, left to right on screen. A right to left run is drawn from its end. text_bidi_index maps a byte to its code point.
  • text_bidi_levels and text_bidi_reorder are the same steps over code points, for code that holds its own. text_bidi_class_of and text_bidi_mirror read the tables.
  • One pass resolves up to TEXT_BIDI_MAX (8192) code points. The rest of a longer paragraph stays in logical order at the paragraph level, and covered says where that starts.

Arabic shaping

isolenui/text/text_shape.h joins Arabic letters by turning them into their Presentation Forms B, which the fallback atlas carries. A lam followed by an alef becomes one lam alef ligature. The direction aware calls run it on every paragraph that has Arabic in it. There is no general shaping engine: scripts other than Arabic are left alone.

The fallback atlas

text_font::fallback and fallback_handle name a second atlas. A glyph the main atlas lacks is measured from it and drawn with its handle, and a pair is only kerned when both glyphs come from the same atlas. A face past the fallback's face count, or one that lacks the glyph, reads the fallback's first face.

assets/fallback.atlas is baked by tools/atlas/fallback.sh from the characters in tools/atlas/fallback.chars: Latin 1 from the faces the main atlas uses, plus Noto Sans Hebrew and Noto Sans Arabic with the presentation forms the shaper picks. It has regular, bold and mono faces in one 2048 by 1024 page.

The build copies it beside every app, and the app shell loads it at open, binds it to the device and points its font at it, unless isolen_app_desc::no_fallback is set. It logs whether the fallback and shaping are on. If the file will not load or bind, it logs a warning and runs without it. Code that owns its own text_font wires it by hand, as in the example above. Only the _dir calls measure and draw fallback glyphs. The plain calls skip them, so a plain measure always matches the plain draw, and text_font_plain sends any run that needs the fallback down the _dir path. With no fallback, the first glyph the atlas lacks logs one warning.

Turning it off

SwitchKindEffect
ISOLEN_TEXT_SHAPINGCMake option, on by defaultOff leaves text_shape.cpp and its tables out of every binary. The shaping calls become inline stubs, and Arabic draws as unjoined letters.
ISOLEN_TEXT_FALLBACKCMake option, on by defaultOff stops the build copying assets/fallback.atlas beside every app, and the app shell never loads one.
isolen_app_desc::no_fallbackRuntime, off by defaultThe app shell skips loading the fallback atlas.
isolen_app_desc::no_shapingRuntime, off by defaultThe app shell calls text_shape_enable(false) at open, so Arabic stays unjoined.
text_shape_enable(bool)Runtime, on at startTurns the joining pass off or on for every thread. text_shape_enabled reads it.
text_font::fallback = nullptrRuntimeWith no fallback, glyphs the main atlas lacks are skipped, so Hebrew and Arabic letters the main atlas does not carry draw as nothing.

Both options reach the code as the compile definitions ISOLEN_TEXT_SHAPING and ISOLEN_TEXT_FALLBACK, set to 0 or 1, and configure prints both. Bidi itself has no switch: text with nothing to reorder never reaches it.

Last updated 6 October 2026