Hold associations that link resources or components as an attribute value. More...

#include <ReferenceItem.h>

Inheritance diagram for smtk::attribute::ReferenceItem:

Collaboration diagram for smtk::attribute::ReferenceItem:

Classes
struct	Cache
	Internally, ReferenceItems cache retrieved PersistentObjects to speed up repeated calls to their contents. More...

class	const_iterator
	An iterator for references held by a ReferenceItem. More...

Public Types
using	Key = std::pair< smtk::common::UUID, smtk::common::UUID >
	A Key is a pair of UUIDs. More...

Public Types inherited from smtk::attribute::Item
enum	Type { AttributeRefType, DoubleType, GroupType, IntType, StringType, VoidType, FileType, DirectoryType, ColorType, ModelEntityType, MeshEntityType, DateTimeType, ReferenceType, ResourceType, ComponentType, NUMBER_OF_TYPES }

typedef std::function< bool(const Item *, bool includeCatagories, bool includeReadAccess, unsigned int readAccessLevel)>	RelevanceFunc
	Typedef for custom relevance functions.

using	Status = smtk::common::Status

Public Member Functions
	smtkTypeMacro (ReferenceItem)

	smtkSuperclassMacro (Item)

	ReferenceItem (const ReferenceItem &)

ReferenceItem &	operator= (const ReferenceItem &)

Item::Type	type () const override
	Indicate we are a reference to a persistent object.

std::size_t	numberOfValues () const
	Return the size of the item (number of entities associated with the item).

bool	setNumberOfValues (std::size_t newSize)
	Set the number of entities to be associated with this item (returns true if permitted).

bool	removeInvalidValues ()
	Remove all invalid references. More...

virtual std::shared_ptr< const ReferenceItemDefinition >	definition () const
	Return this item's definition.

const std::multimap< std::string, std::string > &	acceptableEntries () const
	Return the association constraints for this item.

std::size_t	numberOfRequiredValues () const
	Return the number of values required by this item's definition (if it has one).

std::size_t	maxNumberOfValues () const
	Return the maximum number of values allowed by this item's definition (or 0).

bool	contains (const smtk::resource::PersistentObjectPtr &obj) const
	Return true if the ReferenceItem contains a reference to the given object.

bool	contains (const smtk::common::UUID &compId) const
	Return true if the component is contained in this item; false otherwise.

void	visit (std::function< bool(const PersistentObjectPtr &)> visitor) const
	Invoke a method on each value of this item. More...

template<typename Container >
void	as (Container &result, std::function< typename Container::value_type(const PersistentObjectPtr &)> converter=[](const PersistentObjectPtr &obj) { return obj;}) const
	Populate a container of the given type with members of this item. More...

template<typename Container >
Container	as (std::function< typename Container::value_type(const PersistentObjectPtr &)> converter=[](const PersistentObjectPtr &obj) { return obj;}) const

Key	objectKey (std::size_t i=0) const
	\ Set/get object key (used for serialization). More...

bool	setObjectKey (std::size_t i, const Key &key)

bool	setObjectKey (std::size_t i, const Key &key, std::size_t conditional)

PersistentObjectPtr	value (std::size_t i=0) const
	Return the i-th object stored in this item.

template<typename T >
T::Ptr	valueAs (std::size_t i=0) const

virtual bool	isValueValid (std::size_t ii, const PersistentObjectPtr &entity) const

bool	isValueValid (const PersistentObjectPtr &entity) const

bool	setValue (const PersistentObjectPtr &val)
	Set the component stored with this item. More...

bool	setValue (std::size_t i, const PersistentObjectPtr &val)
	Set the i-th value to the given item. More...

template<typename I >
bool	setValues (I vbegin, I vend, typename std::iterator_traits< I >::difference_type offset=0)

template<typename I >
bool	appendValues (I vbegin, I vend)

template<typename I , typename T >
bool	setValuesVia (I vbegin, I vend, const T &converter, typename std::iterator_traits< I >::difference_type offset=0)

template<typename I , typename T >
bool	appendValuesVia (I vbegin, I vend, const T &converter)

bool	appendValue (const PersistentObjectPtr &val, bool allowDuplicates=true)
	Add val if it is allowed and val is not already present in the item unless allowDuplicates is true. More...

