Skip to content

Positioning Stage

Jump to bottom
Bobby Comet edited this page Aug 23, 2026 · 1 revision

Position Stage

What it is

Position Stage is a layout tool in Conky Studio’s Studio tab. It shows a 2D plane the size of the selected window (or the project canvas for a single-window HUD). Each visual node appears as a draggable rectangle (proxy). Moving a proxy updates the same x/y or cx/cy properties used by the property panel, Live Preview, and Build.

It does not replace the property-panel spinboxes. It is an alternate, screen-space way to place visuals. The node graph still handles data flow and wiring; Position Stage only handles where things sit on the HUD.

Where to find it

In the Studio tab:

  • Bottom docks: Live Preview and Position Stage are tabified together.
  • Open Position Stage from that bottom tab strip (or from the “Hidden panels” bar if the dock was closed).

How it works

Window plane

  • The stage draws a rectangle matching the current window’s width × height (from Windows settings, or the Canvas node for a single-window project).
  • Coordinates: top-left is (0, 0); bottom-right is (width, height).
  • A light grid and center crosshair help alignment.
  • Extra margin around the window lets you scroll slightly outside the bounds.

Proxies (visual nodes)

Only visual nodes with position properties are shown:

Position props Behavior
x, y Proxy top-left matches those values
cx, cy Proxy center matches those values (gauges, rings, fans, etc.)

Size is estimated from common props (width/height, radius, size, bar counts, etc.) so the proxy roughly matches on-screen footprint. The label is the node’s name or type.

Non-visual nodes (sources, logic), the Canvas node, and visuals without position keys do not appear.

Writing positions back

When you drag a proxy and release:

  1. Snap (if enabled) is applied during the drag, not after.
  2. Final position is written into node.props as integer pixels.
  3. That triggers the same graph changed path as editing spinboxes → Live Preview can rebuild, and Build uses the new values.

Multi-window

If the project has multiple windows:

  • Use the Window combo to pick which window’s size and scene the stage represents (same idea as Live Preview’s window selector).
  • If that window has a non-empty visible node list (scene filter), only those visuals are shown; otherwise all visible visuals on the shared graph are shown.

Controls

Control Purpose
Window Which window resolution (and optional scene filter) the stage uses
Snap Snap dragged positions to a grid
Step Grid step in pixels when Snap is on (e.g., 10 px)
Lock position Freeze the selected proxy (same idea as the Layers lock)
Fit Zoom so the window rectangle fills the view
↻ Reload proxies from the current project

Navigation

  • Ctrl + scroll — zoom
  • Alt + drag or middle-click drag — pan
  • Left-drag on empty area — pan / rubber-band (depending on context)
  • Left-drag on a proxy — move that visual

Lock and Layers

  • Lock position on the stage mirrors node.locked (Layers dock lock icon).
  • Locked proxies cannot be moved; they use a muted/dashed style.
  • Locking from the stage updates Layers and the canvas; locking from Layers updates the stage on refresh.

Selection sync

  • Selecting a proxy highlights the matching node on the graph canvas and in Layers, and loads it in the Properties panel.
  • Selecting a node on the canvas (or in Layers) can highlight the matching proxy.
  • Selection driven from the stage is careful not to force the Properties dock forward in a way that interrupts layout work (similar to how Layers selection avoids stealing focus during drag).

What Position Stage is not

  • Not a live Cairo preview of the HUD (that’s Live Preview / real Conky).
  • Not a replacement for wiring sources → logic → visuals on the node canvas.
  • Not a full design surface for every prop; only layout (position and optionally lock). Size, color, data, etc. still live in Properties.

Typical workflow

  1. Build or load a HUD in Studio (graph + properties).
  2. Open Position Stage and choose the window if multi-monitor.
  3. Drag visuals into place; use Snap for even spacing.
  4. Lock finished items so they don’t move accidentally.
  5. Use Live Preview to confirm the real Conky window matches.
  6. Build & Install when ready — exported render.lua / conf use the same coordinates.

Technical notes (for contributors)

  • Implementation: conkystudio.ui.studio.position_stage (PositionStagePanel, StageScene, StageProxyItem).
  • Snap is applied in StageProxyItem.itemChange(ItemPositionChange) on the proposed position so the proxy does not fight the drag or stick to the grid after Snap is turned off.
  • Size estimation is approximate so proxies stay grab-able; it does not need to match every generator pixel-perfectly.
  • Studio wiring: studio_tab connects layout_changed → graph refresh / preview, and keeps stage selection in sync with canvas and Layers.

Clone this wiki locally