An object that manages bindable properties. More...

#include <xentara/workbench/bindings/PropertyController_definition.hpp>

Inheritance diagram for xentara::workbench::bindings::PropertyController:

Classes
struct	PropertyConfiguration
	Configuration parameters for a property. More...

class	PropertyConfigurationContext
	A context for configureProperties() More...

class	Subscription

struct	SubscriptionCallbacks
	A list of callbacks for a subscription. More...

Public Member Functions
	PropertyController () noexcept=default
	Default constructor.

	PropertyController (const PropertyController &) noexcept
	Copy constructor that does not actually copy anything.

	PropertyController (PropertyController &&) noexcept
	Copy constructor that does not actually move anything.

constexpr auto	operator= (const PropertyController &) noexcept -> PropertyController &
	Copy assignment operator that does not actually assign anything.

constexpr auto	operator= (PropertyController &&) noexcept -> PropertyController &
	Move assignment operator that does not actually assign anything.

virtual	~PropertyController ()=0
	virtual destructor

Accessing address-based properties
template<typename Type , typename Value > requires std::equality_comparable_with<const Type &, const Value &> && std::assignable_from<Type &, Value &&>
auto	setProperty (Type &property, Value &&value) const -> bool
	Sets an address-based property, and publishes changes if necessary.

template<typename Type , PropertyChangedInvocable ChangeCallback>
auto	subscribe (const Type &property, ChangeCallback &&changeCallback) -> Subscription
	Subscribes to an address-based property.

template<typename Type >
auto	subscribe (const Type &property, SubscriptionCallbacks callbacks) -> Subscription
	Subscribes to an address-based property, with support for specialized callbacks.

template<typename Type >
auto	publish (const Type &property, Action action=Action::ValueChanged, std::size_t index={}) const -> void
	Publishes a change to the value and state for an address-based property.

template<typename Type >
auto	publishValue (const Type &property, Action action=Action::ValueChanged, std::size_t index={}) const -> void
	Publishes a change to only the value of an address-based property.

template<typename Type >
auto	publishState (const Type &property) const -> void
	Publishes a change in only the state of an address-based property.

template<typename Type >
auto	publishVisibility (const Type &property) const -> void
	Publishes a change in the visibility of an address-based property.

template<typename Type >
auto	propertyState (const Type &property) const -> const utils::eh::expected< void, ui::String > &
	Gets the state of an address-based property.

template<typename Type >
auto	propertyVisible (const Type &property) const -> bool
	Gets the visibility of an address-based property.

template<typename Type >
auto	propertyId (const Type &property) const noexcept -> PropertyId
	Gets the ID of an address-based property.

template<typename Type >
auto	propertyHandle (const Type &property) noexcept -> PropertyHandle
	Creates a handle for an address-based property.

Accessing arbitrary properties
template<PropertyChangedInvocable ChangeCallback>
auto	subscribe (const PropertyId &propertyId, ChangeCallback &&changeCallback) -> Subscription
	Subscribes to a property.

auto	subscribe (const PropertyId &propertyId, SubscriptionCallbacks callbacks) -> Subscription
	Subscribes to a property, with support for specialized callbacks.

auto	publish (const PropertyId &propertyId, Action action=Action::ValueChanged, std::size_t index={}) const -> void
	Publishes a value and state change for a property.

auto	publishValue (const PropertyId &propertyId, Action action=Action::ValueChanged, std::size_t index={}) const -> void
	Publishes a change to only the value of a property.

auto	publishState (const PropertyId &propertyId) const -> void
	Publishes a change in the state of a property.

auto	publishVisibility (const PropertyId &propertyId) const -> void
	Publishes a change in the visibility of a property.

auto	propertyState (const PropertyId &propertyId) const -> const utils::eh::expected< void, ui::String > &
	Gets the state of a property.

auto	propertyVisible (const PropertyId &propertyId) const -> bool
	Gets the visibility of a property.

auto	propertyHandle (const PropertyId &propertyId) noexcept -> PropertyHandle
	Creates a handle for a property.

Public Member Functions inherited from xentara::workbench::bindings::PropertyContainer
	PropertyContainer () noexcept=default
	Default constructor.

	PropertyContainer (const PropertyContainer &other)
	Copy constructor.

	PropertyContainer (PropertyContainer &&other) noexcept
	Move constructor.

