Scripted Decorations in Settings

Scripted Decorations run Lua to create and update one taskbar display. The script is stored in the Decoration definition; the taskbar only receives its published presentation. A Scripted definition has one active placement, and only one TaskManSync applet at a time runs its script. Other applets show the shared result. See placing Decorations for placement and applet visibility.

Import and edit

Create a Scripted definition in TaskManSync Settings > Decorations, then choose Import to copy a local .lua file into it, or Edit Script to enter source directly. Import and Re-import check the Lua syntax: a script with a syntax error is rejected, nothing changes, and the error appears in Settings. (Import Decorations, the batch import beside + New, behaves differently: it still creates the Decoration and reports the problem. See Importing and Exporting.)

The saved source is what runs. Deleting or moving the original file does not stop the stored script, though Re-import needs that file. To save a copy of the script as a .lua file, use Export, the button beside Place that every Decoration type shares. Save pending changes first; export does not change the definition or include private storage or external modules. See Importing and Exporting. A Scripted Decoration needs a non-empty, unique Name; its Name also identifies its private storage.

The script editor’s Save button stores source and checks its Lua syntax. Reload Decoration is on by default; when enabled, a successful save reloads the active Decoration.

Metadata header

A leading Lua long comment can carry a metadata header with four keys: Name, Description, Taskbars, and Orientation.

--[[
Name: System Status
Description: Displays the current system status.
Orientation: Horizontal
]]

On Import or Re-import, Taskbars and Orientation become the Decoration’s settings (Orientation changes only the Settings preview). Keys the file leaves out keep their current values. A non-blank Name replaces the definition’s name; otherwise the current name is kept. If both are empty on an initial Import, the file name supplies the name.
The Description is shown beneath the Settings preview.
A malformed header (for example an invalid Orientation, a repeated key, or a multi-line Description without """ delimiters) rejects Import and Re-import.
Save in the script editor does not read or check the header, so changing it there changes nothing. Use Re-import to apply a changed header from the file.

See Scripting Concepts for the Lua side.

Taskbar presentation and updates

decoration.text is a TDML string. See the TDML Guide and TDML Reference for its syntax and properties. A script can also set the taskbar surface background, request Content, Fixed, or Flexible width, create positioned text elements, and assign retained line/path graphics. Content uses whole-Decoration text only; positioned text and graphics are excluded, and visual-only output falls back to effective Flexible with a warning. Graphics are limited to those primitives; they do not support images, SVG, shaders, or arbitrary native drawing. Line endpoints use normalized surface coordinates from 0 to 1; paths use a logical-pixel rectangle with normalized move, line, cubic, and close operations. The Scripted Decorations guide covers the broader Lua surface.

The usual lifecycle is onLoad(), optional onTick() updates, and normal teardown through onStop(). onTaskLeftClick(modifiers) and onTaskMiddleClick(modifiers) can respond to clicks on the taskbar item. requestUpdate() asks for another coalesced update. Periodic updates are disabled by default; assigning decoration.interval during top-level initialization requests onTick() opportunities at an interval from 50 to 2,147,483,647 ms. This is not a promise that callbacks or painting occur at that cadence. Updates are serialized and coalesced, not real-time.

Scripts can use storage for persistent private values keyed by the Decoration’s Name (spaces at either end and capitalization are ignored). Values survive runtime reloads and ordinary placement removal/re-addition; Lua variables and runtime handles do not. Renaming the Decoration retains its storage. See Scripting Concepts for storage and runtime errors.

The taskbar surface is only one output. A Scripted Decoration may create a separate TaskManSync Window; Window content can include rich-text editboxes backed by a typed Lua value from ui.createRichText(). That rich-text userdata is for Window inputs, not a way to put arbitrary HTML or native document objects on the taskbar Decoration. See Script-Created Windows.

Scripted Decorations can also request generated audio with sound.tone, sound.note, sound.sequence, and sound.abc; sound.stop() stops playback from that runtime. These are bounded, fire-and-forget requests, not audio-file playback or a completion-notification API. See Sound.

Examples and limits

Use TaskManSync Settings > Other Settings > Export Examples… to copy the example catalog to a folder. It includes Plain Text and TDML source as well as importable Lua scripts. Useful Scripted starting points include Clock.lua (time/date and a Window), Alarm.lua (a scheduled alarm with an optional generated chime), Aquarium Fish Taskbar.lua (animated graphics and click interaction), and Winter Scene.lua (an animated scene). The Scripting Examples page describes the catalog.

Lua receives typed values and bounded TaskManSync capabilities, not arbitrary Qt, QML, Plasma, or TaskManSync objects. A callback error is contained to that runtime generation; the last successful output may remain visible while the Decoration is marked with fault status. TDML diagnostics and Scripted preview errors are shown in Settings. See the Scripting guide for a broader overview.

Decoration Width Colors and Appearance