Metadata Headers

A metadata header is an optional block at the top of a Plain Text (.pt), TDML (.tdml), or Lua (.lua) Decoration file. It carries the Decoration’s name and settings so they travel with the file. TaskManSync reads the header when you import a file and writes one when you export a Decoration.

--[[
Name: Alert Badge
WidthMode: Fixed
Width: 120
]]
{sz:18;fgc:#FFF7ED;bgc:#C2410C;bld}ALERT{}

This example is a TDML file. Its text size comes from the TDML markup {sz:18} in the body, not from the header.

The header is not part of the Decoration’s content. It is never displayed on the taskbar or in the preview, and a TDML header is not TDML syntax.

Where the header goes

• The header starts with --[[ and ends at the first ]] after it. Neither may be missing: an opening --[[ with no closing ]] is an error.
• Blank lines and ordinary -- comment lines may come before the opening --[[. The first other line must begin with --[[ (leading spaces are allowed). A --[[ that comes after other content is not a header.
• Only the first header is read. Text after the closing ]] on the same line is not part of the header.
• A file with no header is valid. When imported as a new Decoration, its settings take their defaults, and a Plain Text or TDML Decoration has no name. Re-import into an existing Scripted Decoration keeps omitted settings, as described below.

Writing keys

Each setting is one line of the form Key: value.

• The key starts in the first column. A line that starts with a space is not a key.
• Key names are not case-sensitive (name: and Name: are the same). Values that are fixed words, such as Left or Fixed, must use the exact capitalization shown below.
• One space after the colon is optional. Values are not quoted, and surrounding spaces are ignored except in Taskbars: after the optional space, all remaining spaces are kept.
• Keys can appear in any order, and blank lines between keys are ignored.
• A key can appear only once. A repeated key, even with the same value, is an error.
• Keys the format does not support are ignored. This includes Notes in every format, Description in Plain Text and TDML, and Width or WidthMode in Lua. There is one layout exception: after a single-line Lua Description, a nonblank line must begin another supported key in the first column or end the header. An unsupported key there is an error; put it before Description or use the multi-line form below.
• ]] cannot appear in a value.

When only Name is set, a compact one-line header is also accepted: --[[ Name: Alert Badge ]]. Everything after Name: is the name. No other key can be written in the compact form.

Supported keys

A missing key is never an error: its default applies. A key that is present with an invalid value is an error. The Lua keys are Name, Description, Taskbars, and Orientation; Lua controls its own width, colors, and text in code. See Scripted Decorations.

Font Size

FontSize is a multiplier, not a pixel size, and is spelled exactly FontSize when TaskManSync writes it. Values need not be multiples of 0.1.

FontSize is a Plain Text key only. The multiplier scales the text. Export writes any value you set and leaves out an unset value. The written number may look different: 1.0 is written as 1, and 1.1 may be written as 1.1000000000000001; both restore the same value on import.

FontSize is not a TDML key. In TDML, set text size in the body with TDML markup:

{size:30}Large text{}
{sz:14}Small text{}
{sza:18}Explicitly absolute{}

size, sz, and sza take a whole number of logical pixels. szr and sizer take a factor of the Decoration’s height, for example {szr:.5}Half height{}. See the TDML Reference.

FontSize is not a Lua key either. A Scripted Decoration sizes its text with the same TDML markup in the text it returns.

Width

Width accepts 1 through 4096, the same range as the Settings Width control. A larger value, such as 4097, is an error. See Decoration Width.

Invalid headers

A header’s settings are applied all or nothing. If any supported key has an invalid value, appears twice, or the block is not closed, no header settings are applied. Import Decorations creates the Decoration with default settings, but a Lua file still uses a valid Name from the header for its name and duplicate check.

• Import Decorations: the file is still imported with its text unchanged. The import result reports it as “imported with diagnostics” and lists the problems, and the problems appear again in Settings when you select the Decoration. Fix the file or the text and import again.
• Plain Text and TDML: a valid Name is not used when the rest of the header is invalid, so the Decoration is unnamed.
• Lua: if there is no usable Name, the file name is used. A name already taken by another Scripted Decoration rejects the file, even when another header field is invalid.
• Lua Import or Re-import on an existing Decoration: a malformed header rejects the whole action and nothing changes.

Problems are described by line number, for example Line 3: invalid value for "Width"; expected a whole number from 1 to 4096.

When the header takes effect

After an import, TaskManSync keeps only the name line in the stored header of a Plain Text or TDML Decoration; the other settings now live in the Decoration’s Settings. Change them in Settings, not by typing Width: 80 into the header. Lines TaskManSync does not use, such as Notes, are left as they are.

After a valid Lua import or re-import, Name and Description stay in the stored script’s header. Taskbars and Orientation are removed because their values now live in Settings; export writes them from those settings when needed. Ordinary script-editor Save does not remove or apply these lines.

Name after Save

When you save a Plain Text or TDML Decoration, its name follows the header:

• a valid header with Name sets the name (spaces around it are removed);
• a valid header without Name, or no header at all, makes the name blank;
• an invalid header leaves the name as it was, and the save still goes through.

The Decorations list shows the name from the header when its eye button is closed. A Decoration with no name shows its rendered content. Names are not required to be unique: several Plain Text or TDML Decorations can share a name. Scripted Decoration names must be unique; see Importing and Exporting.

Examples

The shipped TDML example Alert Badge.tdml uses the compact form:

--[[ Name: Alert Badge ]]
{dc:#7F1D1D}
{fgc:#FFF7ED;bgc:#C2410C;bld;wgt:700}ALERT{} {fgc:#FDBA74;opc:65;ita}CHECK LOG{}

A Lua file can carry its name, a multi-line description, and settings:

--[[
Name: System Status
Description: """
Shows the current system status.

Click the taskbar item to refresh it.
"""
Orientation: Horizontal
]]

An example that is not in the catalog but shows the Plain Text keys:

--[[
Name: Two Hands
BackgroundColor: #1283f4
TextColor: #bdf412
Alignment: Left
WidthMode: Content
Notes: ignored
]]
👈|👉