auto	operator= (const PropertyContainer &rhs) -> PropertyContainer &
	Copy assignment operator.

auto	operator= (PropertyContainer &&rhs) noexcept -> PropertyContainer &
	Move assignment operator that does not actually assign anything.

virtual	~PropertyContainer ()=0
	Virtual destructor.

auto	setEnclosingPropertyContainer (PropertyContainer &enclosingContainer, SetEnclosingPropertyContainerOptions options={}) -> void
	Sets the enclosing container.

auto	resetEnclosingPropertyContainer (SetEnclosingPropertyContainerOptions options={}) -> void
	Resets the enclosing container.

auto	enclosingPropertyContainer () const -> PropertyContainer *
	Gets the enclosing container.

auto	propertyErrorCount () const -> std::size_t
	Gets the number of error properties, including those of sub containers.

template<std::invocable Callback>
auto	subscribeToPropertyErrorCount (Callback &&callback) -> ErrorCountSubscription
	Subscribes to a property.

auto	forEachCrossReference (const ForEachCrossReferenceFunction &function, ForEachCrossReferenceOptions options={}) noexcept -> void
	Calls a function for each cross reference contained within the container.

Private Member Functions
virtual auto	configureProperties (PropertyConfigurationContext &context) -> void
	Called by the framework to request that the controller configure its properties.

Virtual overrides for PropertyContainer
auto	forEachSubPropertyContainer (const ForEachSubPropertyContainerFunction &function, bool includeInvisible) noexcept -> void final
	Virtual override for PropertyContainer::forEachSubPropertyContainer()

auto	forEachLocalCrossReference (const ForEachCrossReferenceFunction &function, bool includeInvisible) noexcept -> void final
	Virtual override for PropertyContainer::forEachLocalCrossReference()

auto	localPropertyErrorCount () const -> std::size_t final
	Virtual override for PropertyContainer::localPropertyErrorCount()

auto	propertyNotificationRaised (const PropertyId &propertyId) -> void final
	Virtual override for PropertyContainer::propertyNotificationRaised()

Additional Inherited Members
Protected Member Functions inherited from xentara::workbench::bindings::PropertyContainer
auto	subPropertyContainerAdded (const PropertyContainer &container) -> void
	Must be called by derived classes if a sub container was added.

auto	subPropertyContainerRemoved (const PropertyContainer &container) -> void
	Must be called by derived classes if a sub container was removed.

auto	subPropertyContainerListChanged (SubPropertyContainerListChangedOptions options={}) -> void
	Must be called by derived classes if the list of sub containers changed completely.

auto	subPropertyContainerListCopied (const PropertyContainer &other, SubPropertyContainerListChangedOptions options={}) -> void
	Must be called by derived classes if the list of sub containers was copied from another container.

auto	subPropertyContainerListMoved (PropertyContainer &other, SubPropertyContainerListChangedOptions options={}) -> void
	Must be called by derived classes if the list of sub containers was moved from another container.

auto	subPropertyContainerListSwapped (PropertyContainer &other, SubPropertyContainerListChangedOptions options={}) -> void
	Must be called by derived classes if the list of sub containers was swapped with another container.

auto	localPropertyErrorCountChanged () -> void
	Must be called by derived classes if the value returned by localPropertyErrorCount() has changed.

auto	raisePropertyNotification (const PropertyId &propertyId) const -> void
	Passes a property notification to the enclosing container.

Detailed Description

An object that manages bindable properties.

Bindable properties can be bound to UI bindings, and they support a publish/subscribe mechanism that allows clients to subscribe to variable changes.

Bindable properties are identified by a property ID. The property ID can be generated in one of two ways:

For address-based properties, the property ID is based on the address of the variable holding the property’s value.
For name-based properties, the property ID is based on an abstract property name. This is usually used for properties whose value is generated on-the-fly, rather that being stored in a variable.

Constructor & Destructor Documentation

◆ PropertyController() [1/3]

xentara::workbench::bindings::PropertyController::PropertyController ( )

defaultnoexcept

Default constructor.

◆ PropertyController() [2/3]

xentara::workbench::bindings::PropertyController::PropertyController ( const PropertyController & )

noexcept

Copy constructor that does not actually copy anything.

This copy constructor is a no-op. This allows you to copy objects that derive from PropertyController, without copying the subscriber list and property configurations.

