OverlayBase and OverlayStorage

OverlayBase is the abstract base class for every plot overlay in Blackchirp. Each overlay carries a display label, a source and destination file path, a plot panel assignment, and a set of transformations (X/Y offset, Y scale) applied on top of the raw data. Optional frequency-range clips restrict the visible frequency window independently of the transformation. Visibility is controlled by setEnabled(); the enabled state is synchronized with the CurveAppearance metadata so that the plot widget reflects the change without an additional signal.

The OverlayType enumerator is the type discriminator that identifies each concrete subclass:

BCExperiment — an FT spectrum read from a Blackchirp experiment file (BCExpOverlay).
Catalog — a spectroscopic line catalog from SPCAT, XIAM, or a compatible program (CatalogOverlay). Optional Lorentzian or Gaussian lineshape convolution produces a simulated absorption profile for direct comparison with a measured FT spectrum.
GenericXY — an arbitrary two-column data file (CSV, TSV, etc.) (GenericXYOverlay).

The three concrete subclasses are defined in overlaytypes.h; their member documentation appears in the API Reference section below. The user-facing overlay workflow is described in Overlays.

OverlayStorage

OverlayStorage manages the persistent collection of overlays for a single experiment. It maintains two separate in-memory collections: persistent overlays that are written to disk under <experimentPath>/overlays/, and preview overlays that exist only in memory. Write operations are dispatched asynchronously via QtConcurrent; the signals overlayWriteCompleted() and overlayWriteFailed() report outcomes on the object’s own thread. waitForPendingWrites() coordinates shutdown with in-flight background operations.

Preview overlays bypass all disk I/O. detachPreviewOverlay() converts a preview overlay to a persistent one, scheduling the initial background write.

OverlayStorage inherits DataStorageBase for compatibility with the experiment data pipeline; only save() has a non-trivial implementation. The other DataStorageBase methods (advance, start, finish) are no-ops.

API Reference

class OverlayBase

Abstract base class for all plot overlays.

OverlayBase defines the common data model shared by every overlay type: transformations (X/Y offset, Y scale), frequency-range clipping, visibility, plot assignment, and curve appearance metadata. Concrete subclasses implement the data source (a Blackchirp experiment FT, a spectroscopic catalog, or a generic XY file) by overriding the pure-virtual members.

The type discriminator OverlayType identifies each concrete kind and drives the factory in OverlayStorage. The three values are:

BCExperiment — an FT spectrum taken from a Blackchirp experiment file.
Catalog — a spectroscopic line-catalog from SPCAT, XIAM, or similar.
GenericXY — an arbitrary two-column data file (CSV, TSV, etc.).

xyData() applies X/Y offsets and frequency-range filtering on the raw data returned by the pure-virtual _xyData() and caches the result; the cache is invalidated whenever an offset or frequency-limit setter is called.

The preview flag suppresses disk I/O, allowing the UI to create and display temporary overlays before the user commits them.

Subclassed by BCExpOverlay, CatalogOverlay, GenericXYOverlay

Public Types

enum OverlayType

Discriminator tag identifying the concrete overlay subclass.

Values:

enumerator BCExperiment: FT spectrum from a Blackchirp experiment file.

enumerator Catalog: Spectroscopic line catalog (SPCAT, XIAM, etc.).

enumerator GenericXY: Arbitrary two-column XY data file.

Public Functions

OverlayBase(OverlayType type)

Construct an overlay of the given type.

Parameters:: type – The OverlayType discriminator for this instance.

virtual ~OverlayBase() = default

Virtual destructor.

Required because OverlayBase is an abstract polymorphic base destroyed through base-class pointers (see the std::shared_ptr usage in OverlayTableModel and friends — shared_ptr’s type erasure happens to dispatch correctly today, but a future unique_ptr<OverlayBase> or a raw delete bp; would silently skip the derived destructor without this).

QVector<QPointF> xyData() const

Return the transformed and frequency-filtered XY data, using a cached copy when valid.

Applies d_xOffset, d_yScale, d_yOffset, and the optional frequency clip limits to the raw data from _xyData(). The result is cached until any transformation parameter changes.

QString getLabel() const: Return the user-visible overlay label.

QString getSourceFile() const: Return the path to the original source data file.

QString getDestFile() const: Return the path to the overlay’s on-disk destination file.

QString getPlotId() const: Return the plot panel identifier this overlay is assigned to.

QString getComment() const: Return the free-text annotation for this overlay.

double getYScale() const: Return the multiplicative Y-axis scaling factor.

double getYOffset() const: Return the additive Y-axis offset.

double getXOffset() const: Return the additive X-axis offset.

bool getMinFreqEnabled() const: Return true if the low-frequency clip is active.

double getMinFreqValue() const: Return the low-frequency clip value in MHz.

bool getMaxFreqEnabled() const: Return true if the high-frequency clip is active.

double getMaxFreqValue() const: Return the high-frequency clip value in MHz.

bool getEnabled() const: Return true if the overlay is visible on the plot.

double yMax() const

Return the maximum absolute raw Y value (before scale/offset are applied).

Triggers a cache refresh if the cache is stale.

inline OverlayType type() const: Return the OverlayType discriminator for this instance.

inline QString errorString() const: Return the most recent error description, or an empty string if none.

inline bool isModified() const: Return true if any property has been changed since the last save().

inline bool isPreview() const: Return true if this overlay is in preview (non-persistent) mode.

QVariant getCurveMetadata(const QString &key) const

Return the curve metadata value for key, or an invalid QVariant if absent.

Parameters:: key – Metadata key (e.g. a CurveKey constant).

void setCurveMetadata(const QString &key, const QVariant &value)

Set a curve metadata value and mark the overlay modified.

Parameters:

key – Metadata key.
value – Value to store.

void setLabel(const QString &newlabel): Set the user-visible label and mark the overlay modified.

void setSourceFile(const QString &newsourceFile): Set the source data file path and mark the overlay modified.

void setDestFile(const QString &newdestFile): Set the on-disk destination file path and mark the overlay modified.

void setPlotId(const QString &newplotId): Set the plot panel identifier and mark the overlay modified.

void setComment(const QString &newcomment): Set the free-text annotation and mark the overlay modified.

void setYScale(double newyScale): Set the multiplicative Y-axis scale and mark the overlay modified.

void setYOffset(double newyOffset): Set the additive Y-axis offset and mark the overlay modified.

void setXOffset(double newxOffset)

Set the additive X-axis offset, invalidate the cache, and mark modified.

Parameters:: newxOffset – New X offset value.

void setMinFreqLimit(bool enabled, double value)

Set the low-frequency clip, invalidate the cache, and mark modified.

Parameters:

enabled – true to activate the clip.
value – Clip value in MHz.

void setMaxFreqLimit(bool enabled, double value)

Set the high-frequency clip, invalidate the cache, and mark modified.

Parameters:

enabled – true to activate the clip.
value – Clip value in MHz.

void setEnabled(bool enabled)

Set overlay visibility, update curve metadata, and mark modified.

Parameters:: enabled – true to make the overlay visible on the plot.

void setPreview(bool preview)

Set preview mode; marks the overlay modified when transitioning out of preview.

In preview mode, save() is a no-op and no data is written to disk. Clearing the preview flag (setting it to false) marks the overlay as modified so that the next save() writes it to disk.

Parameters:: preview – true to enable preview mode.

void save()

Write the overlay to its destination file and clear the modified flag.

A no-op when preview mode is active.

Protected Functions

inline void setModified(bool modified = true)

Set or clear the modified flag.

Parameters:: modified – New modified state; defaults to true.

virtual void readFromDest() = 0

Load data from the overlay’s destination file.

Called by OverlayStorage when reading an existing overlay from disk. Implementations should populate the internal data structures from the file at d_destFile.

virtual void writeToDest() = 0

Write data to the overlay’s destination file.

Called by save() when the overlay is not in preview mode. Implementations should serialize their data to d_destFile.

virtual void _storeMetadata(std::map<QString, QVariant, std::less<>> &m) = 0

Store subclass-specific metadata into the settings map.

Called during save()/storeMetadata() to allow each subclass to add its own key-value pairs to the shared settings map before it is written to the settings CSV.

Parameters:: m – The metadata map to populate.

virtual void _retrieveMetadata(const std::map<QString, QVariant, std::less<>> &m) = 0

Restore subclass-specific metadata from the settings map.

Called during OverlayStorage load to allow each subclass to extract its own key-value pairs from the shared settings map.

Parameters:: m – The metadata map read from the settings CSV.

void invalidateCache()

Invalidate the filtered XY data cache.

Must be called by any setter that changes a parameter affecting the output of xyData() (offsets, frequency limits).

Protected Attributes

QString d_errorString: Most recent error description; empty when no error.

Private Functions

virtual QVector<QPointF> _xyData() const = 0

Return the raw XY data for this overlay (before offset/filter transforms).

Must be implemented by each concrete subclass to return the underlying data points. The base-class xyData() applies transformations on top of this result.

void storeMetadata(std::map<QString, QVariant, std::less<>> &m)

void retrieveMetadata(const std::map<QString, QVariant, std::less<>> &m)

Private Members

OverlayType d_type

QString d_label = {""}

QString d_sourceFile = {""}

QString d_destFile = {""}

QString d_plotId = {""}

QString d_comment = {""}

double d_yScale = {1.0}

double d_yOffset = {0.0}

double d_xOffset = {0.0}

bool d_minFreqEnabled = {false}

bool d_maxFreqEnabled = {false}

double d_minFreqValue = {0.0}

double d_maxFreqValue = {1000.0}

bool d_enabled = {true}

bool d_preview = {false}

bool d_modified = {false}

std::map<QString, QVariant, std::less<>> d_curveMetadata

mutable QVector<QPointF> d_cachedFilteredData

mutable bool d_cacheValid = {false}

mutable double d_cachedYMax = {0.0}

Friends

friend class OverlayStorage

friend class OverlayMetadataStorage

friend class UnifiedOverlayWidget

class BCExpOverlay : public OverlayBase 

OverlayBase subclass for FT spectra from Blackchirp experiment files.

BCExpOverlay stores an Ft object that was produced by FtWorker and serializes it to the overlay destination file. The raw XY data is derived from the frequency axis and amplitude vector of the stored Ft.

See also

OverlayBase, Ft

Public Functions

BCExpOverlay(): Construct a BCExperiment-type overlay.

void setFtData(const Ft &ftData)

Set the Ft data for this overlay.

Parameters:: ftData – Ft object to store.

Ft getFtData() const: Return the stored Ft object.

Protected Functions

virtual void readFromDest() override: Load Ft data from the destination file.

virtual void writeToDest() override: Write Ft data to the destination file.

virtual void _storeMetadata(std::map<QString, QVariant, std::less<>> &m) override: Store FT-specific metadata fields into the settings map.

virtual void _retrieveMetadata(const std::map<QString, QVariant, std::less<>> &m) override: Restore FT-specific metadata fields from the settings map.

Private Functions

virtual QVector<QPointF> _xyData() const override: Return XY data derived from the stored Ft object.

Private Members

Ft d_ft: The stored FT spectrum.

class CatalogOverlay : public OverlayBase 

OverlayBase subclass for spectroscopic line catalogs with optional lineshape convolution.

CatalogOverlay loads transition data from a catalog file produced by SPCAT, XIAM, or a compatible program. When convolution is enabled the raw stick spectrum is convolved with a Lorentzian or Gaussian lineshape on a user-defined frequency grid to produce a simulated absorption profile that can be compared directly with a measured FT spectrum.

Convolution is computationally intensive; the class provides a background-operation cache (Invalid → Pending → Valid) and a ProgressCallback mechanism so callers can monitor and cancel long runs.

See also

OverlayBase, CatalogData

Public Types

enum LineshapeType

Lineshape function used when convolving the stick spectrum.

Values:

enumerator Lorentzian: Lorentzian (Cauchy) profile.

enumerator Gaussian: Gaussian profile.

using ProgressCallback = std::function<bool(int percentage, const QString &message)>

Callback type for progress reporting during chunked convolution.

The callback receives a percentage (0–100) and a status message string. Return true to continue processing or false to cancel.

Public Functions

CatalogOverlay(): Construct a Catalog-type overlay.

CatalogData catalogData() const: Return the loaded catalog data.

void setCatalogData(const CatalogData &data)

Replace the catalog data and mark the overlay modified.

Parameters:: data – New catalog data.

bool convolutionEnabled() const: Return true if lineshape convolution is active.

void setConvolutionEnabled(bool enabled)

Enable or disable lineshape convolution and mark modified.

Parameters:: enabled – true to enable convolution.

LineshapeType lineshapeType() const: Return the active lineshape type.

void setLineshapeType(LineshapeType type)

Set the lineshape type and mark modified.

Parameters:: type – Lorentzian or Gaussian.

double linewidth() const: Return the convolution linewidth FWHM in kHz.

void setLinewidth(double width)

Set the convolution linewidth FWHM in kHz and mark modified.

Parameters:: width – FWHM in kHz.

double convolutionMinFreq() const: Return the lower bound of the convolution frequency range in MHz.

double convolutionMaxFreq() const: Return the upper bound of the convolution frequency range in MHz.

void setConvolutionFreqRange(double minFreq, double maxFreq)

Set the convolution frequency range and mark modified.

Parameters:

minFreq – Lower bound in MHz.
maxFreq – Upper bound in MHz.

int numConvolutionPoints() const: Return the number of points in the convolution frequency grid.

void setNumConvolutionPoints(int numPoints)

Set the number of convolution grid points and mark modified.

Parameters:: numPoints – Desired grid size.

double calculatePointSpacing() const: Return the spacing between convolution grid points in MHz.

double filterMinFreq() const: Return the lower bound of the display filter range in MHz.

double filterMaxFreq() const: Return the upper bound of the display filter range in MHz.

void setFilterRange(double minFreq, double maxFreq)

Set the display filter frequency range and mark modified.

Parameters:

minFreq – Lower bound in MHz.
maxFreq – Upper bound in MHz.

void setConvolutionSettings(bool enabled, LineshapeType lineshape, double linewidth, double minFreq, double maxFreq, int numPoints)

Set all convolution parameters in a single call and mark modified.

Parameters:

enabled – Enable convolution.
lineshape – Lineshape type.
linewidth – FWHM in kHz.
minFreq – Lower bound of convolution range in MHz.
maxFreq – Upper bound of convolution range in MHz.
numPoints – Number of convolution grid points.

QVector<QPointF> generateConvolvedSpectrum() const

Generate the convolved spectrum from the loaded catalog data.

Returns:: Vector of (frequency MHz, intensity) points.

QVector<QPointF> generateConvolvedSpectrum(ProgressCallback progressCallback) const

Generate the convolved spectrum with progress reporting.

Parameters:: progressCallback – Callback invoked after each chunk; return false to cancel.
Returns:: Vector of (frequency MHz, intensity) points, or empty if cancelled.

void invalidateConvolutionCache(): Invalidate the convolution cache, forcing recomputation on next access.

void setCachePending(): Mark the convolution cache as pending (background operation in progress).

void setCacheValid(const QVector<QPointF> &convolvedData)

Mark the convolution cache as valid and store the result.

Parameters:: convolvedData – Computed convolution result to cache.

bool isCacheValid() const: Return true if the convolution cache holds a valid result.

bool hasConvolvedData() const: Return true if the cache is in the Valid state and contains data.

