Importing and Exporting Decorations

Import and export move Decorations between TaskManSync and files: .pt for Plain Text, .tdml for TDML, and .lua for Scripted Decorations. Each file can carry a metadata header with the Decoration’s name and settings.

Both actions are in TaskManSync Settings > Decorations. Import Decorations is the icon-only button beside + New above the list; hover it to see its tooltip. Export is beside Place (or Remove) for the selected Decoration.

Import files

Choose Import Decorations to open the import dialog. Importing creates new Decorations in the library; it does not place them on a taskbar.

Add files with Add Files…, add a folder with Add Folder… (subfolders are searched too), or drop files and folders onto the drop area in the dialog.
Check the review list. It shows each file’s name, its location, and its format.
Choose Import. Choose Cancel to close the dialog and discard the list without changing anything.

How files are chosen:

The format comes from the file extension alone, ignoring case: .pt is Plain Text, .tdml is TDML, .lua is Scripted Lua. Renaming a file changes how it is imported. TaskManSync never guesses a format from the content.
Files with other extensions are skipped when you add them. If nothing usable is selected, the dialog says “No supported Decoration files selected.”
The same file reached twice, for example by adding a folder and one of its files, appears once.
The review list does not open or check the files. Problems appear only after you choose Import.

What the file must contain

Files must be valid UTF-8 text. A file that begins with a byte order mark (BOM) is rejected as not valid UTF-8; save it without a BOM.
A Lua file can be at most 16 MiB. Lua files are also checked for Lua syntax errors, but see below for what happens to one that fails.
The importer has no explicit file-size check for Plain Text or TDML; this does not guarantee that arbitrarily large files can be stored. TDML’s own limits apply when it is displayed; see the TDML Guide.

The import result

Each file is processed on its own, so a problem with one file does not stop the others. After you choose Import, the dialog lists one line per file:

Line	Meaning
`name: imported.`	The Decoration was created and any header settings were applied.
`name: imported with diagnostics: ...`	The Decoration was created, but something in it needs attention: an invalid metadata header (no header settings were applied, but a Lua file still uses a valid `Name`) or, for a Lua file, a syntax error. The Decoration keeps the file’s text so you can fix it.
`name: is not valid UTF-8.`	Nothing was created. The Plain Text or TDML file is not valid UTF-8, or it begins with a BOM.
`name: could not read a valid UTF-8 Lua file.`	Nothing was created. The Lua file could not be read, is larger than 16 MiB, is not valid UTF-8, or begins with a BOM.
`name: could not be read.` or `name: could not be read completely.`	Nothing was created. The file could not be opened or read.
`name: Name already exists. Choose a different name.`	Nothing was created. A Scripted Decoration with that name already exists; see Names and duplicates.

If every line is imported., the lines are shown in green and the dialog closes by itself after about a second. If any file had a problem, the lines are shown in red and the dialog stays open so you can read them.

To recover:

Imported with diagnostics: select the new Decoration in the list. The problems are shown in its settings. Fix the text there, or correct the file and import it again; the first copy remains until you delete it.
Files that were not created: close the dialog with Cancel, fix those files, then open the dialog and add them again.

The dialog does not clear its list after an import, and it has no control for removing a single file from the list. Choosing Import a second time submits every listed file again, including ones already imported. Each repeated Plain Text or TDML file becomes another new Decoration, and a repeated Lua file is rejected because its name is now taken. Use Cancel and start a new list instead.

Names and duplicates

Plain Text and TDML imports always create a new Decoration, even when another one has the same name. Nothing is overwritten, merged, or renamed. Names are not required to be unique.
Scripted Decorations must have unique names. Names are compared ignoring capitalization and spaces at either end. A file whose Name: is already taken is rejected.
If a Lua file has no usable Name:, its file name without the extension is used.
A valid Lua Name: is still used when another header field is invalid. If that name is already taken, the file is rejected rather than renamed to its file name.

Importing a file or editing text

Importing a file and typing or pasting into a Decoration’s editor are different:

