Getting Started

A Scripted Decoration is created from the Decorations settings. Its Lua source is stored with the Decoration definition. If you import a script from a file, the imported source becomes the stored source; changing the external file later does not automatically replace the stored script.

1. Open TaskManSync Settings > Decorations, choose Scripted from + New, and give it a non-empty, unique Name. Save Name/settings changes with the Decorations page’s Save control; this is separate from saving Lua in the script editor. Import can also supply the Name, Taskbars, and Orientation from the script’s metadata header.
2. Select Edit Script to enter Lua source, or Import to copy a local .lua file into the definition. For ready-made scripts, first use Other Settings > Export Examples…, then import one of the exported Lua files.
3. In the editor, choose Save. Reload Decoration is enabled by default and remembered between editor sessions. When checked, a successful save also replaces the active runtime. When unchecked, the source is stored but the running script keeps its previous code until it is reloaded.
4. Select Place to add the definition to the shared taskbar workspace, or drag its Settings preview onto a taskbar. Creating a definition alone does not place it. A Scripted definition permits one active placement; other applets display the shared output rather than running extra copies.

Save and Import compile-check the source; syntax errors reject the candidate and appear in the editor or Settings. This is not a guarantee that callbacks, file access, or external requests will succeed when the script runs. Unsaved editor changes are not used by the active Decoration.

Re-import explicitly reads the original imported file again; it is available only when a source-file location was recorded. It applies the file’s metadata header: keys the file mentions update the Decoration, and keys it leaves out keep their current values. Saving in the script editor does not read the header. Export, the button beside Place that every Decoration type shares, writes a .lua copy with the current saved Name, Description, Taskbars, and Orientation; the script outside the header stays unchanged. Save pending edits before exporting. Export does not include private storage or bundle external modules, and cancellation leaves the definition unchanged. See Importing and Exporting for the difference between Import here and Import Decorations. Editing or saving in TaskManSync does not write back to the original file. Imported paths also supply the base directory for relative file access and Lua modules; see Desktop capabilities.

A minimal Scripted Decoration can be as small as:

function onLoad()
    decoration.text = "Hello from Lua"
end

The script assigns TDML text to decoration.text. Plain text is valid TDML too, so no special markup is required for a simple result.

For dynamic content, update the Decoration when the value changes:

function onLoad()
    decoration.text = "Ready"
end

function onTaskLeftClick(modifiers)
    decoration.text = "{bld}Clicked{}"
end

The most useful starting callbacks are:

Callbacks are optional global Lua functions, not methods on decoration. Define only the ones your script needs. onTick() does not run periodically unless you request updates, for example by assigning decoration.interval = 1000 at the top level of the script, outside onLoad().

An update opportunity is not an immediate-paint guarantee. Scripts should update their state and presentation and let TaskManSync schedule and publish the result. Continue with Scripted Decorations for layout and drawing, Script-Created Windows for interactive windows, and Concepts for persistence, scheduling, and errors. Placing Decorations explains visibility and removal.