bool	removeValue (std::size_t i)
	Remove the value at the i-th location. More...

void	detachOwningResource () override
	Release the item's dependency on its parent attribute's Resource.

void	reset () override
	Clear the list of values and fill it with null entries up to the number of required values.

virtual std::string	valueAsString () const
	A convenience method to obtain the first value in the item as a string.

virtual std::string	valueAsString (std::size_t i) const
	Return the value of the i-th component as a string. More...

virtual bool	isSet (std::size_t i=0) const
	Return whether the i-th value is set. More...

virtual void	unset (std::size_t i=0)
	Force the i-th value of the item to be invalid.

virtual std::size_t	numberOfSetValues () const
	Return the number of non-null values in the item.

Item::Status	assign (const smtk::attribute::ConstItemPtr &sourceItem, const CopyAssignmentOptions &options, smtk::io::Logger &logger) override

bool	isExtensible () const
	A convenience method returning whether the item's definition is extensible.

const_iterator	begin () const
	Return an iterator to the first value in this item.

const_iterator	end () const
	Return an iterator just past the last value in this item.

std::ptrdiff_t	find (const smtk::common::UUID &compId) const
	Return the index of the first component with the given compId.

std::ptrdiff_t	find (const PersistentObjectPtr &component) const
	Return the index of the given component.

smtk::resource::LockType	lockType () const

void	visitChildren (std::function< void(smtk::attribute::ItemPtr, bool)> visitor, bool activeChildren=true) override
	visitChildren Invoke a function on each (or, if findInActiveChildren is true, each active) child item. More...

std::size_t	numberOfChildrenItems () const
	Return the number of all children items associated with the item.

const std::map< std::string, smtk::attribute::ItemPtr > &	childrenItems () const
	Return the map of all children items. More...

std::size_t	numberOfActiveChildrenItems () const
	Return the number of active children items associated with the item.

smtk::attribute::ItemPtr	activeChildItem (std::size_t i) const
	Return the i th active child item associated with the item.

std::size_t	currentConditional () const
	Return the index of the current active conditional. More...

virtual Status	assign (const smtk::attribute::ConstItemPtr &sourceItem, const CopyAssignmentOptions &options=CopyAssignmentOptions())
	Assigns contents to be same as source item. More...

virtual Status	assign (const smtk::attribute::ConstItemPtr &sourceItem, const CopyAssignmentOptions &options, smtk::io::Logger &logger)
	Assigns contents to be same as source item. More...

Public Member Functions inherited from smtk::attribute::Item
	smtkTypeMacroBase (smtk::attribute::Item)

std::string	name () const

std::string	label () const

bool	isRelevant (bool includeCatagories=true, bool includeReadAccess=false, unsigned int readAccessLevel=0) const
	Returns true if the item is relevant. More...

virtual bool	defaultIsRelevant (bool includeCatagories, bool includeReadAccess, unsigned int readAccessLevel) const
	Default isRelevant method that returns true if the item is relevant. More...

const smtk::attribute::ConstItemDefinitionPtr &	definition () const

template<typename DefType >
std::shared_ptr< const DefType >	definitionAs () const

smtk::attribute::AttributePtr	attribute () const
	Return the attribute that owns this item.

smtk::attribute::ItemPtr	owningItem () const

int	position () const
	Position is the item's location w/r to the owning item if not null or the owning attribute. More...

int	subGroupPosition () const
	Return the position of the item with respects to the GroupItem that owns it. More...

bool	isOptional () const
	Returns true if the item is optional.

bool	isEnabled () const
	An item is enabled under the following conditions: More...

bool	localEnabledState () const
	Return the state of the instance's isEnabled state.

void	setIsEnabled (bool isEnabledValue)
	Set the instance's local enabled state.

const smtk::attribute::Categories &	categories () const
	return the categories associated with the item (via its Definition)

unsigned int	advanceLevel (int mode=0) const
	Get the item 's advance level. More...

void	setLocalAdvanceLevel (int mode, unsigned int level)

unsigned int	localAdvanceLevel (int mode=0) const

void	unsetLocalAdvanceLevel (int mode=0)

bool	hasLocalAdvanceLevelInfo (int mode=0) const

