Generate subphrases to display for a given descriptive phrase. More...

#include <SubphraseGenerator.h>

Inheritance diagram for smtk::view::SubphraseGenerator:

Collaboration diagram for smtk::view::SubphraseGenerator:

Public Types
using	Path = std::vector< int >

using	PhrasesByPath = std::multimap< Path, DescriptivePhrasePtr >

Public Member Functions
	smtkTypeMacroBase (smtk::view::SubphraseGenerator)

	smtkCreateMacro (smtk::view::SubphraseGenerator)

virtual DescriptivePhrases	subphrases (DescriptivePhrase::Ptr src)
	Return a list of descriptive phrases that elaborate upon src. More...

virtual bool	hasChildren (const DescriptivePhrase &src) const
	Return true if children would be generated for the Descriptive Phrase.

virtual smtk::resource::PersistentObjectSet	parentObjects (const smtk::resource::PersistentObjectPtr &obj) const
	Return a set of parent Persistent Objects for this object. More...

bool	setModel (PhraseModelPtr model)
	Set the phrase model used to adapt phrases to a user interface.

PhraseModelPtr	model () const
	Return the phrase model (if any) used to adapt phrases to a user interface.

virtual DescriptivePhrasePtr	createSubPhrase (const smtk::resource::PersistentObjectPtr &obj, const DescriptivePhrasePtr &parent, Path &childPath)
	Create a new Subphrase for an object which will be a child of parent and return the path to the phrase.

virtual void	subphrasesForCreatedObjects (const smtk::resource::PersistentObjectArray &objects, const DescriptivePhrasePtr &localRoot, PhrasesByPath &resultingPhrases)
	Append subphrases and their paths that the given set of created objects implies. More...

virtual int	directLimit () const
	The maximum number of subphrases to directly include before turning into a list. More...

virtual bool	setDirectLimit (int val)
	Set the maximum number of direct children before a summary phrase is inserted. More...

virtual bool	shouldOmitProperty (DescriptivePhrase::Ptr parent, smtk::resource::PropertyType ptype, const std::string &pname) const
	Should the property of the given type and name be omitted from presentation? More...

ManagerPtr	manager () const
	SubphraseGenerators that are managed have a non-null pointer to their manager.


virtual void	setSkipProperties (bool val)
	Get/Set whether entity properties will be skiped for subphrases. More...

virtual bool	skipProperties () const
	Get/Set whether entity properties will be skiped for subphrases. More...


virtual void	setSkipAttributes (bool val)
	Get/Set whether entity attributes will be skiped for subphrases. More...

virtual bool	skipAttributes () const
	Get/Set whether entity attributes will be skiped for subphrases. More...

Static Public Member Functions
static std::string	getType (const smtk::view::ConfigurationPtr &viewSpec)

static SubphraseGeneratorPtr	create (const std::string &typeName, const smtk::view::ManagerPtr &manager)

Public Attributes
friend	Manager

Protected Member Functions
virtual Path	indexOfObjectInParent (const smtk::resource::PersistentObjectPtr &obj, const smtk::view::DescriptivePhrasePtr &parent, const Path &parentPath)

virtual int	findResourceLocation (smtk::resource::ResourcePtr rsrc, const DescriptivePhrase::Ptr &root) const

virtual bool	findSortedLocation (Path &pathOut, smtk::attribute::AttributePtr attr, DescriptivePhrase::Ptr &phr, const DescriptivePhrase::Ptr &parent) const

virtual bool	findSortedLocation (Path &pathOut, smtk::model::EntityPtr entity, DescriptivePhrase::Ptr &phr, const DescriptivePhrase::Ptr &parent) const

virtual bool	findSortedLocation (Path &pathOut, smtk::mesh::ComponentPtr comp, DescriptivePhrase::Ptr &phr, const DescriptivePhrase::Ptr &parent) const

bool	resourceHasChildren (const smtk::resource::ResourcePtr &rsrc) const
	Return true if the resource would cause subphrases to be generated.

bool	modelEntityHasChildren (const smtk::model::EntityPtr &entity) const
	Return true if the model entity would cause subphrases to be generated.

