#include <ImFusion/Base/DataModel.h>

Container for datasets holding ownership and managing a hierarchical list of persistent data. More...

Inheritance diagram for DataModel:

Detailed Description

Container for datasets holding ownership and managing a hierarchical list of persistent data.

In most cases there will be only one DataModel instance per application. The data is saved as a tree with any kind of Data instances in the leafs and DataGroup instances in the nodes. Furthermore, it ensures the invariant that Data::name() is unique for all elements in the model.

DataModel will take ownership of all added datasets and created DataGroups and enables you to browse/query them. However (in contrast to DataItemModel), it will not expose the children of CompoundData (except for DataGroup) since they are owned by their parent dataset and considered internal.

In addition to serving the actual datasets, DataModel also manages a set of DataLinks that can be used to synchronize properties across multiple datasets.

Note: DataModel does monitor its DataGroups for changes from the outside, and will attempt to handle them (including emitting the corresponding signals) correctly. However, doing so is discouraged. You should prefer using DataModel's add(), move(), and remove() functions instead because they may be more robust wrt. maintaining invariants.

See also: Data, DataGroup, DataLink, DataItemModel

Public Member Functions
void	setPrepareDataCallback (std::function< bool(Data *)> prepareData)
	Sets an optional callback that is called just before new data is added.

Public Member Functions inherited from SignalReceiver
	SignalReceiver ()=default
	Default constructor.

	SignalReceiver (const SignalReceiver &other)
	Copy constructor, does not copy any existing signal connections from other.

SignalReceiver &	operator= (SignalReceiver rhs)
	Assignment operator, disconnects all existing connections, does not copy any existing signal connections from rhs.

virtual	~SignalReceiver ()
	Virtual destructor disconnects from all connected signals.

Public Attributes
Signal< Data * >	signalDataAdded
	Emitted whenever a new dataset has been added; recursively for children of added groups.

Signal< Data * >	signalDataAboutToBeRemoved
	Emitted directly before a dataset is removed; recursively for children of removed groups.

Signal< Data * >	signalDataMoved
	Signal emitted whenever a dataset in the model has been moved to a new position.

Signal< DataLink * >	signalLinkAdded
	Signal emitted whenever a new DataLink has been added.

Signal< DataLink * >	signalLinkAboutToBeRemoved
	Signal emitted directly before a DataLink will be removed from the model.

Protected Member Functions
virtual bool	addImpl (Data data, const std::string &name, DataGroup group)

virtual std::string	generateName (const Data *data) const

virtual std::string	makeUniqueName (const std::string &baseName, Data *data) const

Protected Member Functions inherited from SignalReceiver
void	disconnectAll ()
	Disconnects all existing connections.

Protected Attributes
DataGroup	m_data
	Root node containing all top-level datasets managed by the DataModel.

std::vector< std::unique_ptr< DataLink > >	m_links
	List of all DataLinks managed by the DataModel.

std::function< bool(Data *)>	m_prepareData
	Optional callback used to check if new Data may be added to the model.

Manage the datasets of the model
bool	add (std::unique_ptr< Data > data, const std::string &baseName="", DataGroup *parentGroup=nullptr)
	Adds data to the model and acquires ownership of the object.

bool	add (OwningDataList &&dataList, const std::string &baseName="", DataGroup *parentGroup=nullptr)

virtual std::unique_ptr< Data >	remove (Data *data)
	Removes data from anywhere in the model and returns ownership to the caller.

void	clear ()
	Deletes all data from the model by calling remove on all data.

virtual bool	move (Data data, DataGroup newParent, int position=-1)
	Moves data from anywhere in the model to any new position.

DataGroup *	createGroup (const DataList &children)
	Creates a new group from the given list of children.

Query datasets from the model
bool	contains (const Data *data) const
	Returns true if the model contains data.

Data *	get (const std::string &name)
	Returns the data called name if it exists and `nullptr` otherwise.

const Data *	get (const std::string &name) const

DataList	getAll (Data::Kind kind=Data::UNKNOWN, Data::Modality modality=Data::Modality::NA) const
	Returns the flat list of all data of the given kind and modality in this model in a depth-first order.

Data *	getFirst (const std::set< Data::Kind > &kind={}, const std::set< Data::Modality > &modality={}) const
	Returns the first data in this model which matches the kind and modality criteria.

const DataGroup &	getRootNode () const
	Returns the root node of the data model under which all top-level data resides.

DataGroup &	getRootNode ()

DataGroup *	getParent (const Data *data) const
	Locates the parent node of the given dataset or `nullptr` if data is not part of the model.