Import Decorations reads the file’s whole header and applies its settings to a new Decoration.
Typing or pasting into a Plain Text or TDML editor and saving stores the text. Only the header’s Name is read when you save; other header lines you type there do not change the Decoration’s settings. Use the Settings controls, or import a file.
Saving in the Lua script editor stores the source and checks its Lua syntax. It does not check or apply the metadata header.

So to bring a shipped example into the library with its settings, import the file rather than pasting its text.

Importing a Lua file into an existing Decoration

A Scripted Decoration also has its own Import and Re-import buttons. They copy a .lua file into that one Decoration, which behaves differently from Import Decorations:

	Import Decorations	Import or Re-import on a Scripted Decoration
Result	A new Decoration for each file.	The selected Decoration’s script is replaced.
Header settings	Start from the defaults; keys in the file replace them.	Keys in the file replace the Decoration’s current values. Keys the file leaves out keep their current values; they are not reset.
Lua syntax error	The Decoration is still created, marked “imported with diagnostics”.	The file is rejected and nothing changes.
Malformed header	Default settings are used, but a valid Lua `Name` still determines the name and duplicate check.	The file is rejected and nothing changes.
Name	The header `Name:`, else the file name.	A non-blank header `Name:` replaces the current name; otherwise the current name stays; if there is none, the file name is used.

For example, importing a file that has no Orientation: line onto a Decoration set to Vertical leaves it Vertical.

The script is copied. Editing, moving, or deleting the original file does not change the stored script. Re-import reads the original file again and is available only while TaskManSync knows where that file is; if the file is gone, it reports that the stored source file is missing and disables Re-import.

After a valid import, Taskbars and Orientation lines are removed from the stored script’s header because their values have moved into Settings. Name and Description remain. Export rebuilds the header from the saved values. A conflicting name on per-Decoration Import or Re-import leaves the existing Decoration unchanged and reports that the selected Lua script could not be attached.

Export a Decoration

Select a Decoration and choose Export.
Choose a destination in the save dialog. The file must end in the Decoration’s extension: .pt, .tdml, or .lua. The suggested file name comes from the Decoration’s name, with characters that are not allowed in file names replaced; a Decoration with no name is suggested as decoration. The name inside the file is unchanged.

Export writes the Decoration’s saved settings, so save pending edits first. It does not change the Decoration or place anything on a taskbar. Canceling changes nothing. If the file cannot be written, or a value cannot be written into a header, an error appears in Settings and no partial file is left at the destination. A Scripted Decoration must have stored Lua source before it can be exported.

What the header contains:

The header is rebuilt from the Decoration’s current settings. Everything outside the header is unchanged. If the Decoration has no header, one is added at the top.
Name is always written, even when blank.
Settings at their default are left out. The defaults are Alignment Center, WidthMode Content, Orientation Horizontal, unset colors, and an unset Plain Text FontSize. A Plain Text FontSize you set is always written; for example, 1.0 is written as 1. See Font Size for number formatting. Omitted values use defaults on a new import; Re-import keeps existing values.
Width is written only when WidthMode is Fixed, and Taskbars only when its saved value contains a digit from 0 to 9; when written, the whole value is kept. A new import uses the default width for Content or Flexible, and an omitted Taskbars means all applets, not necessarily the literal text All.
If Name is the only setting written, the header is the one-line form --[[ Name: Alert Badge ]]. Otherwise it is a multi-line block.
Plain Text writes Name, colors, FontSize, Alignment, WidthMode, Width, Taskbars, and Orientation (those that are not defaults). TDML writes Name, WidthMode, Width, Taskbars, and Orientation; TDML text size is part of the TDML markup, not the header. Lua writes Name, Description, Taskbars, and Orientation; Lua code controls its own width. A multi-line Description is written between """ lines.
A value that cannot be written is reported instead of being changed. This includes a name containing ]] and a Lua Description containing a line that is exactly """. Notes is never written.

Exported Plain Text and TDML files can be brought back with Import Decorations, and Lua files with Import Decorations or, for an existing Decoration, Import and Re-import. Export does not include a Scripted Decoration’s stored data or external modules.

To copy TaskManSync’s ready-made examples, use Other Settings > Export Examples… instead; see the Scripting Examples and TDML Examples pages.

Creating and Editing Decorations Metadata Headers