UI

Window methods use :; module functions such as ui.createWindow use .. Calls return true when admitted or nil, error unless a row states another result. Errors have operation = "ui", code, and message. Admission does not mean the Window has painted. Handles belong to the script runtime that created them and cannot be reused after reload. See Script-Created Windows for a complete input/action example and lifecycle behavior.

Settings/preview Windows validate calls but perform no native operations. Menus are not available to Scripted Decorations.

Content Values

window:setContent({ text = "...", inputs = {...}, actions = {...}, animated = false, visual = {...} }) replaces everything, including input values. Omitted collections become empty. Invalid fields, duplicate IDs, missing callback functions, or invalid values reject the whole replacement. text is a UTF-8 string, limited to 65,536 bytes, not taskbar TDML. Actions and inputs each have at most 16 entries. IDs are non-empty, at most 64 characters, and use ASCII letters, digits, _, or -. Labels are UTF-8 up to 1,024 bytes.

An action is { id = "apply", label = "Apply", enabled = true, callback = "applyValue" }. enabled defaults true; callback names an existing global function, not a function value. A complete example shows the callback reading form data. Required-input validation also applies to visual buttons.

The optional visual table has these fields:

Visual colors use Qt color syntax, including #RRGGBB and alpha-first #AARRGGBB, not TDML’s alpha-last eight-digit form. Visual buttons also accept optional color and labelColor; omitted label color uses automatic contrast. Their native hover/focus/disabled styling remains host-controlled. Positioned text is a UTF-8 string styled by its record fields, not TDML. Within the visual surface, layers are background, cells, lines, paths, text items, then buttons; ordinary text/inputs/actions are a separate layer above it. There is no per-primitive z-order or pointer-hit-test API.

Cell Space accepts exactly one printable Basic Latin character (U+0020..U+007E) or Halfwidth Forms character (U+FF61..U+FF9F) per record, not arbitrary Unicode, emoji, or combining/wide characters. Off-grid cells are clipped and may become visible when resized. Cell mutations are contiguous arrays of set, clear, or clearAll records. clearAll must be first and has no cell fields; addressed coordinates cannot repeat in a batch. The batch and retained collection are each limited to 8,192 entries. Mutations preserve other Window content, while complete content replacement replaces the cells.

animated = true delivers visible Window frame opportunities to onTick(frameTimeSeconds). onResize(windowId, dimensions) provides positive columns, rows, and surfaceAspect (visual width/height ratio), not pixel size, font metrics, or DPI. Initial dimensions arrive after realization; resize bursts coalesce, and hidden/minimized/preview Windows do not deliver them.

onKey(key, modifiers) receives key presses only for a focused visible Window. Keys are 0-9, A-Z, F1-F12, Escape, Enter, Space, Tab, Backspace, Delete, Insert, Left, Right, Up, Down, Home, End, PageUp, and PageDown. Modifiers are boolean shift, ctrl, alt, and meta. Fullscreen Escape is handled by the host before Lua. The callback does not receive a Window ID, key releases, repeat notifications, or text-composition events.

Window Inputs

Inputs share id, kind, optional label, optional value, and required (default false). An omitted value reads as nil; a supplied empty string or false is a valid value. An invalid edit retains the last valid value but prevents action activation if that input is required. Application policy, such as requiring a future alarm time, belongs in Lua. There is no general input-change callback; read values in an action or another callback using getInput().

For dateTime, omitted components are fixed rather than editable; an omitted second is fixed at zero. If components is absent, all six are available. Twelve-hour display changes only presentation; Lua still receives a normal instant. See Time for arithmetic and persistent millisecond conversion.

Rich-text editboxes require ui.createRichText(html), not a Lua string containing HTML. The returned value has :toHtml() and :toPlainText(). Persist the HTML string, then call createRichText when restoring; neither storage nor JSON accepts the rich-text value itself. This fragment installs a restored document in an existing Window:

local html = storage.getOrDefault("documentHtml", "<p>Initial <b>notes</b></p>")
local notes, richError = ui.createRichText(html)
if not notes then
	log.error(richError.message)
	return
end

function saveNotes()
	local value, inputError = window:getInput("notes")
	if not value then
		if inputError then log.error(inputError.message) end
		return
	end
	local accepted, err = storage.set("documentHtml", value:toHtml())
	if not accepted then log.error(err.message) end
end

local ok, contentError = window:setContent({
	inputs = {
		{ id = "notes", kind = "editbox", textFormat = "richText", value = notes,
		  toolbar = {
			  { id = "bold", label = "B", command = "bold" },
			  { id = "bullets", label = "Bullets", command = "bulletList" },
		  } },
	},
	actions = { { id = "save", label = "Save", callback = "saveNotes" } },
})
if not ok then log.error(contentError.message) end

The example queues the save; use storage.flush before reporting durable success. HTML is the rich-text serialization format, not Markdown or taskbar TDML, and does not expose a native document object.

The optional formatting toolbar contains { id, label, command } records. Commands are bold, italic, underline, strikeout, textColor, paragraph, heading1, heading2, fontDecrease, fontIncrease, alignLeft, alignCenter, alignRight, bulletList, numberedList, outdent, and indent. They act on the current selection, or subsequent typing for character formatting; textColor opens a color picker. Each toolbar is limited to 16 records and is available only for rich-text editboxes.

topToolbar uses the same record shape for separator, save, cut, copy, paste, undo, redo, and spellCheck. A save record must have a matching normal Window action ID; it invokes that action rather than saving automatically. Spell-check availability depends on the host editor support. These controls do not provide arbitrary widgets, layouts, link dialogs, or QML access. The exported Rich Text Editor.lua demonstrates the complete editor and flush handling.