ADL files and extensions

ADL (ASCII Display List) files are text files that describe display layouts. QtEDM uses the same core ADL format as MEDM and extends it with a small number of QtEDM-only block types when a display uses QtEDM-specific widgets.

An ADL file contains:

• A file header with format version and creation information
• A display block defining overall display properties
• A color map defining the 65-color palette
• Widget definitions with their properties and PV associations

QtEDM reads ADL files created by MEDM. MEDM can read the common ADL subset written by QtEDM, but displays that use QtEDM-only extensions are not behaviorally compatible with legacy MEDM. The common file format is documented in the MEDM Reference Manual.

PV Protocol Prefix

QtEDM supports both Channel Access (CA) and PVAccess (PVA). To force PVA for a specific channel, prefix the PV name with pva://:

• pva://my:pv:name – Connect using PVAccess
• my:pv:name – Default Channel Access (no prefix)

ADL Version Header

QtEDM writes a file header version of 40001 when any PV uses the pva:// prefix. Displays with only CA PVs are saved with version 40000. Both versions remain fully readable by QtEDM.

QtEDM-only ADL Extensions

QtEDM currently adds these object and attached-rule block types beyond the legacy MEDM set:

• heatmap
• thermometer
• led_monitor
• text_area
• pv_table
• wave_table
• waterfall_plot
• setpoint_control
• expression_channel
• qtedm_symbol
• qtedm_toggle
• qtedm_spinbox
• qtedm_tabbed_display
• qtedm_archive_plot
• qtedm_ndarray_image
• qtedm_plugin
• qtedm_rules

Display Import

File → Import Display... converts a caQtDM or Qt Designer .ui file into ADL. The same reusable converter is available as qtedm-convert. The source file is preserved, tab pages become file-backed child ADLs, and a versioned JSON report classifies every source object as mapped, approximated, omitted, or unsupported. Unsupported objects remain visible as labeled placeholders. Command-line exit status is 0 for a complete mapping, 2 for a completed conversion with warnings, and 1 for fatal failure.

qtedm-convert [--output display.adl] [--report report.json]
              [--source-copy preserved.source.ui] input.ui

-o is accepted as an alias for --output. With no output options, screen.ui produces screen.adl, screen.qtedm-conversion.json, and screen.source.ui beside the input. Input, output, report, and preserved-source paths must be distinct. Version 1 accepts one .ui input up to 64 MiB.

NTNDArray Image

NTNDArray Image is a QtEDM extension stored as qtedm_ndarray_image. It subscribes to a structured raw epics:nt/NTNDArray using an explicit pva:// channel and retains the typed data and dimensions.

• Data: Uncompressed 2-D mono and RGB1/RGB2/RGB3 layouts with all standard integer and floating-point scalar types.
• Interaction: Mouse-wheel zoom, drag pan, double-click or context-menu reset, pixel probe, rotation, flips, color maps, and automatic or manual intensity range.
• Reliability: Decode work runs outside the UI thread, only the newest pending frame is retained, and dropped frames, disconnects, malformed metadata, codecs, and memory-limit failures remain visible.
• Limits: Edit input/image memory and maximum dimension through QtEDM Extension Properties....
• Deferred: Compressed codecs and CA waveform-image compatibility are not supported in version 1.

Version 1 Local Plugins

QtEDM can load trusted local Qt plugins for custom display objects, data provider URI schemes, and archive providers. A plugin library must be installed with a versioned .qtedm-plugin.json sidecar in the executable's plugins directory or an absolute directory from QTEDM_PLUGIN_PATH. Remote plugin loading is not supported.

The loader requires the exact Qt major version, build architecture, compiler ABI, and QtEDM interface version. It also rejects duplicate plugin IDs, display type IDs, data schemes, and archive-provider IDs. Missing or incompatible display plugins appear as labeled placeholders, and their original qtedm_plugin nodes remain intact when the display is saved.

Plugin data-provider and display-widget writes pass through QtEDM's central write policy, so observe-only mode and auditing apply before the provider sees a put. See docs/QtEDM_Plugin_API.md in the source distribution for the complete interface, metadata, lifecycle, and packaging contract.

Declarative Property Rules

Select a built-in or plugin widget in EDIT mode and choose Declarative Property Rules... to attach a qtedm_rules block. Rules reuse the EPICS calculation grammar with typed inputs A through L. They may change only visibility, enabled state, text, foreground/background color, or geometry.

Each rule has a 1–60 Hz evaluation cap and explicit disconnect behavior. QtEDM detects duplicate IDs and dependency cycles, reports authoring errors, and restores original properties when EXECUTE mode ends. Version 1 is not a script engine: Python, JavaScript, filesystem access, process execution, network access, and PV writes are unavailable and rejected by validation.

Named Sessions

File → Save Session... stores the current top-level display paths, macros, window geometries, screen names, active tab IDs, and edit/execute state in a versioned JSON file below QStandardPaths::AppConfigLocation/sessions. Restore is always explicit: use File → Restore Session... or --session name. QtEDM never silently restores a prior layout.

Restore opens valid displays in EXECUTE mode, reports missing or renamed files and invalid records, and moves off-screen or oversized windows onto an available screen. A changed or missing active tab falls back to the display's configured default.

The expression_channel block stores a local calc node that publishes a soft PV for other widgets to consume. A typical block looks like this:

expression_channel {
  object {
    x=20
    y=66
    width=120
    height=40
  }
  variable="expr:sum"
  calc="A+B"
  channelA="src:pv1"
  channelB="src:pv2"
  channelC=""
  channelD=""
  initialValue=0
  eventSignal="onAnyChange"
  clr=30
  bclr=4
  precision=3
}

Expression-channel outputs are process-local to the running QtEDM instance. Other widgets subscribe to the result by using the variable value as their ordinary channel name.

PV Snapshots

File → Save PV Snapshot... captures the deduplicated channels used by the active display into a version-1 .qtedm-snapshot.json file. Scalar numeric, string, enum, character array, and numeric-array values retain provider, exact type, timestamp, units, limits, connection state, access state, and enum metadata. Capture warnings are reported instead of silently inventing unavailable values.

File → Compare / Restore PV Snapshot... first shows saved and current values side by side. Nothing is selected by default. Rows are eligible only when the current PV is connected and writable and its provider, exact type, value kind, enum choices, and limits remain compatible. After the user selects rows, QtEDM asks for confirmation and repeats every safety check immediately before each write.

Observe-only mode blocks restore, string-array restore is unsupported, and file, entry, and array sizes are bounded. Successful and failed restore attempts are audit logged. Snapshot files are local operational artifacts; review their contents and storage permissions before using them to change live equipment.