A generic element within a Xentara model. More...

#include <xentara/workbench/model/Element.hpp>

Public Member Functions
virtual	~Element ()=0
	Virtual destructor.

Access to the Properties
auto	name () const noexcept -> utils::string::StringView
	Gets the name of the element.

auto	primaryKey () const -> std::string
	Gets the primary key of the element.

auto	uuid () const noexcept -> utils::core::Uuid
	Gets the UUID of the element.

auto	type () const -> ui::String
	Gets the the user facing type name of the element.

auto	category () const noexcept -> ElementCategory
	Gets the element category of the element.

Access to Elements Members
auto	attribute (std::string_view name) const -> utils::eh::expected< Attribute, ui::String >
	Gets the attribute with a specific name.

auto	attributes () const -> std::vector< Attribute >
	Returns a list of all the element’s attributes.

auto	event (std::string_view name, process::EventSearchOptions options={}) const -> utils::eh::expected< process::Event, ui::String >
	Gets the event with a specific name.

auto	events (process::EventSearchOptions options={}) const -> std::vector< process::Event >
	Returns a list of all the element’s events.

auto	task (std::string_view name) const -> utils::eh::expected< process::Task, ui::String >
	Gets the task with a specific name.

auto	tasks () const -> std::vector< process::Task >
	Returns a list of all the element’s tasks.

Access to the Element Hierarchy
auto	childElement (std::string_view name) const noexcept -> const Element *
	Gets the child element with a specific name.

auto	childElements () const noexcept -> ChildElementAccessor
	Returns a list of all the element’s children.

auto	parentElement () const noexcept -> const Element *
	Returns the element’s parent.

Creating References
auto	makeReference () const -> ElementReference
	Creates a reference to this element.

auto	makeAttributeReference (const Attribute &attribute) const -> AttributeReference
	Creates a reference to one of this element’s attributes.

auto	makeAttributeReference (std::string_view attributeName) const -> AttributeReference
	Creates a reference to one of this element’s attributes.

auto	makeEventReference (const process::Event &event, process::EventSearchOptions options={}) const -> process::EventReference
	Creates a reference to one of this element’s events.

auto	makeEventReference (std::string_view eventName, process::EventSearchOptions options={}) const -> process::EventReference
	Creates a reference to one of this element’s events.

auto	makeTaskReference (const process::Task &task) const -> process::TaskReference
	Creates a reference to one of this element’s tasks.

auto	makeTaskReference (std::string_view taskName) const -> process::TaskReference
	Creates a reference to one of this element’s tasks.

Iterator Functions
template<std::invocable< const Attribute & > Callback>
auto	forEachAttribute (Callback &&callback) const -> bool
	Iterates over all the element’s attributes.

template<std::invocable< const process::Event & > Callback>
auto	forEachEvent (Callback &&callback, process::EventSearchOptions options={}) const -> bool
	Iterates over all the element’s events.

template<std::invocable< const process::Task & > Callback>
auto	forEachTask (Callback &&callback) const -> bool
	Iterates over all the element’s tasks.

Validation functions for validating cross references
auto	checkCategory (ElementCategories allowedCategories) const noexcept -> bool
	Checks whether the element has one of a selection of categories.

auto	isDataPoint () const noexcept -> bool
	Checks whether the element is a data point.

auto	isSkillDataPoint () const noexcept -> bool
	Checks whether the element is a skill data point.

auto	isA (const skill::Element::Class &elementClass) const noexcept -> bool
	Checks whether the element has a certain class.

auto	isInvisibleRoot () const noexcept -> bool
	Checks whether the element is the invisible root element of the model.

auto	findAncestor (const skill::Element::Class &elementClass) const noexcept -> const Element *
	Finds the closest ancestor that has a certain class.

auto	isDescendentOf (const Element &ancestor) const noexcept -> bool
	Check whether the element is a descendent of another element.

Detailed Description

A generic element within a Xentara model.

Constructor & Destructor Documentation

◆ ~Element()

xentara::workbench::model::Element::~Element ( )

pure virtualdefault

Virtual destructor.

Member Function Documentation

◆ attribute()

auto xentara::workbench::model::Element::attribute ( std::string_view name ) const -> utils::eh::expected< Attribute, ui::String >

Gets the attribute with a specific name.

Parameters

name	The name of the desired attribute, in UTF-8 encoding

Returns: The corresponding attribute, or an error message if the attribute was not found.

◆ attributes()

auto xentara::workbench::model::Element::attributes ( ) const -> std::vector< Attribute >

Returns a list of all the element’s attributes.

Note: It you just want to iterate over the attributes, calling forEachAttribute() can be slightly faster, as it eliminates the construction of the vector.

Returns: A list of all the element’s attributes

◆ category()

auto xentara::workbench::model::Element::category ( ) const -> ElementCategory

noexcept

Gets the element category of the element.

Attention: When checking the category of an element while validating a cross reference, you should use checkCategory() or isDataPoint() rather than comparing the category directly, because checkCategory() and isDataPoint() will always allow custom elements, whose real category is unknown.

Returns: The element category that best describes the element.

◆ checkCategory()

auto xentara::workbench::model::Element::checkCategory ( ElementCategories allowedCategories ) const -> bool

noexcept

Checks whether the element has one of a selection of categories.

Parameters

allowedCategories The categories that the element may have.

Returns: Returns true if the element has one of the given categories. The function also returns true for custom elements, whose category is unknown.

◆ childElement()

auto xentara::workbench::model::Element::childElement ( std::string_view name ) const -> const Element *

noexcept

Gets the child element with a specific name.

Parameters

name	The name of the desired child element, in UTF-8 encoding

Returns: A pointer to the corresponding child element, or nullptr if no child element with the specified name was found.

◆ childElements()

auto xentara::workbench::model::Element::childElements ( ) const -> ChildElementAccessor

noexcept

Returns a list of all the element’s children.

Attention: The element hierarchy will change as the user edits the model, so neither the returned accessor, nor any references or pointers to child elements must be stored beyond the scope of the current function.

Returns: Returns a collection containing all of the element’s children.

◆ event()

auto xentara::workbench::model::Element::event	(	std::string_view	name,
		process::EventSearchOptions	options = `{}`
	)		const -> utils::eh::expected< process::Event, ui::String >

Gets the event with a specific name.

Normally, this function only finds free-standing events. It does not find change events for attributes. To include change events for attributes in the search, set the [.includeChangeEvents](EventSearchOptions::includeChangeEvents) option in the options parameter.

Parameters

name	The name of the desired event, in UTF-8 encoding
options	The search options.

Returns: The corresponding event, or an error message if the event was not found.

◆ events()

auto xentara::workbench::model::Element::events ( process::EventSearchOptions options = {} ) const -> std::vector< process::Event >

Returns a list of all the element’s events.

Normally, this function only returns free-standing events. It does not include change events for attributes. To include change events for attributes in the list, set the [.includeChangeEvents](EventSearchOptions::includeChangeEvents) option in the options parameter. as it eliminates the construction of the vector.

Parameters

options The search options.

Returns: A list of all the element’s events. If options includes the [.includeChangeEvents](EventSearchOptions::includeChangeEvents) option, the change events for attributes are also returned.

◆ findAncestor()

auto xentara::workbench::model::Element::findAncestor ( const skill::Element::Class & elementClass ) const -> const Element *

noexcept

Finds the closest ancestor that has a certain class.

Parameters

elementClass The desired element class for the ancestor

Returns: Returns the closest ancestor that is a skill element with the given class, or nullptr if none was found. If this element has itself the correct class, then this element is returned.

◆ forEachAttribute()

template<std::invocable< const Attribute & > Callback>

auto xentara::workbench::model::Element::forEachAttribute ( Callback && callback ) const -> bool

Iterates over all the element’s attributes.

This function takes a callback that will be called once for each event the element supports, in no particular order. The callback will be passed the UUID and the name of the event, as well as a pointer to the event itself.

If the callback returns a value that can be converted to bool, then the return value is used to determine whether the iteration should be terminated early. If the callback returns a value that evaluates to true, then the iteration is stopped and the callback is not called again. If the return value evaluates to false, then iteration continues as normal.

Parameters

callback The callback that should be called for each event.

Returns: If callback returns a value convertible to bool, then the function returns true if the callback returned true for any event. Otherwise, false is returned.

◆ forEachEvent()

template<std::invocable< const process::Event & > Callback>

auto xentara::workbench::model::Element::forEachEvent	(	Callback &&	callback,
		process::EventSearchOptions	options = `{}`
	)		const -> bool

Iterates over all the element’s events.

This function takes a callback that will be called once for each event the element supports, in no particular order. The callback will be passed the UUID and the name of the event, as well as a pointer to the event itself.