◆ PropertyController() [3/3]

xentara::workbench::bindings::PropertyController::PropertyController ( PropertyController && )

noexcept

Copy constructor that does not actually move anything.

This move constructor is a no-op. This allows you to move objects that derive from PropertyController, without moving the subscriber list and property configurations.

◆ ~PropertyController()

xentara::workbench::bindings::PropertyController::~PropertyController ( )

pure virtualdefault

virtual destructor

Member Function Documentation

◆ configureProperties()

virtual auto xentara::workbench::bindings::PropertyController::configureProperties ( PropertyConfigurationContext & context ) -> void

privatevirtual

Called by the framework to request that the controller configure its properties.

This function is called lazily by the framework the first time the property configurations are needed.

Note: Configuring properties is optional. You only need to override this function if any properties require a visibility callback and/or a state callback.

Default Implementation: The default implementation does nothing, leaving all properties in the default configuration.

Parameters

context A context that allows configuring individual properties.

◆ forEachLocalCrossReference()

auto xentara::workbench::bindings::PropertyController::forEachLocalCrossReference	(	const ForEachCrossReferenceFunction &	function,
		bool	includeInvisible
	)		-> void

finalprivatevirtualnoexcept

Virtual override for PropertyContainer::forEachLocalCrossReference()

Implements xentara::workbench::bindings::PropertyContainer.

◆ forEachSubPropertyContainer()

auto xentara::workbench::bindings::PropertyController::forEachSubPropertyContainer	(	const ForEachSubPropertyContainerFunction &	function,
		bool	includeInvisible
	)		-> void

finalprivatevirtualnoexcept

Virtual override for PropertyContainer::forEachSubPropertyContainer()

Implements xentara::workbench::bindings::PropertyContainer.

◆ localPropertyErrorCount()

auto xentara::workbench::bindings::PropertyController::localPropertyErrorCount ( ) const -> std::size_t

finalprivatevirtual

Virtual override for PropertyContainer::localPropertyErrorCount()

Implements xentara::workbench::bindings::PropertyContainer.

◆ operator=() [1/2]

constexpr auto xentara::workbench::bindings::PropertyController::operator= ( const PropertyController & ) -> PropertyController &

constexprnoexcept

Copy assignment operator that does not actually assign anything.

This assignment operator is a no-op. This allows you to assign objects that derive from PropertyController, without changing the subscriber list and property configurations. Any existing subscribers will remain subscribed, and any existing property configurations will be retained.

Returns: A reference to this object

◆ operator=() [2/2]

constexpr auto xentara::workbench::bindings::PropertyController::operator= ( PropertyController && ) -> PropertyController &

constexprnoexcept

Move assignment operator that does not actually assign anything.

This assignment operator is a no-op. This allows you to assign objects that derive from PropertyController, without changing the subscriber list and property configurations. Any existing subscribers will remain subscribed, and any existing property configurations will be retained.

Returns: A reference to this object

◆ propertyHandle() [1/2]

auto xentara::workbench::bindings::PropertyController::propertyHandle ( const PropertyId & propertyId ) -> PropertyHandle

noexcept

Creates a handle for a property.

Parameters

propertyId The ID of the property to create the handle for. The property controller defines which IDs are used for which properties.

Returns: The handle

◆ propertyHandle() [2/2]

template<typename Type >

auto xentara::workbench::bindings::PropertyController::propertyHandle ( const Type & property ) -> PropertyHandle

noexcept

Creates a handle for an address-based property.

Parameters

property A reference to the variable holding the property’s value.

Returns: The handle

◆ propertyId()

template<typename Type >

auto xentara::workbench::bindings::PropertyController::propertyId ( const Type & property ) const -> PropertyId

noexcept

Gets the ID of an address-based property.

Parameters

property A reference to the variable holding the property’s value.

Returns: The ID

◆ propertyNotificationRaised()

auto xentara::workbench::bindings::PropertyController::propertyNotificationRaised ( const PropertyId & propertyId ) -> void

finalprivatevirtual

Virtual override for PropertyContainer::propertyNotificationRaised()

Implements xentara::workbench::bindings::PropertyContainer.

◆ propertyState() [1/2]

auto xentara::workbench::bindings::PropertyController::propertyState ( const PropertyId & propertyId ) const -> const utils::eh::expected< void, ui::String > &

Gets the state of a property.

Parameters

propertyId The ID of the property. The property controller defines which IDs are used for which properties.

Returns

The current state of the property. The state will be either a short localized text describing the error, or a default constructed expected if there is no error.

Invisible properties cannot have error states. If the property is invisible, this function will always return a default constructed expected.

◆ propertyState() [2/2]

template<typename Type >

auto xentara::workbench::bindings::PropertyController::propertyState ( const Type & property ) const -> const utils::eh::expected<void, ui::String> &

Gets the state of an address-based property.

Parameters

property A reference to the variable holding the property’s value.

Returns

The current state of the property. The state will be either a short localized text describing the error, or a default constructed expected if there is no error.

Invisible properties cannot have error states. If the property is invisible, this function will always return a default constructed expected.

◆ propertyVisible() [1/2]

auto xentara::workbench::bindings::PropertyController::propertyVisible ( const PropertyId & propertyId ) const -> bool

Gets the visibility of a property.

Parameters

propertyId The ID of the property. The property controller defines which IDs are used for which properties.

Returns: Returns true if the property is visible, or false if it is hidden.

◆ propertyVisible() [2/2]

template<typename Type >

auto xentara::workbench::bindings::PropertyController::propertyVisible ( const Type & property ) const -> bool

Gets the visibility of an address-based property.

Parameters

property A reference to the variable holding the property’s value.

Returns: Returns true if the property is visible, or false if it is hidden.

◆ publish() [1/2]

auto xentara::workbench::bindings::PropertyController::publish	(	const PropertyId &	propertyId,
		Action	action = `Action::ValueChanged`,
		std::size_t	index = `{}`
	)		const -> void

Publishes a value and state change for a property.

This function publishes both a value and a state change. To publish value and state changes separately, use publishValue() and publishState(), respectively. A visibility change is not published.

Parameters

propertyId	The ID of the property to publish. The property controller defines which IDs are used for which properties.
action	The action that is being published
index	The index of the element that changed. This parameter is ignored if action is Action::ValueChanged.

◆ publish() [2/2]

template<typename Type >

auto xentara::workbench::bindings::PropertyController::publish	(	const Type &	property,
		Action	action = `Action::ValueChanged`,
		std::size_t	index = `{}`
	)		const -> void

Publishes a change to the value and state for an address-based property.

This function publishes both a value and a state change. To publish value and state changes separately, use publishValue() and publishState(), respectively. A visibility change is not published.

Parameters

property	A reference to the variable holding the property’s value.
action	The action that is being published
index	The index of the element that changed. This parameter is ignored if action is Action::ValueChanged.

◆ publishState() [1/2]

auto xentara::workbench::bindings::PropertyController::publishState ( const PropertyId & propertyId ) const -> void

Publishes a change in the state of a property.

Parameters

propertyId The ID of the property to publish. The property controller defines which IDs are used for which properties.

◆ publishState() [2/2]

template<typename Type >

auto xentara::workbench::bindings::PropertyController::publishState ( const Type & property ) const -> void

Publishes a change in only the state of an address-based property.

Parameters

property A reference to the variable holding the property’s value.

◆ publishValue() [1/2]

auto xentara::workbench::bindings::PropertyController::publishValue	(	const PropertyId &	propertyId,
		Action	action = `Action::ValueChanged`,
		std::size_t	index = `{}`
	)		const -> void

Publishes a change to only the value of a property.

Parameters

propertyId	The ID of the property to publish. The property controller defines which IDs are used for which properties.
action	The action that is being published
index	The index of the element that changed. This parameter is ignored if action is Action::ValueChanged.

◆ publishValue() [2/2]

template<typename Type >

auto xentara::workbench::bindings::PropertyController::publishValue	(	const Type &	property,
		Action	action = `Action::ValueChanged`,
		std::size_t	index = `{}`
	)		const -> void

Publishes a change to only the value of an address-based property.

Parameters

property	A reference to the variable holding the property’s value.
action	The action that is being published
index	The index of the element that changed. This parameter is ignored if action is Action::ValueChanged.

◆ publishVisibility() [1/2]

auto xentara::workbench::bindings::PropertyController::publishVisibility ( const PropertyId & propertyId ) const -> void

Publishes a change in the visibility of a property.

Note: A change in visibility may also result in an implicit change in state, since invisible properties cannot have an error state. If the change in visibility also results in a change of state, the state will be published as well.