DataGroup *	getCommonParent (DataList dataList) const
	Returns the closest parent all datasets in dataList share or `nullptr` if no such parent exists.

Manage links between datasets of the model
void	addLink (std::unique_ptr< DataLink > link)
	Add the given DataLink to be managed by the DataModel.

void	removeLink (DataLink *link)
	Remove the given DataLink from the DataModel, will be deleted.

std::vector< DataLink * >	links () const
	Return list of all DataLinks managed by this DataModel.

template<typename Link>
bool	hasLink (const std::vector< Data * > &data)
	Checks if the two data object passed are linked with the corresponding LinkType.

template<class Link>
Link *	linkData (const std::vector< Data * > &data)
	Ensure that the given data is linked together using the template DataLink type.

template<class Link>
void	unlinkData (const std::vector< Data * > &data, const std::function< bool(const DataLink *)> &mayDeleteLinkOp=nullptr)
	Removes all Data instances in data from all links of type `Link`.

Member Function Documentation

◆ add()

bool add	(	std::unique_ptr< Data >	data,
		const std::string &	baseName = "",
		DataGroup *	parentGroup = nullptr )

Adds data to the model and acquires ownership of the object.

Parameters

data	One or multiple Data instance to add to the model.
baseName	Base display name of the data. Since DataModel ensures unique naming of all held data, it may add a number to make baseName unique. If no name is provided, the name of data is used (i.e. result of `data->name()`). If both of them are empty, a default name is generated depending on the data type.
parentGroup	Optional DataGroup underneath which data should be added. By default the data is added to the root level.

Returns: Returns false if the provided data could not be added to the model for any reason.

◆ remove()

virtual std::unique_ptr< Data > remove ( Data * data )

virtual

Removes data from anywhere in the model and returns ownership to the caller.

This will also remove the data if it is part of a group. Returns nullptr if data could not be deleted or is not part of model.

Note: If data is the Data::proxyChild() of the parent group, it will remove the entire group.

◆ move()

virtual bool move	(	Data *	data,
		DataGroup *	newParent,
		int	position = -1 )

virtual

Moves data from anywhere in the model to any new position.

Parameters

data	Data instance to move.
newParent	Parent DataGroup to which data should be moved, will use the root node if `nullptr`.
position	Position within newParent where data should be moved to, will move to the end if negative.

◆ createGroup()

DataGroup * createGroup ( const DataList & children )

Creates a new group from the given list of children.

The data in children will be moved from anywhere in the model to the new group that will be created underneath the common parent of children. Returns nullptr on failure for instance if children contains datasets that are not part of the model.

◆ linkData()

template<class Link>

Link * linkData ( const std::vector< Data * > & data )

Ensure that the given data is linked together using the template DataLink type.

This function employs the following logic:

None of the data participates in an existing link of type Link -> create a new link
Any of the data already participates in one link of type Link -> add the other data to the existing link.
The data participates in multiple different links of type Link -> merge all existing links together into a new one.

If a Data instance in data is not accepted by the given Link type (see DataLink::accepts()), it will not be added to the link.

Note: Due to the merging logic that may happen when combining multiple existing links, any additional state of a participating DataLink may be reset when using this function.

Template Parameters

Link	Link type to use, must inherit from DataLink.

Parameters

data	List of Data instances to link together.

Returns: Link instance that links data together, will be null if the instantiated Link would be empty.

◆ unlinkData()

template<class Link>

void unlinkData	(	const std::vector< Data * > &	data,
		const std::function< bool(const DataLink *)> &	mayDeleteLinkOp = nullptr )

Removes all Data instances in data from all links of type Link.

If an existing DataLink holds references to less than two Data instances after the unlink process, it will be removed unless mayDeleteLinkOp is set and returns false for it.

Template Parameters

Link	Link type to use, must inherit from DataLink.

Parameters

data	List of Data instances to unlink.
mayDeleteLinkOp	Optional function to specify if a DataLink may be deleted if it becomes empty.

◆ setPrepareDataCallback()

void setPrepareDataCallback ( std::function< bool(Data *)> prepareData )

Sets an optional callback that is called just before new data is added.

If the callback returns false, the Data won't be added to the model.

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

ImFusion/Base/DataModel.h

Detailed Description

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Manage the datasets of the model

Query datasets from the model

Manage links between datasets of the model

Member Function Documentation

◆ add()

◆ remove()

◆ move()

◆ createGroup()

◆ linkData()

◆ unlinkData()

◆ setPrepareDataCallback()