A Sonic Visualiser document consists of a set of data models, and also the visualisation layers used to display them. More...

#include <Document.h>

Inheritance diagram for Document:

Collaboration diagram for Document:

Classes
class	AddLayerCommand

class	LayerCreationHandler

struct	ModelRecord

class	RemoveLayerCommand

Public Types
typedef void *	LayerCreationAsyncHandle

Signals
void	layerAdded (Layer *)

void	layerRemoved (Layer *)

void	layerAboutToBeDeleted (Layer *)

void	layerInAView (Layer *, bool)

void	modelAdded (ModelId)

void	mainModelChanged (ModelId)

void	modelGenerationFailed (QString transformName, QString message)

void	modelGenerationWarning (QString transformName, QString message)

void	modelRegenerationFailed (QString layerName, QString transformName, QString message)

void	modelRegenerationWarning (QString layerName, QString transformName, QString message)

void	alignmentComplete (ModelId)

void	alignmentFailed (ModelId, QString message)

void	activity (QString)

Public Member Functions
	Document ()
	!! still need to handle command history, documentRestored/documentModified More...

virtual	~Document ()

Layer *	createLayer (LayerFactory::LayerType)
	Create and return a new layer of the given type, associated with no model. More...

Layer *	createMainModelLayer (LayerFactory::LayerType)
	Create and return a new layer of the given type, associated with the current main model (if appropriate to the layer type). More...

Layer *	createImportedLayer (ModelId)
	Create and return a new layer associated with the given model, and register the model as an imported model. More...

Layer *	createEmptyLayer (LayerFactory::LayerType)
	Create and return a new layer of the given type, with an appropriate empty model. More...

Layer *	createDerivedLayer (LayerFactory::LayerType, TransformId)
	Create and return a new layer of the given type, associated with the given transform name. More...

Layer *	createDerivedLayer (const Transform &, const ModelTransformer::Input &)
	Create and return a suitable layer for the given transform, running the transform and associating the resulting model with the new layer. More...