Protected Functions

virtual void readFromDest() override: Load catalog data from the destination file.

virtual void writeToDest() override: Write catalog data to the destination file.

virtual void _storeMetadata(std::map<QString, QVariant, std::less<>> &m) override: Store catalog-specific metadata fields into the settings map.

virtual void _retrieveMetadata(const std::map<QString, QVariant, std::less<>> &m) override: Restore catalog-specific metadata fields from the settings map.

Private Types

enum class CacheState

Values:

enumerator Invalid

enumerator Pending

enumerator Valid

Private Functions

virtual QVector<QPointF> _xyData() const override: Return the convolved spectrum (or raw sticks if convolution is disabled).

double lorentzianProfile(double x, double x0, double fwhmKHz) const

double gaussianProfile(double x, double x0, double fwhmKHz) const

int calculateChunkSize(int numConvolutionPoints, int numTransitions) const

Private Members

CatalogData d_catalogData

bool d_convolutionEnabled = {false}

LineshapeType d_lineshapeType = {Lorentzian}

double d_linewidth = {100.0}

double d_convolutionMinFreq = {0.0}

double d_convolutionMaxFreq = {1000.0}

int d_numConvolutionPoints = {1000}

double d_filterMinFreq = {0.0}

double d_filterMaxFreq = {1000.0}

mutable QVector<QPointF> d_convolvedCache

mutable CacheState d_cacheState = {CacheState::Invalid}

class GenericXYOverlay : public OverlayBase 

OverlayBase subclass for arbitrary two-column XY data files.

GenericXYOverlay parses delimited text files (CSV, TSV, space-separated, etc.) with configurable delimiter, header line count, and column indices. A separate display filter range allows restricting the visible X range independently of the frequency clipping applied by the base class.

See also

OverlayBase

Public Types

enum DelimiterType

Delimiter type used when parsing the data file.

Stored as an enum to avoid embedding literal delimiter characters in the settings CSV where commas and semicolons have structural meaning.

Values:

enumerator Comma: Comma-separated values.

enumerator Tab: Tab-separated values.

enumerator Space: Single-space-separated values.

enumerator Semicolon: Semicolon-separated values.

enumerator Whitespace: Any run of whitespace (greedy split).

Public Functions

GenericXYOverlay(): Construct a GenericXY-type overlay.

QVector<QPointF> rawData() const: Return the raw parsed data points before base-class transformations.

void setRawData(const QVector<QPointF> &data)

Replace the raw data and update cached statistics.

Parameters:: data – New XY data points.

QString delimiter() const: Return the delimiter string used for parsing.

void setDelimiter(const QString &delim)

Set the delimiter string and mark modified.

Parameters:: delim – Delimiter string (e.g. “,”, “\t”).

int headerLines() const: Return the number of header lines skipped when parsing.

void setHeaderLines(int lines)

Set the number of header lines and mark modified.

Parameters:: lines – Number of lines to skip.

int xColumn() const: Return the zero-based index of the X data column.

int yColumn() const: Return the zero-based index of the Y data column.

void setDataColumns(int xCol, int yCol)

Set the X and Y column indices and mark modified.

Parameters:

xCol – Zero-based X column index.
yCol – Zero-based Y column index.

QStringList columnNames() const: Return the column names parsed from the header, if any.

void setColumnNames(const QStringList &names)

Set the column name list and mark modified.

Parameters:: names – Column names in order.

int dataPointCount() const: Return the number of data points loaded.

double xMin() const: Return the minimum X value in the loaded data.

double xMax() const: Return the maximum X value in the loaded data.

double yMin() const: Return the minimum Y value in the loaded data.

double yMax() const: Return the maximum Y value in the loaded data.

QPair<double, double> xRange() const: Return the (min, max) X range of the loaded data.

QPair<double, double> yRange() const: Return the (min, max) Y range of the loaded data.

double filterMinX() const: Return the lower bound of the display filter range.

double filterMaxX() const: Return the upper bound of the display filter range.

void setFilterRange(double minX, double maxX)

Set the display filter range and mark modified.

Parameters:

minX – Lower filter bound.
maxX – Upper filter bound.

Protected Functions

virtual void readFromDest() override: Load XY data from the destination file.

virtual void writeToDest() override: Write XY data to the destination file.

virtual void _storeMetadata(std::map<QString, QVariant, std::less<>> &m) override: Store GenericXY-specific metadata fields into the settings map.

virtual void _retrieveMetadata(const std::map<QString, QVariant, std::less<>> &m) override: Restore GenericXY-specific metadata fields from the settings map.

Private Functions

virtual QVector<QPointF> _xyData() const override: Return the raw XY data (no transformation applied).

void updateStatistics()

DelimiterType stringToDelimiterType(const QString &delimiter) const

QString delimiterTypeToString(DelimiterType type) const

Private Members

QVector<QPointF> d_rawData

QString d_delimiter = {","}

int d_headerLines = {0}

int d_xColumn = {0}

int d_yColumn = {1}

QStringList d_columnNames

int d_dataPoints = {0}

double d_xMin = {0.0}

double d_xMax = {0.0}

double d_yMin = {0.0}

double d_yMax = {0.0}

double d_filterMinX = {0.0}

double d_filterMaxX = {1000.0}

class OverlayStorage : public QObject, public DataStorageBase 

Manages the persistent collection of overlays for a single experiment.

OverlayStorage maintains two separate collections of OverlayBase objects: a persistent map of overlays that are written to disk under <experimentPath>/overlays/, and a preview map of temporary overlays that exist only in memory. Each persistent overlay occupies two files: a data file and a settings CSV, both named from the sanitized overlay label.

Write operations are dispatched asynchronously via QtConcurrent so that the calling thread is not blocked during I/O. The signals overlayWriteCompleted() and overlayWriteFailed() report completion on the object’s thread. hasPendingWrites() and waitForPendingWrites() let callers coordinate with the background tasks when needed (e.g. before closing the experiment).

Preview overlays bypass all disk I/O and are managed separately through addPreviewOverlay(), removePreviewOverlay(), detachPreviewOverlay(), and clearAllPreviews(). Detaching converts a preview overlay to a persistent one by clearing its preview flag and adding it to the persistent map.

OverlayStorage inherits DataStorageBase for interface compatibility with the experiment data pipeline; only save() has a non-trivial implementation — advance(), start(), and finish() are no-ops.

See also

OverlayBase, DataStorageBase

Public Functions

OverlayStorage(int number, const QString &path)

Construct the storage manager for a specific experiment.

Parameters:

number – Experiment number; used to locate the experiment directory.
path – Base path of the experiment data directory.

~OverlayStorage()

bool loadOverlay(const QString &fileBase, OverlayBase::OverlayType t)

Load an existing overlay from disk into the persistent collection.

Constructs the appropriate OverlayBase subclass for t, sets its source and destination paths from fileBase, reads the settings CSV, and calls readFromDest() to populate its data.

Parameters:

fileBase – Sanitized base name of the overlay files (without extension).
t – OverlayType discriminator identifying the subclass to create.

Returns:

true if the overlay was loaded and added successfully.

bool addOverlay(std::shared_ptr<OverlayBase> overlay)

Add an externally created overlay to the persistent collection.

Schedules an asynchronous write of the overlay data and settings. Emits overlayAdded() on success.

Parameters:: overlay – Shared pointer to the overlay to store.
Returns:: true if the overlay was accepted (label is unique and valid).

QVector<std::shared_ptr<OverlayBase>> getAllOverlays() const: Return all persistent overlays as a vector of shared pointers.

bool removeOverlay(const QString &label)

Remove the persistent overlay with the given label and delete its files.

Emits overlayRemoved() if the overlay existed.

Parameters:: label – User-visible label of the overlay to remove.
Returns:: true if the overlay was found and removed.