Parameters

propertyId The ID of the property to publish. The property controller defines which IDs are used for which properties.

◆ publishVisibility() [2/2]

template<typename Type >

auto xentara::workbench::bindings::PropertyController::publishVisibility ( const Type & property ) const -> void

Publishes a change in the visibility of an address-based property.

Note: A change in visibility may also result in an implicit change in state, since invisible properties cannot have an error state. If the change in visibility also results in a change of state, the state will be published as well.

Parameters

property A reference to the variable holding the property’s value.

◆ setProperty()

template<typename Type , typename Value >
requires std::equality_comparable_with<const Type &, const Value &> && std::assignable_from<Type &, Value &&>

auto xentara::workbench::bindings::PropertyController::setProperty	(	Type &	property,
		Value &&	value
	)		const -> bool

Sets an address-based property, and publishes changes if necessary.

This function will first compare the current value of property and value, and see if they compare equal. If they compare equal, nothing is done. If they do not compare equal, value is assigned to property, and a value and state change is published using publish().

This function will only work if the property controller uses the default property ID for the property, as generated using propertyId(). If the property controller uses a custom ID, you must assign the property manually, and call publish() as appropriate.

Parameters

property	A reference to the variable holding the property’s value.
value	The value to assign to the property

Returns: Returns true if the property changed, or false if the property did not change.

◆ subscribe() [1/4]

template<PropertyChangedInvocable ChangeCallback>

auto xentara::workbench::bindings::PropertyController::subscribe	(	const PropertyId &	propertyId,
		ChangeCallback &&	changeCallback
	)		-> Subscription

Subscribes to a property.

Parameters

propertyId	The ID of the property to subscribe to. The property controller defines which IDs are used for which properties.
changeCallback	A callback that will be called whenever the property’s value has changed.

Returns: An automatic object that can be used to unsubscribe the subscription.

◆ subscribe() [2/4]

auto xentara::workbench::bindings::PropertyController::subscribe	(	const PropertyId &	propertyId,
		SubscriptionCallbacks	callbacks
	)		-> Subscription

Subscribes to a property, with support for specialized callbacks.

Parameters

propertyId	The ID of the property to subscribe to. The property controller defines which IDs are used for which properties.
callbacks	The callbacks.

Returns: An automatic object that can be used to unsubscribe the subscription.

◆ subscribe() [3/4]

template<typename Type , PropertyChangedInvocable ChangeCallback>

auto xentara::workbench::bindings::PropertyController::subscribe	(	const Type &	property,
		ChangeCallback &&	changeCallback
	)		-> Subscription

Subscribes to an address-based property.

Parameters

property	A reference to the variable holding the property’s value.
changeCallback	A callback that will be called whenever the property’s value has changed.

Returns: An automatic object that can be used to unsubscribe the subscription.

◆ subscribe() [4/4]

template<typename Type >

auto xentara::workbench::bindings::PropertyController::subscribe	(	const Type &	property,
		SubscriptionCallbacks	callbacks
	)		-> Subscription

Subscribes to an address-based property, with support for specialized callbacks.

Parameters

property	A reference to the variable holding the property’s value.
callbacks	The callbacks.

Returns: An automatic object that can be used to unsubscribe the subscription.

Classes

Public Member Functions

Private Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ PropertyController() [1/3]

◆ PropertyController() [2/3]

◆ PropertyController() [3/3]

◆ ~PropertyController()

Member Function Documentation

◆ configureProperties()

◆ forEachLocalCrossReference()

◆ forEachSubPropertyContainer()

◆ localPropertyErrorCount()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ propertyHandle() [1/2]

◆ propertyHandle() [2/2]

◆ propertyId()

◆ propertyNotificationRaised()

◆ propertyState() [1/2]

◆ propertyState() [2/2]

◆ propertyVisible() [1/2]

◆ propertyVisible() [2/2]

◆ publish() [1/2]

◆ publish() [2/2]

◆ publishState() [1/2]

◆ publishState() [2/2]

◆ publishValue() [1/2]

◆ publishValue() [2/2]

◆ publishVisibility() [1/2]

◆ publishVisibility() [2/2]

◆ setProperty()

◆ subscribe() [1/4]

◆ subscribe() [2/4]

◆ subscribe() [3/4]

◆ subscribe() [4/4]