A base class for phrases describing an SMTK model. More...

#include <DescriptivePhrase.h>

Inheritance diagram for smtk::view::DescriptivePhrase:

Collaboration diagram for smtk::view::DescriptivePhrase:

Public Types
using	Visitor = std::function< int(DescriptivePhrasePtr, std::vector< int > &)>
	The signature of a function used to visit all or part of a phrase hierarchy. More...

using	Badges = std::vector< Badge * >

Public Member Functions
	smtkTypeMacroBase (DescriptivePhrase)

	smtkCreateMacro (DescriptivePhrase)

Ptr	setup (DescriptivePhraseType phraseType, Ptr parent=Ptr())
	Populate a phrase with its type and parent in the hierarchy of phrases.

Ptr	setDelegate (SubphraseGeneratorPtr delegate)
	Set the subphrase generator used to populate the children of this phrase.

bool	setContent (PhraseContentPtr content)
	Set the content (state) of the phrase.

PhraseContentPtr	content () const
	Return the content (state) of the phrase.

Badges	badges () const
	Return an ordered subset of badges that apply to this phrase. More...

virtual DescriptivePhraseType	phraseType () const
	Return the role that the phrase plays in the description.

virtual DescriptivePhrasePtr	parent () const
	Return the parent phrase of this phrase (or null).

bool	hasChildren () const
	Indicate if the Phrase has children. More...

virtual void	markDirty (bool dirty=true)
	Indicate that this phrases children need to be rebuilt (or not if dirty is false).

virtual bool	areSubphrasesBuilt () const
	Indicate whether the list of subphrases is built by a subphrase generator and is up to date.

virtual DescriptivePhrases &	subphrases ()
	Return children phrases that further describe the subject of this phrase.

virtual DescriptivePhrases	subphrases () const
	Return children phrases that further describe the subject of this phrase.

virtual int	argFindChild (const DescriptivePhrase *child) const
	Return the index of the given phrase in this instance's subphrases (or -1).

virtual int	argFindChild (const smtk::resource::ResourcePtr &child, bool onlyResource=true) const
	Return the index of the given Resource pointer in this instance's subphrases (or -1). More...

virtual int	argFindChild (const smtk::resource::ComponentPtr &child) const
	Return the index of the given Component pointer in this instance's subphrases (or -1).

virtual int	argFindChild (const std::string &propName, smtk::resource::PropertyType propType) const
	Return the index of the given property (name, type) in this instance's subphrases. More...

int	indexInParent () const
	Return the location of this phrase in its parent's array of children or -1 (if no parent).

void	index (std::vector< int > &idx) const
	Populate the index idx, from the top of the hierarchy, that will select this phrase. More...

std::vector< int >	index () const
	A convenience method that returns the index for the phrase.

DescriptivePhrasePtr	root () const
	Return the root phrase of the tree containing this item.

DescriptivePhrasePtr	relative (const std::vector< int > &relativePath) const
	Descend children of this phrase along the relativePath, returning the child or null. More...

DescriptivePhrasePtr	at (const std::vector< int > &absolutePath) const
	Descend the root of the current phrase given the absolute path, returning the child or null. More...

unsigned int	phraseId () const
	Return a unique integer ID of this phrase.

SubphraseGeneratorPtr	findDelegate () const
	Find the subphrase generator for this phrase (held locally or by any parent) or return null.

virtual bool	isPropertyValueType () const
	Return true if this phrase's type is any of: {STRING, FLOAT, INTEGER}_PROPERTY_VALUE.

virtual void	visitChildren (Visitor fn)
	Invoke fn on all of this phrase's existing children recursively. More...

PhraseModelPtr	phraseModel () const
	Return the PhraseModel (obtained via the subphrase generator) holding this phrase (or null).

bool	operator== (const DescriptivePhrase &other) const
	Provide contents-based comparison for phrases. More...

bool	operator!= (const DescriptivePhrase &other) const

void	reparent (const DescriptivePhrasePtr &nextParent)
	Do not call this; it is for use by subphrase generators.


virtual std::string	title () const
	Convenience functions to fetch and modify content. More...

virtual bool	isTitleMutable () const
	Indicate whether users should be allowed to edit the title text.

virtual bool	setTitle (const std::string &newTitle)
	A method called by user interface code to change the title text, returning true on success.

virtual std::string	subtitle ()
	Return supplementary text that should be displayed with less emphasis than the title.

virtual bool	isSubtitleMutable () const
	Indicate whether users should be allowed to edit the subtitle text.

virtual bool	setSubtitle (const std::string &newSubtitle)
	A method called by user interfaces to change the subtitle text, returning true on success.

virtual smtk::resource::PersistentObjectPtr	relatedObject () const
	Return the persistent object related to this phrase (or nullptr if not well defined).

virtual smtk::resource::ResourcePtr	relatedResource () const
	Return the resource related to this phrase (or nullptr if not well defined).

