Ui

Draws the widgets of a plugin’s panel or dialog, the same widgets Modlumi’s own panels use. Value widgets take the current value and return it, or the user’s change of it:

state.width = ui.length("Width", state.width, { min: 0.1 });
if (ui.button("Build", { primary: true })) build(state);

Consecutive fields line up in a form, labels on the left. A widget is identified by its label within the sections, tabs and columns around it, so keep labels stable or pass an id. Repeated labels are told apart by their order.

Methods

angle()

angle(label, radians, options?): number

An angle in radians, shown and typed in degrees.

Parameters

label

string

radians

number

options?

NumberOptions

Returns

number

---

button()

button(label, options?): boolean

Returns true in the draw that reports the click. That draw may edit the model, so call Model.operation right there.

Parameters

label

string

options?

WidgetOptions & object

Returns

boolean

---

canvas()

canvas(label, height, draw, options?): CanvasEvent | null

A canvas height pixels high that fills the window’s width. draw adds its shapes and receives what the user did with the mouse on it, or null, so it can show the effect right away; canvas returns the same event. The draw that reports an event may edit the model, like a clicked button’s.

ui.canvas("Nodes", 200, (canvas, event) => {
  if (event?.type === "drag" && event.item === "node") {
    node.x += event.dx;
    node.y += event.dy;
  }
  canvas.rect(node.x, node.y, 80, 40, { id: "node", fill: { r: 0.2, g: 0.3, b: 0.5, a: 1 } });
});

Parameters

label

string

height

number

draw

(canvas, event) => void

options?

WidgetOptions

Returns

CanvasEvent | null

---

checkbox()

checkbox(label, value, options?): boolean

Parameters

label

string

value

boolean

options?

WidgetOptions

Returns

boolean

---

close()

close(): void

Closes this panel or dialog.

Returns

void

---

color()

color(label, value, options?): Color

Parameters

label

string

value

Color

options?

WidgetOptions & object

Returns

Color

---

columns()

columns(draws, options?): void

Equal-width columns, one per function.

Parameters

draws

readonly () => void[]

options?

WidgetOptions

Returns

void

---

disabled()

disabled(when, draw): void

Grays out the widgets draw adds while when is true.

Parameters

when

boolean

draw

() => void

Returns

void

---

dropdown()

dropdown<T>(label, value, choices, options?): T

Chooses one of many options from a list; returns the chosen one.

Type Parameters

T

T extends string

Parameters

label

string

value

T

choices

readonly T[]

options?

WidgetOptions

Returns

T

---

form()

form<T>(values, schema): T

Draws one field per entry of schema, identified by its key, and returns a copy of values with the user’s changes.

state = ui.form(state, {
  width: { type: "length", label: "Width", min: 0.1 },
  shape: { type: "dropdown", label: "Shape", choices: ["Straight", "L-shaped"] },
});

Type Parameters

T

T extends Record<string, unknown>

Parameters

values

T

schema

Readonly<Record<string, FormField>>

Returns

T

---

heading()

heading(text, options?): void

Parameters

text

unknown

options?

WidgetOptions

Returns

void

---

image()

image(image, options?): void

Shows an image the plugin loaded, at its own size in pixels, or at a width or height that keeps its proportions when only one is given.

Parameters

image

PluginImage

options?

WidgetOptions & object

Returns

void

---

integer()

integer(label, value, options?): number

Parameters

label

string

value

number

options?

RangeOptions

Returns

number

---

length()

length(label, meters, options?): number

A length in meters, shown in the model’s units. It accepts everything the measurements box accepts, such as 1.2m, 18cm, 7" or 5' 3 1/2".

Parameters

label

string

meters

number

options?

RangeOptions

Returns

number

---

material()

material(label, value, options?): Material | null

Chooses one of the model’s materials, shown with their colors, or null for the default material. Assign the result inside Model.operation in the draw that reports it.

Parameters

label

string

value

Material | null

options?

WidgetOptions

Returns

Material | null

---

number()

number(label, value, options?): number

A decimal number; typed text outside the range is refused.

Parameters

label

string

value

number

options?

NumberOptions

Returns

number

---

progress()

progress(fraction, options?): void

Parameters

fraction

number

options?

WidgetOptions & object

Returns

void

---

radio()

radio<T>(label, value, choices, options?): T

Chooses one of a few options shown side by side; returns the chosen one.

Type Parameters

T

T extends string

Parameters

label

string

value

T

choices

readonly T[]

options?

WidgetOptions

Returns

T

---

readOnly()

readOnly(label, value, options?): void

A labeled value that can’t be edited.

Parameters

label

string

value

unknown

options?

WidgetOptions

Returns

void

---

row()

row(draw, options?): void

Places the widgets draw adds side by side, such as a row of buttons.

Parameters

draw

() => void

options?

WidgetOptions

Returns

void

---

section()

section(title, draw, options?): void

A heading that folds the widgets draw adds; open by default.

Parameters

title

string

draw

() => void

options?

WidgetOptions & object

Returns

void

---

separator()

separator(title?, options?): void

A horizontal rule, with an optional title set into it.

Parameters

title?

string

options?

WidgetOptions

Returns

void

---

slider()

slider(label, value, options?): number

Drag to change; Ctrl+click to type a value.

Parameters

label

string

value

number

options?

SliderOptions

Returns

number

---

spacing()

spacing(): void

Vertical space between groups of widgets.

Returns

void

---

table()

Call Signature

table(label, columns, rows, selection, options?): string | null

A table whose columns sort when the user clicks their header; cells that start with a number, such as "1.2 m", sort by it. Pass the selected row’s id, or null, and get the user’s new choice back. Pass an array of ids instead to let Ctrl+click and Shift+click select several rows; the result is then an array too.

Parameters

label

string

columns

readonly TableColumn[]

rows

readonly TableRow[]

selection

string | null

options?

TableOptions

Returns

string | null

Call Signature

table(label, columns, rows, selection, options?): string[]

Parameters

label

string

columns

readonly TableColumn[]

rows

readonly TableRow[]

selection

readonly string[]

options?

TableOptions

Returns

string[]

---

tabs()

tabs(pages, options?): void

Tabs, from each tab’s title to the function that draws it.

Parameters

pages

Readonly<Record<string, () => void>>

options?

WidgetOptions

Returns

void

---

text()

text(text, options?): void

Wrapped text, optionally in a tone.

Parameters

text

unknown

options?

WidgetOptions & object

Returns

void

---

textBox()

textBox(label, value, options?): string

Multi-line text that wraps; 4 visible lines by default.

Parameters

label

string

value

string

options?

WidgetOptions & object

Returns

string

---

textField()

textField(label, value, options?): string

Parameters

label

string

value

string

options?

WidgetOptions & object

Returns

string

---

toggle()

toggle(label, value, options?): boolean

An on/off switch, for settings that apply right away.

Parameters

label

string

value

boolean

options?

WidgetOptions

Returns

boolean

---

tree()

tree(label, items, selected, options?): string | null

A tree of selectable items, such as an outliner. Returns the selected item’s id, or the user’s new choice; null when nothing is selected. Arrows fold and unfold items.

Parameters

label

string

items

readonly TreeItem[]

selected

string | null

options?

WidgetOptions

Returns

string | null