Overlay Widgets

Ui.Overlay.setText/setPanel are the quick form. For buttons, draggable panels, images, progress rings or charts, create a widget and keep its handle. Every setter returns the widget, so calls chain.

var hp = Ui.Overlay.text("hp")
    .setText("HP: 100%")
    .at(40, "10%")            // px number, "24dp", "10%"
    .anchor("top-left")
    .textStyle({ size: 18, color: Color.green(), weight: 700, family: "mono" })
    .background(Color.fromHex("#CC101317"))
    .corner("12dp")
    .padding(["8dp", "14dp"])
    .show();

hp.setText("HP: 42%").setTextColor(Color.red());   // update in place

Constructors

Each takes an optional id (auto-generated if omitted) and an optional property object. Passing the same id again returns a handle to the existing widget.

Keep the handle a constructor returns. Ui.Overlay.get(id) is slower because it checks that the id exists, so avoid it inside loops. For a widget you know exists, Ui.Overlay.ref(id) returns a handle without the check.

Constructor	Renders
`Ui.Overlay.text(id?, props?)`	A text label.
`Ui.Overlay.panel(id?, props?)`	A filled box.
`Ui.Overlay.image(id?, props?)`	An image from your saved templates, a file path, or base64.
`Ui.Overlay.button(id?, props?)`	A tappable label; clickable by default.
`Ui.Overlay.progress(id?, props?)`	A progress bar, horizontal or vertical.
`Ui.Overlay.gauge(id?, props?)`	An arc gauge.
`Ui.Overlay.sparkline(id?, props?)`	An auto-scaled line chart over a rolling sample window.
`Ui.Overlay.group(id?, props?)`	A container; children call `.parent(groupId)` and position relative to it.

Units and placement

A plain number is pixels. Strings carry a unit: "24dp" scales with screen density, "25%" is a fraction of the parent, "auto" sizes to content.

.anchor() accepts top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right; the x/y you set become offsets from that anchor. .safeArea(true) keeps the widget clear of the notch and navigation bar.

For layouts that look the same on every device, use dp, % or anchors. To keep pixel coordinates but scale them like the rest of your macro, call Ui.Overlay.setCoordinateMode("scaled") once at the top of your script. The default is "raw".

Setters

`.set({ ... })`

Change several properties in one call. Faster than chained setters inside an update loop.

let result = .set('demo');
console.log(result);

`.at(x, y)`

Position.

let result = .at(500, 1200);
console.log(result);

`.setX(x)`

Position.

.setX(500);

`.setY(y)`

Position.

.setY(1200);

`.size(w, h)`

Size; "auto" wraps content.

let result = .size(300, 120);
console.log(result);

`.setW(w)`

Size; "auto" wraps content.

.setW(300);

`.setH(h)`

Size; "auto" wraps content.

.setH(120);

`.anchor(a)`

Placement. padding/margin take one value, [vertical, horizontal], or [l, t, r, b].

let result = .anchor(255);
console.log(result);

`.padding(v)`

Placement. padding/margin take one value, [vertical, horizontal], or [l, t, r, b].

let result = .padding('demo');
console.log(result);

`.margin(v)`

Placement. padding/margin take one value, [vertical, horizontal], or [l, t, r, b].

let result = .margin('demo');
console.log(result);

`.safeArea(b)`

Placement. padding/margin take one value, [vertical, horizontal], or [l, t, r, b].

let result = .safeArea(255);
console.log(result);

`.parent(groupId)`

Grouping and stacking order.

let result = .parent('demo');
console.log(result);

`.z(index)`

Grouping and stacking order.

let result = .z('demo');
console.log(result);

`.background(color)`

Fill. Image backgrounds stretch to the widget box.

.background(Color.fromHex('#00FF88'));

`.gradient([c1, c2], angle?)`

Fill. Image backgrounds stretch to the widget box.

let result = .gradient('demo', 'demo', 'demo');
console.log(result);

`.setBackgroundImage(name)`

Fill. Image backgrounds stretch to the widget box.

.setBackgroundImage('demo');

`.setImage(name)`

Image widgets. setImage swaps the picture, scaleMode is fit, fill, stretch or center, and tint recolours it, which is how one white icon becomes a green one and a red one.

.setImage('demo');

`.scaleMode(mode)`

Image widgets. setImage swaps the picture, scaleMode is fit, fill, stretch or center, and tint recolours it, which is how one white icon becomes a green one and a red one.

let result = .scaleMode('safe');
console.log(result);

`.tint(color)`

Image widgets. setImage swaps the picture, scaleMode is fit, fill, stretch or center, and tint recolours it, which is how one white icon becomes a green one and a red one.

let result = .tint(Color.fromHex('#00FF88'));
console.log(result);

`.corner(r)`

Decoration. .corner() also takes [tl, tr, br, bl]. On a text widget the shadow falls on the glyphs; on any box (panel, group, button, image) it is a drop shadow. .shadow(false) removes it.

let result = .corner(255);
console.log(result);

`.border(width, color)`

let result = .border('demo', Color.fromHex('#00FF88'));
console.log(result);

`.shadow(radius, dx, dy, color)`

let result = .shadow('demo', 'demo', 'demo', Color.fromHex('#00FF88'));
console.log(result);

`.opacity(0..1)`

Compositing. Widgets are fully opaque by default; set opacity, or an alpha in the colour (#CC101317), when you want to see through them.

let result = .opacity('demo');
console.log(result);

`.rotation(deg)`

Compositing. Widgets are fully opaque by default; set opacity, or an alpha in the colour (#CC101317), when you want to see through them.

let result = .rotation('demo');
console.log(result);

`.elevation(px)`

Compositing. Widgets are fully opaque by default; set opacity, or an alpha in the colour (#CC101317), when you want to see through them.

let result = .elevation('demo');
console.log(result);

`.setTextColor(c)`

Text. family is system, mono, serif or condensed.

.setTextColor('demo');

`.setTextSize(sp)`

Text. family is system, mono, serif or condensed.

.setTextSize('demo');

`.font(family)`

Text. family is system, mono, serif or condensed.

let result = .font('demo');
console.log(result);

`.bold(b)`

Text. family is system, mono, serif or condensed.

let result = .bold(255);
console.log(result);

`.italic(b)`

Text. family is system, mono, serif or condensed.

let result = .italic(255);
console.log(result);

`.align(a)`

Text. family is system, mono, serif or condensed.

let result = .align(255);
console.log(result);

`.maxLines(n, ellipsize?)`

Text. family is system, mono, serif or condensed.

let result = .maxLines('demo', 'demo');
console.log(result);

`.html(text)`

Rich text. HTML is sanitised to a safe tag subset; markdown supports **bold**, *italic*, __underline__ and backtick code. .plain() sets the text and turns rich formatting back off, so markup arriving from a variable is shown literally instead of being parsed.

let result = .html('Daily Reward Ready');
console.log(result);

`.markdown(text)`

let result = .markdown('Daily Reward Ready');
console.log(result);