void	componentsOfResource (DescriptivePhrase::Ptr src, smtk::resource::ResourcePtr rsrc, DescriptivePhrases &result)
	Populate result with the top-level components of rsrc with src as their parent.

void	itemsOfAttribute (DescriptivePhrase::Ptr src, smtk::attribute::AttributePtr att, DescriptivePhrases &result)
	Populate result with the active, public items of att with src as their parent.

void	childrenOfModelEntity (DescriptivePhrase::Ptr src, smtk::model::EntityPtr modelEntity, DescriptivePhrases &result)
	Populate result with the children of modelEntity with src as their parent.

template<typename T >
PhraseListContentPtr	addComponentPhrases (const T &components, DescriptivePhrase::Ptr parent, DescriptivePhrases &result, int mutability=static_cast< int >(smtk::view::PhraseContent::ContentType::TITLE)\|static_cast< int >(smtk::view::PhraseContent::ContentType::COLOR), std::function< bool(const DescriptivePhrase::Ptr &, const DescriptivePhrase::Ptr &)> comparator=DescriptivePhrase::compareByTypeThenTitle)
	A templated helper for creating lists of components as subphrases. More...

template<typename T >
void	filterModelEntityPhraseCandidates (T &ents)
	A template helper for filtering the model entity phrase candidates As a model entity could be marked as excluded from view presentation, this helper will update the container to respect this property. More...

template<typename T >
PhraseListContentPtr	addModelEntityPhrases (const T &ents, DescriptivePhrase::Ptr parent, int limit, DescriptivePhrases &result, int mutability=static_cast< int >(smtk::view::PhraseContent::ContentType::TITLE)\|static_cast< int >(smtk::view::PhraseContent::ContentType::COLOR), std::function< bool(const DescriptivePhrase::Ptr &, const DescriptivePhrase::Ptr &)> comparator=nullptr)
	A templated helper for the model-related utility methods.


void	freeSubmodelsOfModel (DescriptivePhrase::Ptr src, const smtk::model::Model &mod, DescriptivePhrases &result)
	Model-entity utility methods. More...

void	freeGroupsOfModel (DescriptivePhrase::Ptr src, const smtk::model::Model &mod, DescriptivePhrases &result)
	Add groups of mod to result with src as their parent.

void	freeCellsOfModel (DescriptivePhrase::Ptr src, const smtk::model::Model &mod, DescriptivePhrases &result)
	Add free cells of mod to result with src as their parent.

void	freeAuxiliaryGeometriesOfModel (DescriptivePhrase::Ptr src, const smtk::model::Model &mod, DescriptivePhrases &result)
	Add auxiliary geometry entities of mod to result with src as their parent.

void	instancesOfModelEntity (DescriptivePhrase::Ptr src, const smtk::model::EntityRef &ent, DescriptivePhrases &result)
	Add instances of ent to result with src as their parent.

void	cellOfModelUse (DescriptivePhrase::Ptr src, const smtk::model::UseEntity &ent, DescriptivePhrases &result)
	Add attributes associated with ent to result with src as their parent.

void	boundingShellsOfModelUse (DescriptivePhrase::Ptr src, const smtk::model::UseEntity &ent, DescriptivePhrases &result)
	Model-entity utility methods. More...

void	toplevelShellsOfModelUse (DescriptivePhrase::Ptr src, const smtk::model::UseEntity &ent, DescriptivePhrases &result)
	Model-entity utility methods. More...

void	usesOfModelCell (DescriptivePhrase::Ptr src, const smtk::model::CellEntity &ent, DescriptivePhrases &result)
	Model-entity utility methods. More...

void	inclusionsOfModelCell (DescriptivePhrase::Ptr src, const smtk::model::CellEntity &ent, DescriptivePhrases &result)
	Model-entity utility methods. More...

void	boundingCellsOfModelCell (DescriptivePhrase::Ptr src, const smtk::model::CellEntity &ent, DescriptivePhrases &result)
	Model-entity utility methods. More...

void	usesOfModelShell (DescriptivePhrase::Ptr src, const smtk::model::ShellEntity &ent, DescriptivePhrases &result)
	Model-entity utility methods. More...

void	membersOfModelGroup (DescriptivePhrase::Ptr src, const smtk::model::Group &grp, DescriptivePhrases &result)
	Model-entity utility methods. More...

void	childrenOfModelAuxiliaryGeometry (DescriptivePhrase::Ptr src, const smtk::model::AuxiliaryGeometry &aux, DescriptivePhrases &result)
	Model-entity utility methods. More...

void	prototypeOfModelInstance (DescriptivePhrase::Ptr src, const smtk::model::Instance &ent, DescriptivePhrases &result)
	Model-entity utility methods. More...

template<typename T >
void	PreparePath (T &result, const T &parentPath, int childIndex)
	Model-entity utility methods. More...

template<typename T >
int	IndexFromTitle (const std::string &title, const T &phrases)
	Model-entity utility methods. More...

Protected Attributes
int	m_directLimit

bool	m_skipAttributes

bool	m_skipProperties

WeakPhraseModelPtr	m_model

WeakManagerPtr	m_manager

Detailed Description

Generate subphrases to display for a given descriptive phrase.

This abstract class should be subclassed by user interfaces to provide control over what information is presented about a given entity or set of entities.

Its subphrases() method takes in a single phrase and returns an ordered array of child phrases. If the input phrase is null, then the generator should return an array of top-level phrases.

A phrase generator may hold a weak reference to a phrase model. The generator's purpose is to compute a list of child phrases while a model's purpose is to interface a phrase hierarchy to a concrete user interface. This involves notifying observers of changes to phrases (including insertions, deletions, moves, and modifications). A model may also need to decorate phrase content produced by the generator to accommodate different UI affordances. For this reason, when using a phrase model, it should be set on each subphrase generator in the hierarchy. Then, when a descriptive phrase uses the generator to build a portion of the hierarchy, the model can be informed of the changes.

Member Function Documentation

◆ addComponentPhrases()

template<typename T >

PhraseListContentPtr smtk::view::SubphraseGenerator::addComponentPhrases	(	const T &	components,
		DescriptivePhrase::Ptr	parent,
		DescriptivePhrases &	result,
		int	mutability = `static_cast< int >(smtk::view::PhraseContent::ContentType::TITLE)\|static_cast< int >(smtk::view::PhraseContent::ContentType::COLOR)`,
		std::function< bool(const DescriptivePhrase::Ptr &, const DescriptivePhrase::Ptr &)>	comparator = `DescriptivePhrase::compareByTypeThenTitle`
	)

protected

A templated helper for creating lists of components as subphrases.

This method will create a new descriptive phrase with no PhraseContent and its type set to COMPONENT_LIST. That phrase will added to result. It will have its subphrases populated with new phrases, one per entry of the components container, each with ComponentPhraseContent. If a comparator is passed in, then the children of this new phrase will be sorted using the comparator.

◆ boundingCellsOfModelCell()

void smtk::view::SubphraseGenerator::boundingCellsOfModelCell	(	DescriptivePhrase::Ptr	src,
		const smtk::model::CellEntity &	ent,
		DescriptivePhrases &	result
	)

protected

Model-entity utility methods.

These methods are called by childrenOfModelEntity and are available for subclasses dealing with presenting the model tree. Add submodels of mod to result with src as their parent.

◆ boundingShellsOfModelUse()

void smtk::view::SubphraseGenerator::boundingShellsOfModelUse	(	DescriptivePhrase::Ptr	src,
		const smtk::model::UseEntity &	ent,
		DescriptivePhrases &	result
	)

protected

Model-entity utility methods.

These methods are called by childrenOfModelEntity and are available for subclasses dealing with presenting the model tree. Add submodels of mod to result with src as their parent.

◆ childrenOfModelAuxiliaryGeometry()

void smtk::view::SubphraseGenerator::childrenOfModelAuxiliaryGeometry	(	DescriptivePhrase::Ptr	src,
		const smtk::model::AuxiliaryGeometry &	aux,
		DescriptivePhrases &	result
	)

protected

Model-entity utility methods.

These methods are called by childrenOfModelEntity and are available for subclasses dealing with presenting the model tree. Add submodels of mod to result with src as their parent.

◆ directLimit()

int smtk::view::SubphraseGenerator::directLimit ( ) const

virtual

The maximum number of subphrases to directly include before turning into a list.