bool renameOverlay(const QString &currentLabel, const QString &newLabel)

Rename a persistent overlay and its associated files.

Parameters:

currentLabel – Existing label.
newLabel – New label; must be unique and valid.

Returns:

true if the rename succeeded.

bool hasPendingWrites() const: Return true if any background write operations are still in flight.

void waitForPendingWrites(): Block until all pending background write operations complete.

int pendingWriteCount() const: Return the number of write operations currently in flight.

void saveOverlayMetadata(std::shared_ptr<OverlayBase> overlay)

Asynchronously write only the settings metadata for a specific overlay.

Used when curve appearance or other non-data settings change without requiring a full data rewrite.

Parameters:: overlay – Overlay whose settings should be saved.

bool addPreviewOverlay(std::shared_ptr<OverlayBase> overlay)

Add a preview (non-persistent) overlay to the preview collection.

Parameters:: overlay – Shared pointer to the preview overlay.
Returns:: true if the overlay was accepted.

bool removePreviewOverlay(const QString &label)

Remove a preview overlay by label.

Parameters:: label – Label of the preview overlay to remove.
Returns:: true if the overlay was found and removed.

bool detachPreviewOverlay(const QString &label)

Convert a preview overlay to a persistent overlay.

Clears the preview flag on the overlay and moves it from the preview collection to the persistent collection, scheduling a background write.

Parameters:: label – Label of the preview overlay to detach.
Returns:: true if the overlay was found and detached successfully.

bool detachPreviewOverlay(const std::shared_ptr<OverlayBase> &overlay)

Detach a preview overlay identified by object identity.

Equivalent to detachPreviewOverlay(const QString&) but matches the preview entry by shared_ptr rather than label. The label-keyed form misses when the overlay’s label changed after it was registered as a preview, which then lets clearAllPreviews() emit overlayRemoved for the just-promoted overlay and tear its curve back off the plot.

Parameters:: overlay – The preview overlay instance to detach.
Returns:: true if a matching preview entry was found and removed.

void clearAllPreviews(): Remove all preview overlays from the preview collection.

QVector<std::shared_ptr<OverlayBase>> getAllPreviewOverlays() const: Return all preview overlays as a vector of shared pointers.

inline virtual void advance() override: No-op; OverlayStorage does not use segment-advance semantics.

virtual void save() override: Write the overlay metadata index (overlays.csv) to disk.

inline virtual void start() override: No-op; OverlayStorage does not require explicit start.

inline virtual void finish() override: No-op; OverlayStorage does not require explicit finish.

Signals

void overlayAdded(std::shared_ptr<OverlayBase> overlay): Emitted when an overlay is successfully added to the persistent collection.

void overlayRemoved(std::shared_ptr<OverlayBase> overlay): Emitted when an overlay is removed from the persistent collection.

void overlayWriteCompleted(std::shared_ptr<OverlayBase> overlay): Emitted when a background write operation completes successfully.

void overlayWriteFailed(std::shared_ptr<OverlayBase> overlay, QString error): Emitted when a background write operation fails.

void pendingWritesChanged(int count): Emitted when the number of in-flight write operations changes.

Private Functions

std::shared_ptr<OverlayBase> createOverlayObject(OverlayBase::OverlayType type)

QString sanitizeLabel(const QString &label) const

QString getOverlayDataPath(const QString &sanitizedLabel) const

QString getOverlaySettingsPath(const QString &sanitizedLabel) const

void addVersionMetadata(std::map<QString, QVariant, std::less<>> &metadata) const

bool validateOverlayLabel(const QString &label) const

void onWriteCompleted(const QString &label, bool success, const QString &error = QString())

Private Members

std::map<QString, std::shared_ptr<OverlayBase>, std::less<>> d_overlays

std::map<QString, QFuture<void>, std::less<>> d_pendingWrites

std::map<QString, std::shared_ptr<OverlayBase>, std::less<>> d_previewOverlays