svapp  1.9
Document Class Reference

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

#include <Document.h>

List of all members.

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 (Model *)
void mainModelChanged (WaveFileModel *)
void modelAboutToBeDeleted (Model *)
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 alignmentFailed (QString transformName, QString message)
void activity (QString)

Public Member Functions

 Document ()
 !! still need to handle command history, documentRestored/documentModified
virtual ~Document ()
Layer * createLayer (LayerFactory::LayerType)
 Create and return a new layer of the given type, associated with no model.
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).
Layer * createImportedLayer (Model *)
 Create and return a new layer associated with the given model, and register the model as an imported model.
Layer * createEmptyLayer (LayerFactory::LayerType)
 Create and return a new layer of the given type, with an appropriate empty model.
Layer * createDerivedLayer (LayerFactory::LayerType, TransformId)
 Create and return a new layer of the given type, associated with the given transform name.
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.
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.
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.
void cancelAsyncLayerCreation (LayerCreationAsyncHandle handle)
 Indicate that the async layer creation task associated with the given handle should be cancelled.
void deleteLayer (Layer *, bool force=false)
 Delete the given layer, and also its associated model if no longer used by any other layer.
void setMainModel (WaveFileModel *)
 Set the main model (the source for playback sample rate, etc) to the given wave file model.
WaveFileModel * getMainModel ()
 Get the main model (the source for playback sample rate, etc).
const WaveFileModel * getMainModel () const
 Get the main model (the source for playback sample rate, etc).
std::vector< Model * > getTransformInputModels ()
bool isKnownModel (const Model *) const
Model * 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.
std::vector< Model * > addDerivedModels (const Transforms &transforms, const ModelTransformer::Input &input, QString &returnedMessage, AdditionalModelConverter *)
void addAlreadyDerivedModel (const Transform &transform, const ModelTransformer::Input &input, Model *outputModelToAdd)
 Add a derived model associated with the given transform.
void addImportedModel (Model *)
 Add an imported (non-derived, non-main) model.
void setModel (Layer *, Model *)
 Associate the given model with the given layer.
void setChannel (Layer *, int)
 Set the given layer to use the given channel of its model (-1 means all available channels).
void addLayerToView (View *, Layer *)
 Add the given layer to the given view.
void removeLayerFromView (View *, Layer *)
 Remove the given layer from the given view.
void setAutoAlignment (bool on)
 Specify whether models added via addImportedModel should be automatically aligned against the main model if appropriate.
void alignModels ()
 Generate alignments for all appropriate models against the main model.
void toXml (QTextStream &, QString indent, QString extraAttributes) const
void toXmlAsTemplate (QTextStream &, QString indent, QString extraAttributes) const

Static Public Member Functions

static bool canAlign ()
 Return true if alignment is supported (i.e.

Protected Types

typedef std::map< Model
*, ModelRecord
ModelMap
typedef std::map< Layer
*, std::set< View * > > 
LayerViewMap
typedef std::set< Layer * > LayerSet
 And these are the layers.

Protected Member Functions

void releaseModel (Model *model)
void alignModel (Model *)
 If model is suitable for alignment, align it against the main model and store the alignment in the model.
void addAdditionalModel (Model *)
 Add an extra derived model (returned at the end of processing a transform).
void addToLayerViewMap (Layer *, View *)
void removeFromLayerViewMap (Layer *, View *)
QString getUniqueLayerName (QString candidate)
void writeBackwardCompatibleDerivation (QTextStream &, QString, Model *, const ModelRecord &) const
void toXml (QTextStream &, QString, QString, bool asTemplate) const
void writePlaceholderMainModel (QTextStream &, QString) const
std::vector< Layer * > createLayersForDerivedModels (std::vector< Model * >, QStringList names)

Static Protected Member Functions

static TransformId getAlignmentTransformName ()

Protected Attributes

WaveFileModel * m_mainModel
 The model that provides the underlying sample rate, etc.
ModelMap m_models
LayerViewMap m_layerViewMap
LayerSet m_layers
bool m_autoAlignment

Friends

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

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 68 of file Document.h.


Member Typedef Documentation

Definition at line 131 of file Document.h.

typedef std::map<Model *, ModelRecord> Document::ModelMap [protected]

Definition at line 354 of file Document.h.

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

Definition at line 400 of file Document.h.

typedef std::set<Layer *> Document::LayerSet [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 422 of file Document.h.


Constructor & Destructor Documentation

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

Definition at line 50 of file Document.cpp.

References modelAboutToBeDeleted().

Document::~Document ( ) [virtual]

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

Definition at line 59 of file Document.cpp.

References deleteLayer(), m_layers, m_mainModel, m_models, mainModelChanged(), and modelAboutToBeDeleted().


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 111 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 131 of file Document.cpp.

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

Referenced by MainWindowBase::openLayersFromRDF().

Layer * Document::createImportedLayer ( Model *  model)

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 140 of file Document.cpp.

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

Referenced by MainWindowBase::openAudio(), MainWindowBase::openLayer(), and MainWindowBase::openLayersFromRDF().

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 176 of file Document.cpp.

References addImportedModel(), 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 197 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 211 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!

!! This identifier may be wrong!

Definition at line 222 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, and may be also used for cancelling the task.

!! This identifier may be wrong!

!! what to do with amc?

!! This identifier may be wrong!

!! what to do with amc?

Definition at line 305 of file Document.cpp.

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

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 341 of file Document.cpp.

References AdditionalModelConverter::cancel().

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 815 of file Document.cpp.

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

Referenced by MainWindowBase::openImage(), setMainModel(), and ~Document().

void Document::setMainModel ( WaveFileModel *  model)

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.

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

Definition at line 402 of file Document.cpp.

References activity(), addDerivedModel(), alignModel(), deleteLayer(), m_autoAlignment, m_layers, m_mainModel, m_models, mainModelChanged(), modelAboutToBeDeleted(), modelAdded(), modelRegenerationFailed(), modelRegenerationWarning(), and setModel().

Referenced by MainWindowBase::openAudio(), MainWindowBase::openLayersFromRDF(), and SVFileReader::readModel().

WaveFileModel* Document::getMainModel ( ) [inline]

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

Definition at line 190 of file Document.h.

References m_mainModel.

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

const WaveFileModel* Document::getMainModel ( ) const [inline]

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

Definition at line 195 of file Document.h.

References m_mainModel.

std::vector< Model * > Document::getTransformInputModels ( )

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

Definition at line 1004 of file Document.cpp.

References m_mainModel, and m_models.

bool Document::isKnownModel ( const Model *  model) const

Definition at line 1029 of file Document.cpp.

References m_mainModel, and m_models.

Model * 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.

Definition at line 691 of file Document.cpp.

References addDerivedModels(), and m_models.

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

vector< Model * > Document::addDerivedModels ( const Transforms &  transforms,
const ModelTransformer::Input &  input,
QString &  returnedMessage,
AdditionalModelConverter amc 
)
void Document::addAlreadyDerivedModel ( const Transform &  transform,
const ModelTransformer::Input &  input,
Model *  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.

Definition at line 578 of file Document.cpp.

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

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

void Document::addImportedModel ( Model *  model)

Add an imported (non-derived, non-main) model.

This is necessary to register any imported model that is associated with a layer.

Definition at line 621 of file Document.cpp.

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

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

void Document::setModel ( Layer *  layer,
Model *  model 
)

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 867 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 909 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 915 of file Document.cpp.

References m_mainModel, and m_models.

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

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 939 of file Document.cpp.

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

bool Document::canAlign ( ) [static]

Return true if alignment is supported (i.e.

if the necessary plugin is found).

Definition at line 1048 of file Document.cpp.

References getAlignmentTransformName().

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 273 of file Document.h.

References m_autoAlignment.

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 1159 of file Document.cpp.

References alignModel(), m_mainModel, and m_models.

void Document::toXml ( QTextStream &  out,
QString  indent,
QString  extraAttributes 
) const

Definition at line 1294 of file Document.cpp.

Referenced by MainWindowBase::toXml(), and toXmlAsTemplate().

void Document::toXmlAsTemplate ( QTextStream &  out,
QString  indent,
QString  extraAttributes 
) const

Definition at line 1300 of file Document.cpp.

References toXml().

Referenced by MainWindowBase::toXml().

void Document::layerRemoved ( Layer *  ) [signal]

Referenced by deleteLayer().

void Document::layerAboutToBeDeleted ( Layer *  ) [signal]

Referenced by deleteLayer().

void Document::layerInAView ( Layer *  ,
bool   
) [signal]
void Document::mainModelChanged ( WaveFileModel *  ) [signal]

Referenced by setMainModel(), and ~Document().

void Document::modelGenerationFailed ( QString  transformName,
QString  message 
) [signal]
void Document::modelGenerationWarning ( QString  transformName,
QString  message 
) [signal]
void Document::modelRegenerationFailed ( QString  layerName,
QString  transformName,
QString  message 
) [signal]

Referenced by setMainModel().

void Document::modelRegenerationWarning ( QString  layerName,
QString  transformName,
QString  message 
) [signal]

Referenced by setMainModel().

void Document::alignmentFailed ( QString  transformName,
QString  message 
) [signal]

Referenced by alignModel().

void Document::activity ( QString  ) [signal]

Referenced by setMainModel().

void Document::releaseModel ( Model *  model) [protected]

Definition at line 751 of file Document.cpp.

References m_mainModel, m_models, and modelAboutToBeDeleted().

Referenced by deleteLayer(), and setModel().

void Document::alignModel ( Model *  model) [protected]

If model is suitable for alignment, align it against the main model and store the alignment in the model.

(If the model has an alignment already for the current main model, leave it unchanged.)

!! configure

Definition at line 1056 of file Document.cpp.

References alignmentFailed(), and m_mainModel.

Referenced by addAdditionalModel(), addImportedModel(), alignModels(), and setMainModel().

void Document::addAdditionalModel ( Model *  model) [protected]
void Document::addToLayerViewMap ( Layer *  layer,
View *  view 
) [protected]

Definition at line 946 of file Document.cpp.

References layerInAView(), and m_layerViewMap.

void Document::removeFromLayerViewMap ( Layer *  layer,
View *  view 
) [protected]

Definition at line 964 of file Document.cpp.

References layerInAView(), and m_layerViewMap.

QString Document::getUniqueLayerName ( QString  candidate) [protected]
void Document::writeBackwardCompatibleDerivation ( QTextStream &  out,
QString  indent,
Model *  targetModel,
const ModelRecord rec 
) const [protected]
TransformId Document::getAlignmentTransformName ( ) [static, protected]

Definition at line 1036 of file Document.cpp.

Referenced by canAlign().

void Document::toXml ( QTextStream &  out,
QString  indent,
QString  extraAttributes,
bool  asTemplate 
) const [protected]
void Document::writePlaceholderMainModel ( QTextStream &  out,
QString  indent 
) const [protected]

Definition at line 1430 of file Document.cpp.

References m_mainModel.

Referenced by toXml().

vector< Layer * > Document::createLayersForDerivedModels ( std::vector< Model * >  ,
QStringList  names 
) [protected]

!! inadequate cleanup:

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

!! We need to clone the model when adding the layer, so that it

Definition at line 348 of file Document.cpp.

References createLayer(), layerAdded(), m_models, modelAboutToBeDeleted(), and setModel().

Referenced by createDerivedLayers(), createDerivedLayersAsync(), and AdditionalModelConverter::moreModelsAvailable().


Friends And Related Function Documentation

friend class AdditionalModelConverter [friend]

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

Definition at line 214 of file Document.h.

Referenced by createDerivedLayersAsync().


Member Data Documentation

WaveFileModel* Document::m_mainModel [protected]

The model that provides the underlying sample rate, etc.

This model is not reference counted for layers, and is not freed unless it is replaced or the document is deleted.

Definition at line 330 of file Document.h.

Referenced by addLayerToView(), alignModel(), alignModels(), createEmptyLayer(), createMainModelLayer(), getMainModel(), getTransformInputModels(), isKnownModel(), releaseModel(), setMainModel(), setModel(), toXml(), writePlaceholderMainModel(), and ~Document().

bool Document::m_autoAlignment [protected]

Definition at line 425 of file Document.h.

Referenced by addAdditionalModel(), addImportedModel(), setAutoAlignment(), and setMainModel().


The documentation for this class was generated from the following files: