api.ui

Milliseconds before it leaves on its own; 0 keeps it until dismissed.

One button beside the text, for a notice that is really a question — the update check's "Download". Pressing it dismisses the toast as well as running this.

Manifest id (or slug of the name).

The spec the plugin was installed from (builtin:…, github:…, a URL).

The manifest's icon, resolved; absent when it declared none (or an unusable one).

Return false (or a promise of it) to keep the dialog open.

Close after run; default true.

Fill body (an empty <div> inside the dialog); return a cleanup if you need one.

Footer buttons, left to right; a single Close when omitted. An empty list leaves the dialog without a footer — for a dialog that is a workspace of its own, with its own controls, closed by the title strip's × (setBusy and a slot then have nowhere to show).

The body runs edge to edge, without the dialog's padding: for content that draws its own frame (an editor with its own bars).

Ctrl+V anywhere in the dialog (while it is the topmost one). Files come from the clipboard's items — a screenshot pastes as one image/png file — and text is the plain-text part, so a copied image URL arrives here too.

Something dropped onto the dialog body.

Escape normally closes the dialog. Answer true to keep it open for this press — when the key was meant for something inside the dialog that handles Escape itself (a code editor dismissing its own popups), judged by the element it landed on.

Offer a slot of this dialog's own, so other plugins can add to it with ui.dialogSlot the way they add to a built-in dialog: id is what they name ("<plugin>.<name>"), fields the working copy lent to them, read live, and payload what the dialog was opened with. The Text Trigger Editor plugin offers "trigedit.text" with a text field.

Whether the dialog is still on screen.

Change the title strip's text.

Say the dialog is working: a ring and label at the left of the footer, and every footer button disabled until setBusy(false). A button's own run already does this for as long as its promise is pending — this is for work the buttons did not start, such as the first load, or a search that runs as the user types.

In CSS pixels; 260 by default. The panel is as tall as its content, up to the map's height. Ignored when docked.

Floating: a height in CSS pixels instead of the content's own; the body then scrolls, or fills, as its content asks. Bottom dock: the strip's starting height (160 by default), which the user can then drag.

Floating only: a grip at the bottom-right corner lets the user resize the panel, and the size is remembered with the position for the session. The body is a column flex box, so a root element with flex: 1; min-height: 0 fills whatever size it has — what a code editor or a long list beside the map wants.

Where the panel lives. "float" (the default) is a frame over the map the user drags about. "right" puts it in the right dock as a panel of its own, under Minimap, Layers and Properties, with the same head and hide button the built-in panels have — the choice for anything the user keeps open while working, such as an assistant or a readout. A docked panel shows the dock even when the user has hidden every built-in panel in it. "bottom" puts it in a strip under the map, as wide as the map, which the user makes taller or shorter by dragging its top edge — the place for a timeline, a console or anything read along the width of the map. Several bottom panels stack.

A docked panel that takes the dock's spare height (a transcript, a long list); off by default.

Floating only: the body runs edge to edge, without the panel's padding — for content that draws its own frame.

Floating only: a button in the title strip (and a double-click on it) makes the panel fill the map's area, and puts it back. For a window of charts or tables read at length beside a map that is still there underneath. PanelHandle.maximize does the same.

Fill body (an empty <div> inside the panel); return a cleanup if you need one.

The panel closed, whichever way.

What the files are, for File ▸ Open's list of types ("StarCraft replay").

With the dot, any case: [".rep"].

What the switch over the map calls it ("Game"). The map itself is "Map".

Called once, with the element the view lives in. Fill it as you like; it is as large as the map's area and in the page from the first time the view is shown. Return a function to be called when the view goes (the plugin stops, or dispose).

The view is shown in the map's place, where the map was looking: look is the map's view at that moment, or the other view's (setCamera) when the switch came from one. Turn to look at the same place, as near the same scale as you can, so the switch keeps the person where they were. Not called when another map, already showing the view, comes to the front.

What the minimap shows while the view is shown. Without it the minimap shows the map, and its box and presses are the map's own view's (hidden behind this one).

Draw over the map's ground, each time the minimap's picture is made while the view is shown.

A press on the minimap, and each move of a drag from it, at a map pixel: look there. Without it the minimap does not move anything while the view is shown.

Minimap canvas pixels per map pixel.

A map pixel's x on the minimap's canvas.

The canvas's size in pixels, each side (the map is centred in it, letterboxed).

Offer the view on a map (by OpenDocumentInfo.id; the one in front when left out), or stop offering it there. A map that offers views has a switch over it, the map's own view first. Nothing is offered until you say so.

Show the view in that map's place (offering it there if it was not), or the map again.

Whether the view is what the map in front shows now.

Whether the view is shown changed for the map in front: the person used the switch, show was called, or another map came to the front.

Where the view looks now, in map pixels; call it whenever that changes. The minimap draws its box there while the view is shown, and the map, shown again, opens on the same place at the same scale.

Make the minimap's picture again (minimap.draw), at most once a frame. Cheap: call it as the view's contents move.

A maximizable panel: fill the map's area (true), go back (false), or toggle. Nothing for another panel.

Whether it fills the map's area now.

The tooltip.

Show a spinner in the cell.

Paint the cell as a warning.

Change any of the fields; the cell redraws.

A word or two; the button is as wide as it.

The tooltip.

A count or a short mark beside the label (unread messages); nothing when absent, null, 0 or "".

Drawn pressed: what the button opens is open.

Change any of the fields; the button redraws.

Fill body with the page's controls; return a cleanup if you need one.

Called on OK and Apply while the dialog is open and the page has been shown.

Called by Reset to defaults while the page is the one showing.