virtual smtk::resource::Resource *	relatedRawResource () const
	Convenience functions to fetch and modify content. More...

virtual smtk::resource::ComponentPtr	relatedComponent () const
	Return the resource component related to this phrase (or nullptr if not well defined).

virtual smtk::resource::Component *	relatedRawComponent () const
	Convenience functions to fetch and modify content. More...

virtual smtk::common::UUID	relatedComponentId () const
	A convenience function that returns the related component's UUID if one exists.

virtual std::string	relatedPropertyName () const
	If this phrase describes a property attached to a component, return the property name.

virtual smtk::resource::PropertyType	relatedPropertyType () const
	If this phrase describes a property attached to a component, return the property's type.

Static Public Member Functions
static bool	compareByTypeThenTitle (const DescriptivePhrasePtr &a, const DescriptivePhrasePtr &b)
	Phrase-type-based comparison method for DescriptivePhrases. More...

static bool	compareByTitle (const DescriptivePhrasePtr &a, const DescriptivePhrasePtr &b)
	Title-based comparison method for DescriptivePhrases. More...

Protected Member Functions
void	buildSubphrases ()
	Build (if required) the cached subphrases of this phrase.

void	manuallySetSubphrases (const DescriptivePhrases &children, bool notify=false)
	A special method for dealing with explicitly-specified lists. More...

int	visitChildrenInternal (Visitor fn, std::vector< int > &indices)
	Actual implementation of the public visitChildren() method.

Protected Attributes
WeakDescriptivePhrasePtr	m_parent

DescriptivePhraseType	m_type { DescriptivePhraseType::INVALID_DESCRIPTION }

SubphraseGeneratorPtr	m_delegate

PhraseContentPtr	m_content

unsigned int	m_phraseId

DescriptivePhrases	m_subphrases

bool	m_subphrasesBuilt { false }

Friends
class	SubphraseGenerator

class	PhraseModel

Detailed Description

A base class for phrases describing an SMTK model.

Instances of subclasses serve as the basis for user interfaces to display information about the model in a hierarchical fashion. Each phrase may have zero-to-many subphrases of any type and zero-or-one parent phrases.

The title(), subtitle(), and phraseType() report information for the user interface to present. In the Qt layer, these are to be used for list item text (title and subtitle) and icon (phraseType).

Subphrases are built on demand so that portions of the UI may be presented. Subphrases are not generated by instances of this class, but by instances of a delegate SubphraseGenerator class.

Any DescriptivePhrase may own a SubphraseGenerator, indicating that its children should be computed with that generator. More than one phrase may point to the same instance of SubphraseGenerator. However, the more convenient alternative is for only the top-level phrase of the tree to point to a subphrase generator; if a phrase does not have a generator but does have a parent, then it will use its parent's generator.

Member Typedef Documentation

◆ Visitor

using smtk::view::DescriptivePhrase::Visitor = std::function<int(DescriptivePhrasePtr, std::vector<int>&)>

The signature of a function used to visit all or part of a phrase hierarchy.

The second argument is a vector of integers specifying the indices of the phrase in its parent phrases (or empty if it has no parent). The back of the vector is the index in its immediate parent while the front holds the index of the top-level phrase to choose in order to descent the hierarchy to the current phrase, as if argFindChild() was called on each phrase during descent.

The return value indicates how the hiearchy traversal should continue: return 0 to continue iterating, 1 to skip children of this phrase, or 2 to terminate immediately.

Member Function Documentation

◆ argFindChild() [1/2]

int smtk::view::DescriptivePhrase::argFindChild	(	const smtk::resource::ResourcePtr &	child,
		bool	onlyResource = `true`
	)		const

virtual

Return the index of the given Resource pointer in this instance's subphrases (or -1).

If onlyResource is true, this will only find children whose relatedResource() matches child but whose relatedComponent() is null (meaning that the phrase is describing the resource rather than a component of the resource).

◆ argFindChild() [2/2]

int smtk::view::DescriptivePhrase::argFindChild	(	const std::string &	propName,
		smtk::resource::PropertyType	propType
	)		const

virtual

Return the index of the given property (name, type) in this instance's subphrases.

This assumes that the property name exactly matches the title of the phrase. When there is no match, -1 is returned.

◆ at()

DescriptivePhrasePtr smtk::view::DescriptivePhrase::at ( const std::vector< int > & absolutePath ) const

Descend the root of the current phrase given the absolute path, returning the child or null.

This is equivalent to this->root()->relative(absolutePath). Negative entries may exist in absolutePath, but the first entry must be non-negative.

◆ badges()

DescriptivePhrase::Badges smtk::view::DescriptivePhrase::badges ( ) const

Return an ordered subset of badges that apply to this phrase.

