UXToolbar

UXToolbar is a row of toolbar items (icon-and-label buttons, fixed gaps, separators) laid out left to right. Two behaviours distinguish it from a row of buttons. Flexible spaces absorb the leftover width, to push a group right or centre one between two others. When the fixed items exceed the width, the trailing ones move into an overflow set, which a native toolbar shows under a chevron. The layout and hit test are pure geometry, unit-tested without a window.

On macOS it realizes as an NSToolbar, which is window chrome above the content area, so it has its own kind. On Win32 it realizes as a native toolbar control, on iOS as a UIToolbar, on Android as an android.widget.Toolbar, and on GEM, GTK and the web as the app-drawn row. An Android toolbar puts its actions at its end and moves those that do not fit under its own overflow menu, so the spaces in a UXToolbar have no effect there.

#use <UXKit>

Overview

UXToolbar* tb = new UXToolbar();
tb.addItem((u8*)"doc.new",  (u8*)"New",  1, 48);
tb.addItem((u8*)"doc.open", (u8*)"Open", 2, 48);
tb.setItemIcon(1, (u8*)"new");                       // each platform's own picture for it
tb.setItemIcon(2, (u8*)"open");
tb.addSeparator();
tb.addFlexibleSpace();
tb.addItem((u8*)"search",   (u8*)"Find", 9, 48);   // pushed to the right edge
tb.setAction(&controller.onTool);

void onTool(UXControl* sender) {
    UXToolbar* t = (UXToolbar* ?)sender;
    i32 tag = t.itemAt(t.selection()).tag;
    ...
}

Topics

Items · addItem · setItemIcon · setItemImage · addSpace · addFlexibleSpace · addSeparator · count Selection · selection Overflow · overflow Geometry · layout

addItem

void addItem(u8* ident, u8* label, i32 tag, i16 width)

A clickable item. ident identifies it (a native toolbar keys its items on it), label is the text, tag is yours to use, and width is its fixed extent. It shows its label alone until it is given an icon or an image.

setItemIcon

void setItemIcon(i32 tag, u8* name)

The icon of the item with this tag, by a UXIcon name such as "new", "delete" or "play". Each platform shows its own picture for the name: an SF Symbol on macOS and iOS, an Android system drawable, and UXKit’s own glyph on Windows, GTK, GEM and the web. A name the platform has no picture for shows the label alone. From 0.73.

setItemImage

void setItemImage(i32 tag, UXImage* img)

A picture of the app’s own for the item with this tag, shown in place of its icon on every platform. From 0.73.

addSpace

void addSpace(void)

A fixed gap.

addFlexibleSpace

void addFlexibleSpace(void)

A gap that absorbs an equal share of the leftover width. This one item type provides all of a toolbar’s layout control.

addSeparator

void addSeparator(void)

A thin rule between groups.

count

i32 count(void)

How many items there are, including spaces and separators.

selection

i32 selection(void)

The index of the last clicked item, or -1 before any click. A native toolbar’s click arrives by tag and is recorded here too, so reading it works the same on every backend.

overflow

i32 overflow(void)

How many trailing items did not fit at the last layout. The chevron menu shows these.

layout

void layout(i16 width)

Places every item: fixed widths first, then flexible spaces sharing the remainder, with trailing items marked invisible when the width runs out. Pure geometry; the tests call it without a window.

Platform appearance

The app-drawn fallback: bezeled items, separators, and a flexible space pushing the last group right.

A real UIToolbar. Each item is a UIBarButtonItem, and a flexible space is UIKit’s own.

A real android.widget.Toolbar. Its items are the toolbar’s actions, shown as room allows, with the rest under the platform’s overflow menu.

A native NSToolbar in the window chrome, with traffic lights, title, and icon-above-label items.