void	setUserData (const std::string &key, smtk::simulation::UserDataPtr value)

smtk::simulation::UserDataPtr	userData (const std::string &key) const

void	clearUserData (const std::string &key)

void	clearAllUserData ()

virtual bool	rotate (std::size_t fromPosition, std::size_t toPosition)
	Rotate internal data. More...

void	detachOwningAttribute ()
	This should be used only by attributes.

void	detachOwningItem ()
	This should only be called by the item that owns this one.

bool	isValid (bool useActiveCategories=true) const
	tests the validity of an item More...

bool	isValid (const std::set< std::string > &categories) const
	tests the validity of an item More...

void	setCustomIsRelevant (RelevanceFunc func)
	Set and Get Methods for specifying a custom isRelevant function.

RelevanceFunc	customIsRelevant () const
	Set and Get Methods for specifying a custom isRelevant function.

smtk::attribute::ItemPtr	find (const std::string &name, SearchStyle style=RECURSIVE_ACTIVE)
	return a child item that matches name and satisfies the SearchStyle

smtk::attribute::ConstItemPtr	find (const std::string &name, SearchStyle style=RECURSIVE_ACTIVE) const
	return a child item that matches name and satisfies the SearchStyle

template<typename T >
T::Ptr	findAs (const std::string &name, SearchStyle style=RECURSIVE_ACTIVE)
	return a child item that matches name and satisfies the SearchStyle

template<typename T >
T::ConstPtr	findAs (const std::string &name, SearchStyle style=RECURSIVE_ACTIVE) const
	return a child item that matches name and satisfies the SearchStyle

std::string	path (const std::string &sep="/") const
	Formats the full path to the item with respect to its owning attribute using sep as the path separator.

void	setForceRequired (bool val)
	Controls if an item should be forced to be required regardless of its local enable property. More...

bool	forceRequired () const
	Controls if an item should be forced to be required regardless of its local enable property. More...

virtual Status	assign (const smtk::attribute::ConstItemPtr &sourceItem, const CopyAssignmentOptions &options=CopyAssignmentOptions())

void	setIsIgnored (bool val)
	Controls if an item should be ignored. More...

bool	isIgnored () const
	Controls if an item should be ignored. More...

Protected Member Functions
	ReferenceItem (Attribute *owningAttribute, int itemPosition)
	Construct an item given its owning attribute and location in the attribute.

	ReferenceItem (Item *owningItem, int myPosition, int mySubGroupPosition)
	Construct an item given its owning item and position inside the item.

bool	setDefinition (smtk::attribute::ConstItemDefinitionPtr def) override
	Set the definition of this attribute.

PersistentObjectPtr	value (const ReferenceItem::Key &key) const
	Return the object stored in this item associated with key.

bool	resolve () const
	Resolve the object pointers by accessing them using their associated keys. More...

Key	linkTo (const PersistentObjectPtr &val)
	Construct a link between the attribute that owns this item and val.

bool	isValidInternal (bool useCategories, const std::set< std::string > &categories) const override
	Internal implementation of calculating the validity of the item. More...

smtk::attribute::ItemPtr	findInternal (const std::string &name, SearchStyle style) override
	Internal implementation of the find method.

smtk::attribute::ConstItemPtr	findInternal (const std::string &name, SearchStyle style) const override

void	updateActiveChildrenItems ()
	Update the vector of active children based on the item's current value.

Protected Member Functions inherited from smtk::attribute::Item
	Item (Attribute *owningAttribute, int itemPosition)

	Item (Item *owningItem, int myPosition, int mySubGroupPosition)

template<typename T >
bool	rotateVector (std::vector< T > &v, std::size_t fromPosition, std::size_t toPosition)

Protected Attributes
std::vector< Key >	m_keys

smtk::attribute::WeakAttributePtr	m_referencedAttribute
	In order to clean up its links when being deleted the item needs to track its referencing attribute. More...

Protected Attributes inherited from smtk::attribute::Item
Attribute *	m_attribute

Item *	m_owningItem

int	m_position

int	m_subGroupPosition

bool	m_isEnabled

bool	m_isIgnored

smtk::attribute::ConstItemDefinitionPtr	m_definition

std::map< std::string, smtk::simulation::UserDataPtr >	m_userData

