Skip to content

Legacy Importer Internals

Jump to bottom
Bobby Comet edited this page Jul 31, 2026 · 4 revisions

Legacy Importer Internals & Conversion Rules

Project → Import Legacy Theme… builds a Studio project graph from a theme folder. Conversion is semantic, not a pixel-perfect clone. This page documents how that mapping works.

Source of truth in code: conkystudio/importer/legacy_parser.py (and related helpers).

Pipeline overview

theme folder
  ├── conf / conkyrc     → Canvas settings + lua_load paths
  ├── TEXT section       → cursor layout + text / image / exec nodes
  ├── *.lua (lua_load)   → Custom Lua visual node(s)
  └── scripts / images   → Custom Script sources, path rewrites, warnings
        ↓
   Project (nodes + edges + warnings)
        ↓
   user edits in Studio → Build (same codegen as native projects)

Import never writes a finished theme by itself. You Build afterward for start.sh / conf / Lua.

Conf block → Canvas

Parsed from the Lua-style conky.config = { ... } (or classic settings where present):

Conf concept Studio target
minimum_width / height (and related) Canvas width / height
alignment, gap_x, gap_y Canvas placement
update_interval Influences FPS / timing defaults where mapped
lua_load Resolved relative to the theme dir; may be one path or a list
own_window_* Not always 1:1; Build applies session-aware window types later

lua_load resolution: relative paths, ~, and sibling .lua files under the theme are collected. Multiple loads can become multiple Custom Lua nodes or a merged body depending on structure.

TEXT section → cursor + nodes

TEXT is walked line by line with a virtual cursor (x, y, font, colour) — the same mental model as Conky’s ${goto} / ${voffset} layout, not a full typesetting engine.

Layout directives

Directive Behaviour
${goto N} Set cursor x to N
${offset N} Add N to x
${voffset N} Add N to y
${alignc} / ${alignc N} Centre-ish x using canvas width (+ optional offset)
${font …} Update cursor font family / size
${color…} Update cursor colour (#RRGGBB)
blank lines Advance y by font size + spacing

Literal runs of text become visual.text nodes at the current cursor with the active font/colour.

Conditionals

${if_running…}, ${if_match…}, ${endif} are stripped. Content is kept; branching is not reconstructed. A warning is recorded when any conditional was removed.

${execi} / ${exec} / friends

Form Import rule
${execi INTERVAL CMD} Interval + command extracted
${execpi} / ${texeci} Same family as execi
${exec CMD} Treated as rare/once-style; becomes Custom Script with a long interval + warning

Classification of CMD (_classify_known_script):

  1. Native — known Conky vars / patterns → reuse or create a built-in source type (e.g. CPU-style).
  2. Family — known script families (weather, sensors, …) → family source node with poll_mode: execi and interval.
  3. Else — Custom Script source: command copied/adapted under scripts output, poll_mode: execi, interval from the directive.

TEXT may embed a placeholder tied to that source id so a following text visual can be wired or labeled. Unknown scripts are never dropped silently; they become Custom Script nodes.

${image}

Flag / args Result
path, -p x,y, -s W×H Position/size parsed when present
-n (no cache) Often mapped to Album Art-style node + warning with original path
normal image visual.image_icon if a matching file is found under the theme tree
missing file Node still created with empty/partial path + warning to re-attach

Important: Image/media import is best-effort. Many themes still need manual path fixes. Arbitrary media pipelines are not fully reconstructed.

Cairo / Lua → Custom Lua

Scope boundary (by design): the importer does not decompile Cairo into Arc/Bar/Star nodes.

Input Output
Bodies from lua_load One or more visual.custom_lua nodes
Surface create/destroy boilerplate Stripped or rewritten to rely on Studio’s shared cr / W / H
Asset paths inside Lua Rewritten toward theme-relative / images/ style names when basenames match
Scripts only referenced from Lua Discovered and turned into Custom Script nodes when possible
Click regions in Lua Clickable markers / commands when patterns are recognized

Heavy hand-written themes remain mostly Custom Lua after import — editable, but not exploded into the full visual palette.

Scripts & caches

  • Shell scripts in the theme tree are listed and may be copied into the project’s script set.
  • Cache directory assumptions in scripts can be patched toward Studio’s runtime-cache layout.
  • Executable bits and inline commands may be normalized into files under scripts/.

Edge-case overrides & honesty limits

Situation Rule
Unknown ${…} var Best-effort text or skip with warning
Nested complex TEXT Approximate positions
Pure Cairo art Custom Lua only
Absolute paths to another machine Survive as strings; break until edited
${execbar} / exotic bars Partial — often Custom Script + separate visual
Pixel parity Target ~70–90% structural usefulness, then polish in Studio

All approximations should appear in ImportResult.warnings — read them after import.

After import

  1. Fix Canvas size/alignment.
  2. Re-attach missing images.
  3. Wire or replace placeholders.
  4. Live Preview (same pipeline as native).
  5. Build & Install so start.sh is Studio-standard.

See also Legacy Import (user-facing summary).

Clone this wiki locally