Close the Preferences dialog.

Map pixels. Kept inside the map while a button is held, as the built-in brushes do.

The tile under the pointer.

False once the pointer has left the map with no button held.

Whether the primary button is held.

Canvas pixels per tile.

A map pixel's x on the canvas.

The tiles on screen.

Shown in the viewport's HUD and the status bar while the tool runs.

After the name: "drag to draw a line".

CSS cursor over the map; "crosshair" by default.

Every pointer move over the map, button held or not, and once with inMap: false when it leaves.

Esc or a right-click. Return true to keep the tool running (you cancelled a gesture of your own); otherwise it stops.

Draw over the map, after everything else, each time the viewport repaints.

The tool is no longer running, for whatever reason (once).

Repaint the viewport — and so call draw — now. Cheap; call it from onMove.

Shown in View ▸ Overlays and the Layers panel. Unique per plugin. In English, like a menu label: shown through the plugin's registered catalogues.

Start visible; true by default. What the user last set for this name wins for the session.

Where the picture goes in the paint pass; "terrain" by default.

Draw in canvas pixels through view, each time the viewport repaints while visible.

The pointer over the map while the overlay is visible, on every layer and while a map tool runs; null once when it leaves. Call handle.redraw() here to move a hover mark. A press sets down but is never captured for you.

The overlay was shown or hidden, by the user in the chrome or by your handle.

Repaint the viewport — and so call draw — now.

Take the overlay out of the chrome for good; isVisible is false from then on.

Shown in the viewport's HUD while the user picks; also the status line.

Which kinds count; every kind when omitted. Under the pointer, a unit wins over a location.

accept for the file input, e.g. "image/*" or ".png,.jpg".

In the page, CSS pixels (clientX / clientY).

From the target's top-left corner, CSS pixels.

Whether a button is held — a drag across a chart.

Milliseconds the pointer rests before the tip shows. 500 for text, as the editor's own tooltips; 0 for a function, which reads out what is under the pointer and should keep up with it.

A width the tip does not grow past, CSS pixels; 320 by default.

Ask content again where the pointer stands; nothing when the tip is not showing.

Take the tip away until the pointer next moves over the target.

The primary button; OK by default.

Paint the primary button as a destructive action.

A multi-line field.

Show a Cancel button; cancelled() answers true once it is pressed.

How far along (0…1), and optionally a line under the bar.

True once the user pressed Cancel or closed the panel. Poll it inside a loop.

The same answer as a signal, for work that takes one: aborted when the user cancels, so fetch(url, { signal }) and anything built on AbortSignal stop with the panel. Never aborted by done().

Start off waiting: a ring in front of the label, and the button disabled.

A radio button instead; give the group a name.

Fill the tab's panel, the first time it is shown. What it starts ends with the panel or dialog the tabs are in.

The tab shown first; the first that is not disabled otherwise.

Smaller tabs, for a narrow panel.

Dimmed text at the end of the row.

A number in the row's gutter, as the editor's own lists show indices.

Which row starts selected.

Maximum height in pixels; the list scrolls past it.

"sm" 10px, "md" 14px (the default), "lg" 20px.

Text beside the ring. Without it you get the bare ring, to put beside your own.

How far along to start: 0…1, or null (the default) for the sliding bar that means "no idea how long".

A line under the bar — what is being waited for, or how much of it is done.

The percentage at the end of the bar; on for a bar that knows how far along it is.

Width in CSS pixels; it fills the width it is given by default.

What it says before anything has happened.

CSS width, "100%" by default.

Height in CSS pixels: 10 for a line, 44 for a block.

How many lines, stacked; 1 by default. The last is drawn short, as text ends short.

A block — the place a thumbnail or a picture will take — rather than a line of text.

What is being waited for, over the covered box.

Dim what is already there rather than leaving it at full strength; true by default.

Change the label without lifting the cover.

Uncover the box. Safe to call twice.

While the list is running, show only its last this many rows; the rest come back when it stops. For a list that grows past what a panel can hold while it is watched. 0, the default, shows every row.

A character in front of the label, in the list's own vocabulary: ✎ for a change, ▸ for a read.

The row's tooltip.

Begin running (a ring) rather than pending (a hollow mark).

The line to begin with.

Open to begin with.

Start with a ring for a mark.

Buttons side by side of which one is on: a choice of a few short options seen at once ("Both", "Minerals", "Gas"), where a select would hide them. onChange hears the value picked; set moves the choice without it.

Tabs in the editor's style: a row of tabs over a panel a tab. A tab's mount runs the first time it is shown and its panel is kept after, so what the user did there stays when they come back. Arrow keys move between the tabs.

A two-column grid of labelled fields.

A titled box (a fieldset with a legend, as the dialogs use).

Small dimmed explanatory text.

A turning ring: on its own to put beside your own text, or with a label beside it.

A bar, with the percentage and a line under it. set(0…1) moves it; set(null) gives the sliding bar for work whose length is not known. Use it where the wait has a size — a download, a pass over every trigger — and a spinner where it does not.

The dialog's bottom line: set, busy, progress and a cancel button.

A grey stand-in for content that has not arrived, in the shape it will take. Rows of these in the list you are about to fill say more than an empty box does, and the list does not jump when the answer lands.

Cover a box while what is in it is being replaced: dimmed, deaf to clicks, with a ring and a label over it. done() uncovers it. Give it the box, not the page — the search field that starts the work should stay live so the user can change their mind. Calling it again on a covered box only changes the label.

A list of steps, each pending → running → done / failed / skipped, with a detail.

A block folded to one line — a mark, a line that can change, a control at its end — over a body.