The helper methods in SubphraseGenerator (such as InstancesOfEntity()), will insert small numbers of child items directly into the result subphrases. But when more than directLimit() items of a given type (such as instances for which the given entity serves as a prototype) are present, a sublist is added a subphrase. This prevents long lists from obscuring other details.

Subclasses may override this method.

◆ filterModelEntityPhraseCandidates()

template<typename T >

void smtk::view::SubphraseGenerator::filterModelEntityPhraseCandidates ( T & ents )

protected

A template helper for filtering the model entity phrase candidates As a model entity could be marked as excluded from view presentation, this helper will update the container to respect this property.

Assumption: Type T is std::vector holding smtk::model::EntityRef or its subclass type.

◆ freeSubmodelsOfModel()

void smtk::view::SubphraseGenerator::freeSubmodelsOfModel	(	DescriptivePhrase::Ptr	src,
		const smtk::model::Model &	mod,
		DescriptivePhrases &	result
	)

protected

Model-entity utility methods.

These methods are called by childrenOfModelEntity and are available for subclasses dealing with presenting the model tree. Add submodels of mod to result with src as their parent.

◆ inclusionsOfModelCell()

void smtk::view::SubphraseGenerator::inclusionsOfModelCell	(	DescriptivePhrase::Ptr	src,
		const smtk::model::CellEntity &	ent,
		DescriptivePhrases &	result
	)

protected

Model-entity utility methods.

These methods are called by childrenOfModelEntity and are available for subclasses dealing with presenting the model tree. Add submodels of mod to result with src as their parent.

◆ IndexFromTitle()

template<typename T >

int smtk::view::SubphraseGenerator::IndexFromTitle	(	const std::string &	title,
		const T &	phrases
	)

protected

Model-entity utility methods.

These methods are called by childrenOfModelEntity and are available for subclasses dealing with presenting the model tree. Add submodels of mod to result with src as their parent.

◆ membersOfModelGroup()

void smtk::view::SubphraseGenerator::membersOfModelGroup	(	DescriptivePhrase::Ptr	src,
		const smtk::model::Group &	grp,
		DescriptivePhrases &	result
	)

protected

Model-entity utility methods.

These methods are called by childrenOfModelEntity and are available for subclasses dealing with presenting the model tree. Add submodels of mod to result with src as their parent.

◆ parentObjects()

smtk::resource::PersistentObjectSet smtk::view::SubphraseGenerator::parentObjects ( const smtk::resource::PersistentObjectPtr & obj ) const

virtual

Return a set of parent Persistent Objects for this object.

based on the generator's parent/child rules

Reimplemented in smtk::markup::SubphraseGenerator.

◆ PreparePath()

template<typename T >

void smtk::view::SubphraseGenerator::PreparePath	(	T &	result,
		const T &	parentPath,
		int	childIndex
	)

protected

Model-entity utility methods.

These methods are called by childrenOfModelEntity and are available for subclasses dealing with presenting the model tree. Add submodels of mod to result with src as their parent.

◆ prototypeOfModelInstance()

void smtk::view::SubphraseGenerator::prototypeOfModelInstance	(	DescriptivePhrase::Ptr	src,
		const smtk::model::Instance &	ent,
		DescriptivePhrases &	result
	)

protected

Model-entity utility methods.

These methods are called by childrenOfModelEntity and are available for subclasses dealing with presenting the model tree. Add submodels of mod to result with src as their parent.

◆ setDirectLimit()

bool smtk::view::SubphraseGenerator::setDirectLimit ( int val )

virtual

Set the maximum number of direct children before a summary phrase is inserted.

This is used to add a layer of indirection to the hierarchy so that long lists are not inadvertently opened and so that a parent which would otherwise have many children of many different kinds can group its children to allow easier browsing.

A negative value indicates that no limit should be imposed (no summary phrases will ever be generated).

◆ setSkipAttributes()

void smtk::view::SubphraseGenerator::setSkipAttributes ( bool val )

virtual

Get/Set whether entity attributes will be skiped for subphrases.

For some cases, only model entities are desired in a hierarchy view.

◆ setSkipProperties()

void smtk::view::SubphraseGenerator::setSkipProperties ( bool val )

virtual

Get/Set whether entity properties will be skiped for subphrases.