If the callback returns a value that can be converted to bool, then the return value is used to determine whether the iteration should be terminated early. If the callback returns a value that evaluates to true, then the iteration is stopped and the callback is not called again. If the return value evaluates to false, then iteration continues as normal.

Normally, this function only returns free-standing events. It does not include change events for attributes. To include change events for attributes in the list, set the [.includeChangeEvents](EventSearchOptions::includeChangeEvents) option in the options parameter.

Normally, this function only iterates over free-standing events. It does not include change events for attributes. To iterate over the change events for attributes as well, set the [.includeChangeEvents](EventSearchOptions::includeChangeEvents) option in the options parameter.

Parameters

callback	The callback that should be called for each event.
options	The search options.

Returns: If callback returns a value convertible to bool, then the function returns true if the callback returned true for any event. Otherwise, false is returned.

◆ forEachTask()

template<std::invocable< const process::Task & > Callback>

auto xentara::workbench::model::Element::forEachTask ( Callback && callback ) const -> bool

Iterates over all the element’s tasks.

This function takes a callback that will be called once for each event the element supports, in no particular order. The callback will be passed the UUID and the name of the event, as well as a pointer to the event itself.

If the callback returns a value that can be converted to bool, then the return value is used to determine whether the iteration should be terminated early. If the callback returns a value that evaluates to true, then the iteration is stopped and the callback is not called again. If the return value evaluates to false, then iteration continues as normal.

Parameters

callback The callback that should be called for each event.

Returns: If callback returns a value convertible to bool, then the function returns true if the callback returned true for any event. Otherwise, false is returned.

◆ isA()

auto xentara::workbench::model::Element::isA ( const skill::Element::Class & elementClass ) const -> bool

noexcept

Checks whether the element has a certain class.

Parameters

elementClass The desired element class

Returns: Returns true if the element is a skill element with the given class.

◆ isDataPoint()

auto xentara::workbench::model::Element::isDataPoint ( ) const -> bool

noexcept

Checks whether the element is a data point.

This function is shorthand for checkCategory(xentara::workbench::model::ElementCategory::DataPoint)

Returns: Returns true if the element is a data point. The function also returns true for custom elements, whose type is unknown.

◆ isDescendentOf()

auto xentara::workbench::model::Element::isDescendentOf ( const Element & ancestor ) const -> bool

noexcept

Check whether the element is a descendent of another element.

Parameters

ancestor The ancestor to check

Returns: return true if this element is either the ancestor itself, or one of it descendants.

◆ isInvisibleRoot()

auto xentara::workbench::model::Element::isInvisibleRoot ( ) const -> bool

noexcept

Checks whether the element is the invisible root element of the model.

This function is shorthand for checkCategory(xentara::workbench::model::ElementCategory::DataPoint)

Returns: Returns true if the element is the invisible root element of the model.

◆ isSkillDataPoint()

auto xentara::workbench::model::Element::isSkillDataPoint ( ) const -> bool

noexcept

Checks whether the element is a skill data point.

Returns: Returns true if the element is a skill data point. The function also returns true for custom elements, whose type is unknown.

◆ makeAttributeReference() [1/2]

auto xentara::workbench::model::Element::makeAttributeReference ( const Attribute & attribute ) const -> AttributeReference

Creates a reference to one of this element’s attributes.

Parameters

attribute The attribute. Existence of the attribute is not checked.

Returns: A reference to the given attribute

◆ makeAttributeReference() [2/2]

auto xentara::workbench::model::Element::makeAttributeReference ( std::string_view attributeName ) const -> AttributeReference

Creates a reference to one of this element’s attributes.

Parameters

attributeName The name of the desired attribute, in UTF-8 encoding. The name is not checked for existence or validity.

Returns: A reference to the given attribute

◆ makeEventReference() [1/2]

auto xentara::workbench::model::Element::makeEventReference	(	const process::Event &	event,
		process::EventSearchOptions	options = `{}`
	)		const -> process::EventReference

Creates a reference to one of this element’s events.

Parameters

event	The event. Existence of the event is not checked.
options	The search options to set in the reference.

Returns: A reference to the given event

◆ makeEventReference() [2/2]

auto xentara::workbench::model::Element::makeEventReference	(	std::string_view	eventName,
		process::EventSearchOptions	options = `{}`
	)		const -> process::EventReference