std::vector< Layer * >	createDerivedLayers (const Transforms &, const ModelTransformer::Input &)
	Create and return suitable layers for the given transforms, which must be identical apart from the output (i.e. More...

LayerCreationAsyncHandle	createDerivedLayersAsync (const Transforms &, const ModelTransformer::Input &, LayerCreationHandler *handler)
	Create suitable layers for the given transforms, which must be identical apart from the output (i.e. More...

void	cancelAsyncLayerCreation (LayerCreationAsyncHandle handle)
	Indicate that the async layer creation task associated with the given handle should be cancelled. More...

void	deleteLayer (Layer *, bool force=false)
	Delete the given layer, and also its associated model if no longer used by any other layer. More...

void	setMainModel (ModelId)
	Set the main model (the source for playback sample rate, etc) to the given wave file model. More...

ModelId	getMainModel ()
	Get the main model (the source for playback sample rate, etc). More...

std::vector< ModelId >	getTransformInputModels ()

bool	isKnownModel (ModelId) const
	Return true if the model id is known to be the main model or one of the other existing models that can be shown in a new layer. More...

ModelId	addDerivedModel (const Transform &transform, const ModelTransformer::Input &input, QString &returnedMessage)
	Add a derived model associated with the given transform, running the transform and returning the resulting model. More...

std::vector< ModelId >	addDerivedModels (const Transforms &transforms, const ModelTransformer::Input &input, QString &returnedMessage, AdditionalModelConverter *)

void	addAlreadyDerivedModel (const Transform &transform, const ModelTransformer::Input &input, ModelId outputModelToAdd)
	Add a derived model associated with the given transform. More...

void	addNonDerivedModel (ModelId)
	Add an imported model, i.e. More...

void	setModel (Layer *, ModelId)
	Associate the given model with the given layer. More...

void	setChannel (Layer *, int)
	Set the given layer to use the given channel of its model (-1 means all available channels). More...

void	addLayerToView (View , Layer )
	Add the given layer to the given view. More...

void	removeLayerFromView (View , Layer )
	Remove the given layer from the given view. More...

void	setAutoAlignment (bool on)
	Specify whether models added via addImportedModel should be automatically aligned against the main model if appropriate. More...

void	alignModels ()
	Generate alignments for all appropriate models against the main model. More...

void	realignModels ()
	Re-generate alignments for all appropriate models against the main model. More...

bool	isIncomplete () const
	Return true if any external files (most obviously audio) failed to be found on load, so that the document is incomplete compared to its saved description. More...

void	setIncomplete (bool i)

void	toXml (QTextStream &, QString indent, QString extraAttributes) const override

void	toXmlAsTemplate (QTextStream &, QString indent, QString extraAttributes) const

Static Public Member Functions
static bool	canAlign ()
	Return true if alignment is supported (i.e. More...

Protected Types
typedef std::map< Layer , std::set< View > >	LayerViewMap

typedef std::vector< Layer * >	LayerList
	And these are the layers. More...

Protected Slots
void	performDeferredAlignment (ModelId)

Protected Member Functions
void	releaseModel (ModelId model)

void	alignModel (ModelId, bool forceRecalculate=false)
	If model is suitable for alignment, align it against the main model and store the alignment in the model. More...

void	addAdditionalModel (ModelId)
	Add an extra derived model (returned at the end of processing a transform). More...

void	addToLayerViewMap (Layer , View )

void	removeFromLayerViewMap (Layer , View )

QString	getUniqueLayerName (QString candidate)

void	writeBackwardCompatibleDerivation (QTextStream &, QString, ModelId, const ModelRecord &) const

void	toXml (QTextStream &, QString, QString, bool asTemplate) const

void	writePlaceholderMainModel (QTextStream &, QString) const

std::vector< Layer * >	createLayersForDerivedModels (std::vector< ModelId >, QStringList names)

Protected Attributes
ModelId	m_mainModel
	The model that provides the underlying sample rate, etc. More...

std::map< ModelId, ModelRecord >	m_models

std::set< ModelId >	m_aggregateModels

std::set< ModelId >	m_alignmentModels

LayerViewMap	m_layerViewMap

LayerList	m_layers

bool	m_autoAlignment

Align *	m_align

bool	m_isIncomplete

Friends
class	AdditionalModelConverter
	Add derived models associated with the given set of related transforms, running the transforms and returning the resulting models. More...

Detailed Description

A Sonic Visualiser document consists of a set of data models, and also the visualisation layers used to display them.

Changes to the layers and their layout need to be stored and managed in much the same way as changes to the underlying data.

The document manages:

A main data Model, which provides the underlying sample rate and such like. This must be a WaveFileModel.
Any number of imported Model objects, which contain data without any requirement to remember where the data came from or how to regenerate it.
Any number of Model objects that were generated by a Transformer such as FeatureExtractionModelTransformer. For these, we also record the source model and the name of the transform used to generate the model so that we can regenerate it (potentially from a different source) on demand.
A flat list of Layer objects. Elsewhere, the GUI may distribute these across any number of View widgets. A layer may be viewable on more than one view at once, in principle. A layer refers to one model, but the same model can be in use in more than one layer.

The document does not manage the existence or structure of Pane and other view widgets. However, it does provide convenience methods for reference-counted command-based management of the association between layers and views (addLayerToView, removeLayerFromView).

Definition at line 71 of file Document.h.

Member Typedef Documentation

typedef void* Document::LayerCreationAsyncHandle

Definition at line 134 of file Document.h.

typedef std::map<Layer *, std::set<View *> > Document::LayerViewMap

protected

Definition at line 434 of file Document.h.

typedef std::vector<Layer *> Document::LayerList

protected

And these are the layers.

We also control the lifespans of these (usually through the commands used to add and remove them).

Definition at line 454 of file Document.h.

Constructor & Destructor Documentation

Document::Document ( )

!! still need to handle command history, documentRestored/documentModified

Definition at line 48 of file Document.cpp.

References alignmentComplete(), alignmentFailed(), m_align, and modelGenerationFailed().

Document::~Document ( )

virtual

!! Document should really own the command history. atm we

Definition at line 65 of file Document.cpp.

References deleteLayer(), m_aggregateModels, m_alignmentModels, m_layers, m_mainModel, m_models, and mainModelChanged().

Member Function Documentation

Layer * Document::createLayer ( LayerFactory::LayerType type )

Create and return a new layer of the given type, associated with no model.

The caller may set any model on this layer, but the model must also be registered with the document via the add-model methods below.

Definition at line 118 of file Document.cpp.

References getUniqueLayerName(), layerAdded(), and m_layers.

Referenced by createDerivedLayer(), createEmptyLayer(), createLayersForDerivedModels(), createMainModelLayer(), and SVFileReader::readLayer().

Layer * Document::createMainModelLayer ( LayerFactory::LayerType type )

Create and return a new layer of the given type, associated with the current main model (if appropriate to the layer type).

Definition at line 140 of file Document.cpp.

References createLayer(), m_mainModel, and setModel().

Referenced by MainWindowBase::openLayersFromRDF().

Layer * Document::createImportedLayer ( ModelId modelId )

Create and return a new layer associated with the given model, and register the model as an imported model.

!! for now, just use the first suitable layer type

!! and all channels

Definition at line 151 of file Document.cpp.

References addNonDerivedModel(), getUniqueLayerName(), layerAdded(), m_layers, setChannel(), and setModel().

Referenced by MainWindowBase::addOpenedAudioModel(), MainWindowBase::openLayer(), MainWindowBase::openLayersFromRDF(), and MainWindowBase::record().

Layer * Document::createEmptyLayer ( LayerFactory::LayerType type )

Create and return a new layer of the given type, with an appropriate empty model.

If the given type is not one for which an empty model can meaningfully be created, return 0.

Definition at line 189 of file Document.cpp.

References addNonDerivedModel(), createLayer(), m_mainModel, and setModel().

Referenced by MainWindowBase::insertInstantAt(), MainWindowBase::openImage(), and MainWindowBase::pasteRelative().

Layer * Document::createDerivedLayer	(	LayerFactory::LayerType	type,
		TransformId	transform
	)

Create and return a new layer of the given type, associated with the given transform name.

This method does not run the transform itself, nor create a model. The caller can safely add a model to the layer later, but note that all models used by a transform layer must be registered with the document using addDerivedModel below.

Definition at line 212 of file Document.cpp.

References createLayer(), and getUniqueLayerName().

Layer * Document::createDerivedLayer	(	const Transform &	transform,
		const ModelTransformer::Input &	input
	)

Create and return a suitable layer for the given transform, running the transform and associating the resulting model with the new layer.

Definition at line 228 of file Document.cpp.

References createDerivedLayers().

vector< Layer * > Document::createDerivedLayers	(	const Transforms &	transforms,
		const ModelTransformer::Input &	input
	)

Create and return suitable layers for the given transforms, which must be identical apart from the output (i.e.

must use the same plugin and configuration). The layers are returned in the same order as the transforms are supplied.

!! This identifier may be wrong!

Definition at line 241 of file Document.cpp.

References addDerivedModels(), createLayersForDerivedModels(), getUniqueLayerName(), modelGenerationFailed(), and modelGenerationWarning().

Referenced by createDerivedLayer().

Document::LayerCreationAsyncHandle Document::createDerivedLayersAsync	(	const Transforms &	transforms,
		const ModelTransformer::Input &	input,
		LayerCreationHandler *	handler
	)

Create suitable layers for the given transforms, which must be identical apart from the output (i.e.

must use the same plugin and configuration). This method returns after initialising the transformer process, and the layers are returned through a subsequent call to the provided handler (which must be non-null). The handle returned will be passed through to the handler callback.

!! This identifier may be wrong!

!! what to do with amc?

!! This identifier may be wrong!

!! what to do with amc?

Definition at line 324 of file Document.cpp.

References addDerivedModels(), AdditionalModelConverter, createLayersForDerivedModels(), getUniqueLayerName(), modelGenerationFailed(), modelGenerationWarning(), and AdditionalModelConverter::setPrimaryLayers().

Referenced by Document::LayerCreationHandler::~LayerCreationHandler().

void Document::cancelAsyncLayerCreation ( Document::LayerCreationAsyncHandle h )

Indicate that the async layer creation task associated with the given handle should be cancelled.

There is no guarantee about what this will mean, and the handler callback may still be called.

Definition at line 362 of file Document.cpp.

References AdditionalModelConverter::cancel().

Referenced by Document::LayerCreationHandler::~LayerCreationHandler().

void Document::deleteLayer	(	Layer *	layer,
		bool	force = `false`
	)

Delete the given layer, and also its associated model if no longer used by any other layer.

In general, this should be the only method used to delete layers – doing so directly is a bit of a social gaffe.

Definition at line 889 of file Document.cpp.

References layerAboutToBeDeleted(), layerRemoved(), m_layers, m_layerViewMap, and releaseModel().

Referenced by MainWindowBase::openImage(), SVFileReader::readLayer(), setMainModel(), Document::AddLayerCommand::~AddLayerCommand(), ~Document(), Document::LayerCreationHandler::~LayerCreationHandler(), and Document::RemoveLayerCommand::~RemoveLayerCommand().

void Document::setMainModel ( ModelId modelId )

Set the main model (the source for playback sample rate, etc) to the given wave file model.

This will regenerate any derived models that were based on the previous main model. The model must have been added to ModelById already, and Document will take responsibility for releasing it later.

!! We have a problem here if the number of channels in

Definition at line 421 of file Document.cpp.

References activity(), addDerivedModel(), alignModel(), Document::ModelRecord::channel, deleteLayer(), m_autoAlignment, m_layers, m_mainModel, m_models, mainModelChanged(), modelAdded(), modelRegenerationFailed(), modelRegenerationWarning(), setModel(), Document::ModelRecord::source, and Document::ModelRecord::transform.

Referenced by MainWindowBase::addOpenedAudioModel(), MainWindowBase::openLayersFromRDF(), SVFileReader::readModel(), MainWindowBase::record(), and Document::LayerCreationHandler::~LayerCreationHandler().

ModelId Document::getMainModel ( )

inline

Get the main model (the source for playback sample rate, etc).

Definition at line 195 of file Document.h.

References addDerivedModel(), getTransformInputModels(), isKnownModel(), and m_mainModel.

Referenced by MainWindowBase::getMainModelId(), SVFileReader::readDerivation(), and SVFileReader::readModel().

std::vector< ModelId > Document::getTransformInputModels ( )

!! This will pick up all models, including those that aren't visible...

Definition at line 1083 of file Document.cpp.

References m_mainModel, and m_models.

Referenced by getMainModel().

bool Document::isKnownModel ( ModelId modelId ) const

Return true if the model id is known to be the main model or one of the other existing models that can be shown in a new layer.

Definition at line 1108 of file Document.cpp.

References m_mainModel, and m_models.

Referenced by getMainModel().

ModelId Document::addDerivedModel	(	const Transform &	transform,
		const ModelTransformer::Input &	input,
		QString &	returnedMessage
	)

Add a derived model associated with the given transform, running the transform and returning the resulting model.

The model is added to ModelById before returning.

Definition at line 733 of file Document.cpp.

References addDerivedModels(), and m_models.

Referenced by SVFileReader::endElement(), getMainModel(), and setMainModel().

vector< ModelId > Document::addDerivedModels	(	const Transforms &	transforms,
		const ModelTransformer::Input &	input,
		QString &	returnedMessage,
		AdditionalModelConverter *	amc
	)

!! would be nice to short-circuit this – the version is !! static data, shouldn't have to construct a plugin for it !! (which may be expensive in Piper-world)

Definition at line 756 of file Document.cpp.

References addAlreadyDerivedModel().

Referenced by addDerivedModel(), createDerivedLayers(), and createDerivedLayersAsync().

void Document::addAlreadyDerivedModel	(	const Transform &	transform,
		const ModelTransformer::Input &	input,
		ModelId	outputModelToAdd
	)

Add a derived model associated with the given transform.

This is necessary to register any derived model that was not created by the document using createDerivedModel or createDerivedLayer. Document will take responsibility for releasing the model later.

Definition at line 604 of file Document.cpp.

References Document::ModelRecord::additional, Document::ModelRecord::channel, m_models, modelAdded(), Document::ModelRecord::source, and Document::ModelRecord::transform.

Referenced by addDerivedModels(), and SVFileReader::endElement().

void Document::addNonDerivedModel ( ModelId modelId )

Add an imported model, i.e.

any model (other than the main model) that has been created by any means other than as the output of a transform. This is necessary to register any imported model that is to be associated with a layer, and also to make sure that the model is released by the Document later. Aggregate models, alignment models, and miscellaneous temporary models should also be added in this way, unless the temporary models are large enough to need managing in a way that guarantees the shortest possible lifespan.

Definition at line 645 of file Document.cpp.

References Document::ModelRecord::additional, alignModel(), Document::ModelRecord::channel, m_aggregateModels, m_alignmentModels, m_autoAlignment, m_models, modelAdded(), and Document::ModelRecord::source.

Referenced by MainWindowBase::addOpenedAudioModel(), SVFileReader::addUnaddedModels(), createEmptyLayer(), createImportedLayer(), and MainWindowBase::record().

void Document::setModel	(	Layer *	layer,
		ModelId	modelId
	)

Associate the given model with the given layer.

The model must have already been registered using one of the addXXModel methods above.

Definition at line 951 of file Document.cpp.

References m_mainModel, m_models, and releaseModel().

Referenced by createEmptyLayer(), createImportedLayer(), createLayersForDerivedModels(), createMainModelLayer(), SVFileReader::readLayer(), and setMainModel().

void Document::setChannel	(	Layer *	layer,
		int	channel
	)

Set the given layer to use the given channel of its model (-1 means all available channels).

Definition at line 987 of file Document.cpp.

Referenced by createImportedLayer().

void Document::addLayerToView	(	View *	view,
		Layer *	layer
	)

Add the given layer to the given view.

If the layer is intended to show a particular model, the model should normally be set using setModel before this method is called.

Definition at line 993 of file Document.cpp.

References m_mainModel, and m_models.

Referenced by MainWindowBase::addOpenedAudioModel(), MainWindowBase::insertInstantAt(), MainWindowBase::openImage(), MainWindowBase::openLayer(), MainWindowBase::openLayersFromRDF(), MainWindowBase::pasteRelative(), SVFileReader::readLayer(), and MainWindowBase::record().

void Document::removeLayerFromView	(	View *	view,
		Layer *	layer
	)

Remove the given layer from the given view.

Ownership of the layer is transferred to a command object on the undo stack, and the layer will be deleted when the undo stack is pruned.

Definition at line 1018 of file Document.cpp.

Referenced by MainWindowBase::addOpenedAudioModel(), MainWindowBase::deleteCurrentLayer(), MainWindowBase::deleteCurrentPane(), and MainWindowBase::paneDeleteButtonClicked().

bool Document::canAlign ( )

static

Return true if alignment is supported (i.e.

if the necessary plugin is found).

Definition at line 1118 of file Document.cpp.

void Document::setAutoAlignment ( bool on )

inline

Specify whether models added via addImportedModel should be automatically aligned against the main model if appropriate.

Definition at line 287 of file Document.h.

References alignModels(), m_autoAlignment, and realignModels().

Referenced by MainWindowBase::createDocument().

void Document::alignModels ( )

Generate alignments for all appropriate models against the main model.

Existing alignments will not be re-calculated unless the main model has changed since they were calculated.

Definition at line 1201 of file Document.cpp.

References alignModel(), m_mainModel, and m_models.

Referenced by setAutoAlignment().

void Document::realignModels ( )

Re-generate alignments for all appropriate models against the main model.

Existing alignments will be re-calculated.

Definition at line 1210 of file Document.cpp.

References alignModel(), m_mainModel, and m_models.

Referenced by setAutoAlignment().

bool Document::isIncomplete ( ) const

inline

Return true if any external files (most obviously audio) failed to be found on load, so that the document is incomplete compared to its saved description.

Definition at line 307 of file Document.h.

References m_isIncomplete.

Referenced by MainWindowBase::openSession().

void Document::setIncomplete ( bool i )

inline

Definition at line 309 of file Document.h.

References activity(), alignmentComplete(), alignmentFailed(), alignModel(), layerAboutToBeDeleted(), layerAdded(), layerInAView(), layerRemoved(), m_isIncomplete, mainModelChanged(), modelAdded(), modelGenerationFailed(), modelGenerationWarning(), modelRegenerationFailed(), modelRegenerationWarning(), performDeferredAlignment(), releaseModel(), toXml(), and toXmlAsTemplate().