For some cases, only model entities are desired in a hierarchy view.

◆ shouldOmitProperty()

bool smtk::view::SubphraseGenerator::shouldOmitProperty	(	DescriptivePhrase::Ptr	parent,
		smtk::resource::PropertyType	ptype,
		const std::string &	pname
	)		const

virtual

Should the property of the given type and name be omitted from presentation?

Subclasses should override this method.

◆ skipAttributes()

bool smtk::view::SubphraseGenerator::skipAttributes ( ) const

virtual

Get/Set whether entity attributes will be skiped for subphrases.

For some cases, only model entities are desired in a hierarchy view.

◆ skipProperties()

bool smtk::view::SubphraseGenerator::skipProperties ( ) const

virtual

Get/Set whether entity properties will be skiped for subphrases.

For some cases, only model entities are desired in a hierarchy view.

◆ subphrases()

DescriptivePhrases smtk::view::SubphraseGenerator::subphrases ( DescriptivePhrase::Ptr src )

virtual

Return a list of descriptive phrases that elaborate upon src.

Subclasses must override this method.

Reimplemented in smtk::view::EmptySubphraseGenerator, smtk::view::TwoLevelSubphraseGenerator, and smtk::view::QueryFilterSubphraseGenerator.

◆ subphrasesForCreatedObjects()

void smtk::view::SubphraseGenerator::subphrasesForCreatedObjects	(	const smtk::resource::PersistentObjectArray &	objects,
		const DescriptivePhrasePtr &	localRoot,
		PhrasesByPath &	resultingPhrases
	)

virtual

Append subphrases and their paths that the given set of created objects implies.

After an operation, newly-created objects (components and resources) need to be inserted into the descriptive phrase hierarchy. Since the subphrase generator is responsible for populating all of the tree except the top-level phrases initially, this task also falls to the generator.

The generator is responsible for decorating each path it adds to resultingPhrases if a phrase model is present.

Reimplemented in smtk::markup::SubphraseGenerator.

◆ toplevelShellsOfModelUse()

void smtk::view::SubphraseGenerator::toplevelShellsOfModelUse	(	DescriptivePhrase::Ptr	src,
		const smtk::model::UseEntity &	ent,
		DescriptivePhrases &	result
	)

protected

Model-entity utility methods.

These methods are called by childrenOfModelEntity and are available for subclasses dealing with presenting the model tree. Add submodels of mod to result with src as their parent.

◆ usesOfModelCell()

void smtk::view::SubphraseGenerator::usesOfModelCell	(	DescriptivePhrase::Ptr	src,
		const smtk::model::CellEntity &	ent,
		DescriptivePhrases &	result
	)

protected

Model-entity utility methods.

These methods are called by childrenOfModelEntity and are available for subclasses dealing with presenting the model tree. Add submodels of mod to result with src as their parent.

◆ usesOfModelShell()

void smtk::view::SubphraseGenerator::usesOfModelShell	(	DescriptivePhrase::Ptr	src,
		const smtk::model::ShellEntity &	ent,
		DescriptivePhrases &	result
	)

protected

Model-entity utility methods.

These methods are called by childrenOfModelEntity and are available for subclasses dealing with presenting the model tree. Add submodels of mod to result with src as their parent.

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

/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/view/SubphraseGenerator.h
/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/view/SubphraseGenerator.cxx

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ addComponentPhrases()

◆ boundingCellsOfModelCell()

◆ boundingShellsOfModelUse()

◆ childrenOfModelAuxiliaryGeometry()

◆ directLimit()

◆ filterModelEntityPhraseCandidates()

◆ freeSubmodelsOfModel()

◆ inclusionsOfModelCell()

◆ IndexFromTitle()

◆ membersOfModelGroup()

◆ parentObjects()

◆ PreparePath()

◆ prototypeOfModelInstance()

◆ setDirectLimit()

◆ setSkipAttributes()

◆ setSkipProperties()

◆ shouldOmitProperty()

◆ skipAttributes()

◆ skipProperties()

◆ subphrases()

◆ subphrasesForCreatedObjects()

◆ toplevelShellsOfModelUse()

◆ usesOfModelCell()

◆ usesOfModelShell()