Creates a reference to one of this element’s events.

Parameters

eventName	The name of the desired event, in UTF-8 encoding. The name is not checked for existence or validity.
options	The search options to set in the reference.

Returns: A reference to the given event

◆ makeReference()

auto xentara::workbench::model::Element::makeReference ( ) const -> ElementReference

Creates a reference to this element.

Returns: The reference

◆ makeTaskReference() [1/2]

auto xentara::workbench::model::Element::makeTaskReference ( const process::Task & task ) const -> process::TaskReference

Creates a reference to one of this element’s tasks.

Parameters

task	The task. Existence of the task is not checked.

Returns: A reference to the given task

◆ makeTaskReference() [2/2]

auto xentara::workbench::model::Element::makeTaskReference ( std::string_view taskName ) const -> process::TaskReference

Creates a reference to one of this element’s tasks.

Parameters

taskName The name of the desired task, in UTF-8 encoding. The name is not checked for existence or validity.

Returns: A reference to the given task

◆ name()

auto xentara::workbench::model::Element::name ( ) const -> utils::string::StringView

noexcept

Gets the name of the element.

Note: The name is only known once the configuration of the element has been loaded.

Attention: The returned string view will remain valid only as long as the object is valid. If you are accessing the primary key through a shared pointer, you must not access the returned string view after destroying the pointer, as that may destroy the object. If you need to access the string after the shared pointer has been destroyed, you must first make a copy of it.

Returns: The name of the element, in UTF-8 encoding. For the invisible root element of the model (which has no name), an empty string is returned.

◆ parentElement()

auto xentara::workbench::model::Element::parentElement ( ) const -> const Element *

noexcept

Returns the element’s parent.

Attention: The element hierarchy will change as the user edits the model, so no references or pointers to the parent must be stored beyond the scope of the current function.

Returns: The element’s parent element, or nullptr if the element is the invisible root element. For top-level elements, the invisible root element is returned as parent element.

◆ primaryKey()

auto xentara::workbench::model::Element::primaryKey ( ) const -> std::string

Gets the primary key of the element.

Note: The primary key is only fully known once the entire configuration has been loaded.

Attention: The returned string view will remain valid only as long as the object is valid. If you are accessing the primary key through a shared pointer, you must not access the returned string view after destroying the pointer, as that may destroy the object. If you need to access the string after the shared pointer has been destroyed, you must first make a copy of it.

Returns: The primary key of the element, in UTF-8 encoding. For the invisible root element of the model (which has no primary key), an empty string is returned.

◆ task()

auto xentara::workbench::model::Element::task ( std::string_view name ) const -> utils::eh::expected< process::Task, ui::String >

Gets the task with a specific name.

Parameters

name	The name of the desired task, in UTF-8 encoding

Returns: The corresponding task, or an error message if the task was not found.

◆ tasks()

auto xentara::workbench::model::Element::tasks ( ) const -> std::vector< process::Task >

Returns a list of all the element’s tasks.

Note: It you just want to iterate over the tasks, calling forEachTask() can be slightly faster, as it eliminates the construction of the vector.

Returns: A list of all the element’s tasks

◆ type()

auto xentara::workbench::model::Element::type ( ) const -> ui::String

Gets the the user facing type name of the element.

Returns: The localized display name of the element’s type.

◆ uuid()

auto xentara::workbench::model::Element::uuid ( ) const -> utils::core::Uuid

noexcept

Gets the UUID of the element.

Note: The UUID is only known once the configuration of the element has been loaded.

Returns: The UUID of the element.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~Element()

Member Function Documentation

◆ attribute()

◆ attributes()

◆ category()

◆ checkCategory()

◆ childElement()

◆ childElements()

◆ event()

◆ events()

◆ findAncestor()

◆ forEachAttribute()

◆ forEachEvent()

◆ forEachTask()

◆ isA()

◆ isDataPoint()

◆ isDescendentOf()

◆ isInvisibleRoot()

◆ isSkillDataPoint()

◆ makeAttributeReference() [1/2]

◆ makeAttributeReference() [2/2]

◆ makeEventReference() [1/2]

◆ makeEventReference() [2/2]

◆ makeReference()

◆ makeTaskReference() [1/2]

◆ makeTaskReference() [2/2]

◆ name()

◆ parentElement()

◆ primaryKey()

◆ task()

◆ tasks()

◆ type()

◆ uuid()