It is better to ask the PhraseModel directly than to invoke this method (which must ascend the tree of phrases to find the model.

◆ compareByTitle()

bool smtk::view::DescriptivePhrase::compareByTitle	(	const DescriptivePhrasePtr &	a,
		const DescriptivePhrasePtr &	b
	)

static

Title-based comparison method for DescriptivePhrases.

This can be used to help sort DescriptivePhrases based solely on their titles.

◆ compareByTypeThenTitle()

bool smtk::view::DescriptivePhrase::compareByTypeThenTitle	(	const DescriptivePhrasePtr &	a,
		const DescriptivePhrasePtr &	b
	)

static

Phrase-type-based comparison method for DescriptivePhrases.

This sorts DescriptivePhrases based first on their type and then by their title text.

◆ hasChildren()

bool smtk::view::DescriptivePhrase::hasChildren ( ) const

Indicate if the Phrase has children.

Note that this does not build the child subphrases.

◆ index()

void smtk::view::DescriptivePhrase::index ( std::vector< int > & idx ) const

Populate the index idx, from the top of the hierarchy, that will select this phrase.

Descriptive phrases form a hierarchy, i.e., a tree. Every phrase thus has an index p, specified as a vector of integers that select the children from the root of the hierarchy down to itself. This method populates idx with the selector for this phrase.

An empty idx indicates the current phrase is the root of the hierarchy.

When not empty, the first entry in the vector corresponds to the immediate child of the root phrase to descend to reach this phrase. The final entry in the returned vector p is identical to the value of indexInParent() (which is also identical to parent()->argFindChild(shared_from_this())).

◆ manuallySetSubphrases()

void smtk::view::DescriptivePhrase::manuallySetSubphrases	(	const DescriptivePhrases &	children,
		bool	notify = `false`
	)

protected

A special method for dealing with explicitly-specified lists.

This method exists to be called by PhraseListContent::setup() in order to populate the subphrases with a developer-specified list of phrases instead of having a subphrase generator create them.

This pattern is used indirectly by the SubphraseGenerator when creating subphrases that should themselves be grouped into multiple phrases rather than directly becoming children of a parent. A concrete example is when a model's cells should be split into a phrase listing faces and another listing edges.

Ordinarily the subphrase generator should not be bypassed, but here that creates problems because the subphrase generator may not be able to construct the list of phrases. Also, it may not be possible at this point to invoke methods on the PhraseModel to register new child phrases because the grandchildren are inserted into the child lists before the children are inserted into the parent... this means that the insertion would be provided a non-existent parent index.

◆ operator==()

bool smtk::view::DescriptivePhrase::operator== ( const DescriptivePhrase & other ) const

Provide contents-based comparison for phrases.

This allows unordered sets and maps to hold phrases. Also, it supports comparisons done by PhraseModel::updateChildren().

These compare m_parent, m_type, and m_delegate but do not examine subphrases or phrase ID. Comparing these 3 values should be enough to prove that they will behave the same if given the chance to prepare themselves.

◆ relatedRawComponent()

virtual smtk::resource::Component* smtk::view::DescriptivePhrase::relatedRawComponent ( ) const

inlinevirtual

Convenience functions to fetch and modify content.

Return the title text that should be displayed.

◆ relatedRawResource()

virtual smtk::resource::Resource* smtk::view::DescriptivePhrase::relatedRawResource ( ) const

inlinevirtual

Convenience functions to fetch and modify content.

Return the title text that should be displayed.

◆ relative()

DescriptivePhrasePtr smtk::view::DescriptivePhrase::relative ( const std::vector< int > & relativePath ) const

Descend children of this phrase along the relativePath, returning the child or null.

Negative entries in relativePath indicate that parents, rather than children should be visited. For example, a -2 indicates that the grandparent of the current phrase should be visited.

If a parent or child does not exist, a null pointer is returned.

◆ title()

virtual std::string smtk::view::DescriptivePhrase::title ( ) const

inlinevirtual

Convenience functions to fetch and modify content.

Return the title text that should be displayed.

◆ visitChildren()

void smtk::view::DescriptivePhrase::visitChildren ( Visitor fn )

virtual

Invoke fn on all of this phrase's existing children recursively.

This method will not descend any phrase if areSubphrasesBuilt() returns false.

The visitor fn should never modify any parents of the element in the phrase hierarchy it is called upon or the indices it is passed may become invalid. It is possible to modify the current element, including methods that will cause its children to change. In this case, the modified children will be visited since children are visited after their parents.

It is possible in the future that this method may execute in parallel. If so, it will also accept a c++17 execution policy.

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

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

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ Visitor

Member Function Documentation

◆ argFindChild() [1/2]

◆ argFindChild() [2/2]

◆ at()

◆ badges()

◆ compareByTitle()

◆ compareByTypeThenTitle()

◆ hasChildren()

◆ index()

◆ manuallySetSubphrases()

◆ operator==()

◆ relatedRawComponent()

◆ relatedRawResource()

◆ relative()

◆ title()

◆ visitChildren()