SMTK  @SMTK_VERSION@
Simulation Modeling Tool Kit
Classes | Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
smtk::attribute::ReferenceItem Class Reference

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

#include <ReferenceItem.h>

Inheritance diagram for smtk::attribute::ReferenceItem:
[legend]
Collaboration diagram for smtk::attribute::ReferenceItem:
[legend]

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
}
 
enum  AssignmentOptions {
  IGNORE_EXPRESSIONS = 0x001, IGNORE_MODEL_ENTITIES = 0x002, IGNORE_ATTRIBUTE_REF_ITEMS = 0x004, IGNORE_RESOURCE_COMPONENTS = 0x008,
  COPY_MODEL_ASSOCIATIONS = 0x010
}
 

Public Member Functions

 smtkTypeMacro (ReferenceItem)
 
 smtkSuperclassMacro (Item)
 
 ReferenceItem (const ReferenceItem &)
 
ReferenceItemoperator= (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 ReferenceItemDefinitiondefinition () 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.
 
bool assign (smtk::attribute::ConstItemPtr &sourceItem, unsigned int options=0) override
 Assigns contents to be same as source item. More...
 
bool isExtensible () const
 A convenience method returning whether the item's definition is extensible.
 
const_iterator begin () const
 Return an iterator to the first model-entity value in this item.
 
const_iterator end () const
 Return an iterator just past the last model-entity 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...
 
- Public Member Functions inherited from smtk::attribute::Item
 smtkTypeMacroBase (smtk::attribute::Item)
 
std::string name () const
 
std::string label () const
 
virtual bool isRelevant (bool includeCatagories=true, bool includeReadAccess=false, unsigned int readAccessLevel=0) const
 Returns true if the item is relevant. More...
 
const smtk::attribute::ConstItemDefinitionPtrdefinition () 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
 
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::Categoriescategories () 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...
 
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
 
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...
 
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< Keym_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
Attributem_attribute
 
Itemm_owningItem
 
int m_position
 
int m_subGroupPosition
 
bool m_isEnabled
 
bool m_isIgnored
 
smtk::attribute::ConstItemDefinitionPtr m_definition
 
std::map< std::string, smtk::simulation::UserDataPtrm_userData
 

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

Member Typedef Documentation

◆ Key

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()

bool smtk::attribute::ReferenceItem::assign ( smtk::attribute::ConstItemPtr sourceItem,
unsigned int  options = 0 
)
overridevirtual

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 occured.

Reimplemented from smtk::attribute::Item.

◆ 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
visitora lambda function which would be applied on children items
activeChildrena 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: