TDML Reference

This reference separates text/run formatting from whole-Decoration directives. Text formatting uses nested scopes; alignment affects the presentation as a whole; directives affect the Decoration surface or position the complete presentation.

Text and run formatting

bold, italic, underline, and strike turn their style on for the scope; close the scope with {} to restore the previous style. The last valid occurrence of a property in a tag wins. Invalid parameters are diagnosed and do not replace the previous valid value.

background/bgc paints only the affected text run. When a color includes alpha, the run’s opacity is multiplied by that alpha. It does not color the unoccupied Decoration surface.

Alignment

Alignment is presentation-wide, not per-run formatting. The parser takes both values from the first emitted text run. Set alignment on a formatting scope that produces the first text; any earlier text, including whitespace, becomes that first run and determines the alignment instead.

For example, this makes the presentation centered; the nested color and bold properties style its text runs:

{alignh:center;alignv:center}{fgc:#FFFFFF;bld}CENTERED{}{}

Alignment places the presentation within its available Decoration geometry. It does not move the Decoration in the workspace and is distinct from posh/posv.

Font size and offsets

Absolute sizes use a positive integer number of logical pixels. Relative szr/sizer values are positive finite factors, not percentages. Each relative value uses the same realized internal Decoration height, not the total height of all lines. Sizes inherit through nested scopes and restore on {}. If content exceeds the surface, it is clipped; TaskManSync does not automatically fit or shrink it. If realized geometry is unavailable, the relative inline size is omitted and normal text sizing is used.

offseth/osh and offsetv/osv move one logical line as a unit, including its differently styled runs. Negative horizontal offsets move left; positive move right. Negative vertical offsets move up; positive move down. These line offsets are inherited with the style and are not limited to the line containing the opening tag. Use a separate scope when subsequent lines should not inherit the offset. Prefer canonical offsetv or osv; offset and os remain vertical-offset aliases. The offset parameter inside posh or posv is a different, whole-presentation value.

Colors

TDML colors accept named colors and these hexadecimal forms, with alpha last when present:

The same color parser is used for foreground, text-run background, and dcolor/dc.

Whole-Decoration directives

These directives apply to the entire presentation or surface, not to one run. They are valid at root scope, wherever that root-level tag occurs in the source. They can appear together; if a tag also contains ordinary formatting properties, those properties still open a scope and need a closing {}.

Each position directive requires exactly one named anchor parameter and one named offset parameter. Positive horizontal offsets move right; positive vertical offsets move down. The actual Decoration surface is the reference frame and remains the clipping boundary. These directives do not set workspace order, item placement, or Decoration width.

A directive-only tag does not open a text scope and must not be followed by {}. A line ending immediately after it is handled as described in the Guide. Directives are not available in Scripted positioned text elements; those elements use their own coordinates and the parent Decoration’s surface.

Surface color precedence

For a Static Decoration, TDML dcolor/dc takes precedence over the definition background, then the active Theme’s Decoration background, Theme Taskbar background, and KDE/Plasma default. For a Scripted Decoration, a non-empty runtime decoration.backgroundColor takes precedence over TDML dcolor/dc, followed by the same definition and theme fallbacks. An unset dcolor leaves that fallback chain in effect. See Colors and Appearance.

Width and orientation

Content, Fixed, and Flexible are Decoration width modes configured separately in Settings (or by the Scripted Decoration API); TDML has no width property. Width is the extent along the taskbar’s item flow, so its axis follows the taskbar orientation. Settings’ Orientation control affects only the preview; the placed Decoration follows its taskbar. szr still uses realized internal height, while posh/posv position the presentation inside the Decoration surface. See Decoration Width and the TDML Guide.