RelevanceFunc	m_customIsRelevant = nullptr

Friends
class	ReferenceItemDefinition

class	ValueItemDefinition

class	Definition

Additional Inherited Members
Static Public Member Functions inherited from smtk::attribute::Item
static std::string	type2String (Item::Type t)

static Item::Type	string2Type (const std::string &s)

Detailed Description

Hold associations that link resources or components as an attribute value.

An attribute whose value is a resource or component (such as a mesh set, model entity, or even an attribute).

While the actual value stored is a pointer to the linked object, only the UUID(s) of the object are saved when the attribute is serialized. Then, when deserialized, the application's resource manager is used to find a pointer to the deserialized object given its UUID(s). If the entity is not present, the returned pointer will be null and no type checking of attribute values can be performed.

Anything inheriting this class must implement

the type() method;
the virtual valueAsString() method this class declares; and
a method to construct an instance and return a shared pointer to it.

Member Typedef Documentation

◆ Key

using smtk::attribute::ReferenceItem::Key = std::pair<smtk::common::UUID, smtk::common::UUID>

A Key is a pair of UUIDs.

the First UUID is the id of the resource link, and the second one is the id of the component link.

Member Function Documentation

◆ appendValue()

bool smtk::attribute::ReferenceItem::appendValue	(	const PersistentObjectPtr &	val,
		bool	allowDuplicates = `true`
	)

Add val if it is allowed and val is not already present in the item unless allowDuplicates is true.

This will not enable the item if it is disabled.

This will not always add val to the end of the item's array; if there is an unset value anywhere in the allocated array, that will be preferred to reallocation. Note that disallowing duplicates will result in a performance impact.

◆ as()

template<typename Container >

void smtk::attribute::ReferenceItem::as	(	Container &	result,
		std::function< typename Container::value_type(const PersistentObjectPtr &)>	converter = `[](const PersistentObjectPtr& obj) { return obj; }`
	)		const

inline

Populate a container of the given type with members of this item.

Note that you can use the converter parameter to downcast items as desired (and thus skip entries not of the downcast type). For example:

ReferenceItemPtr modelEntityItem;
std::set<smtk::model::EntityPtr> modelEntities;
modelEntityItem->as(modelEntities,
  [](const PersistentObjectPtr& obj)
  { return std::dynamic_pointer_cast<smtk::model::Entity>(obj); });

will populate the modelEntities set with only those persistent objects that inherit smtk::model::Entity; other objects return a nullptr when cast and this method skips values which evaluate to false.

◆ assign() [1/3]

Item::Status Item::assign

Assigns contents to be same as source item.

Assigns this item to be equivalent to another. Returns true if success and false if a problem occurred.

◆ assign() [2/3]

Item::Status smtk::attribute::ReferenceItem::assign	(	const smtk::attribute::ConstItemPtr &	sourceItem,
		const CopyAssignmentOptions &	options,
		smtk::io::Logger &	logger
	)

overridevirtual

Assigns this item to be equivalent to another. Options are processed by derived item classes. The options are defined in Item.h.

This method returns a Status object that indicates both success/failure and modification/stasis. If cast to a boolean, the Status object returns true for success and false for failure.

Reimplemented from smtk::attribute::Item.

◆ assign() [3/3]

Item::Status Item::assign

Assigns contents to be same as source item.

Assigns this item to be equivalent to another. Returns true if success and false if a problem occurred.

◆ childrenItems()

const std::map<std::string, smtk::attribute::ItemPtr>& smtk::attribute::ReferenceItem::childrenItems ( ) const

inline

Return the map of all children items.

The map's key is the name of the item.

◆ currentConditional()

std::size_t smtk::attribute::ReferenceItem::currentConditional ( ) const

inline

Return the index of the current active conditional.

This is primarily used when serializing/deserializing the item

◆ isSet()

bool smtk::attribute::ReferenceItem::isSet ( std::size_t i = 0 ) const

virtual

Return whether the i-th value is set.

This returns true when the item and its UUID are non-nullptr and false otherwise.

Note that this is not always what you would expect! You can set a value to be an invalid, non-nullptr UUID so that entities which have been expunged can be reported (and other use cases).

◆ isValidInternal()

bool smtk::attribute::ReferenceItem::isValidInternal	(	bool	useCategories,
		const std::set< std::string > &	categories
	)		const

overrideprotectedvirtual

Internal implementation of calculating the validity of the item.

If useCategories is true then the set of categories will be taken into consideration.

Implements smtk::attribute::Item.

◆ objectKey()

smtk::attribute::ReferenceItem::Key smtk::attribute::ReferenceItem::objectKey ( std::size_t i = 0 ) const

\ Set/get object key (used for serialization).

If the item has children associated with it, you need to call the method that explicitly sets the proper conditional since we may not be able to access the corresponding persistent object

◆ removeInvalidValues()

bool smtk::attribute::ReferenceItem::removeInvalidValues ( )

Remove all invalid references.

Go through all values that are set and verify that they are still valid. If the value's resource is loaded in memory, the associated value is checked to see if it exists within the resource. If it is not then it is removed. The method returns true if there were values removed. Note that if the resource is not loaded the values are left alone.

◆ removeValue()

bool smtk::attribute::ReferenceItem::removeValue ( std::size_t i )

Remove the value at the i-th location.

If the number of values may not be changed, then the i-th array entry is set to nullptr. Otherwise, the value is erased from the array (reducing the number of values stored by 1).

◆ resolve()

bool smtk::attribute::ReferenceItem::resolve ( ) const

protected

Resolve the object pointers by accessing them using their associated keys.

Return true if all object pointers were successfully resolved.

◆ setValue() [1/2]

bool smtk::attribute::ReferenceItem::setValue ( const PersistentObjectPtr & val )

Set the component stored with this item.

This always sets the 0-th item and is a convenience method for cases where only 1 value is needed.

◆ setValue() [2/2]

bool smtk::attribute::ReferenceItem::setValue	(	std::size_t	i,
		const PersistentObjectPtr &	val
	)

Set the i-th value to the given item.

This method does no checking to see if i is valid. bool setObjectValue(std::size_t i, const PersistentObjectPtr& val); Return the i-th object stored in this item.

◆ valueAsString()

std::string smtk::attribute::ReferenceItem::valueAsString ( std::size_t i ) const

virtual

Return the value of the i-th component as a string.

This returns a string of the form "[" {UUID} "," {UUID} "]" where the first UUID is the component's resource and the second UUID is the component's.

Reimplemented in smtk::attribute::ComponentItem, and smtk::attribute::ResourceItem.

◆ visit()

void smtk::attribute::ReferenceItem::visit ( std::function< bool(const PersistentObjectPtr &)> visitor ) const

Invoke a method on each value of this item.

If the lambda returns false, iteration will terminate immediately. Otherwise, iteration continues.

◆ visitChildren()

void smtk::attribute::ReferenceItem::visitChildren	(	std::function< void(smtk::attribute::ItemPtr, bool)>	visitor,
		bool	activeChildren = `true`
	)

overridevirtual

visitChildren Invoke a function on each (or, if findInActiveChildren is true, each active) child item.

If a subclass presents childern items(ValueItem, Group, ComponentItem, ...) then this function should be overriden.

Parameters

visitor	a lambda function which would be applied on children items
activeChildren	a flag indicating whether it should be applied to active children only or not

Reimplemented from smtk::attribute::Item.

Member Data Documentation

◆ m_referencedAttribute

smtk::attribute::WeakAttributePtr smtk::attribute::ReferenceItem::m_referencedAttribute

protected

In order to clean up its links when being deleted the item needs to track its referencing attribute.

During deletion, the attribute() call may return nullptr not because the owning attribute is being deleted but because the owning item is being deleted.

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

/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/release/smtk/attribute/ReferenceItem.h
/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/release/smtk/attribute/ReferenceItem.cxx

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Key

Member Function Documentation

◆ appendValue()

◆ as()

◆ assign() [1/3]

◆ assign() [2/3]

◆ assign() [3/3]

◆ childrenItems()

◆ currentConditional()

◆ isSet()

◆ isValidInternal()

◆ objectKey()

◆ removeInvalidValues()

◆ removeValue()

◆ resolve()

◆ setValue() [1/2]

◆ setValue() [2/2]

◆ valueAsString()

◆ visit()

◆ visitChildren()

Member Data Documentation

◆ m_referencedAttribute