A VParameter enables VObjects to retrieve certain values. More...

#include <ocean/plankton/VParameter.hpp>

Inheritance diagram for Wizt::VParameter:

Public Types
using	UserIterator = std::function< bool(const WeakPtr< VManagedObject > &TheUsingObject, const string &alias)>
	Iterator object that allows to inspect the objects that (might) be using the current VParameter under a given alias name.

Public Types inherited from MemCore::ReferenceBase< ValueNotifierList >
using	reference_domain_t = ValueNotifierList
	The type of the base class.

using	SelfPtr_t = WeakPtr< ValueNotifierList, ValueNotifierList >
	Type for a pointer to this object itself.

Public Member Functions
void	AddAction (const RefPtr< ValueActionBase > &VAB)
	Add an action to the change of the underlying value.

const RefPtr< VCreationPreferences > &	addCreationPreference (const string &p)
	The creation preferences.

void	AddUndoAction (const RefPtr< VUndoAction > &what, int MaxActions)
	Add an undo action element to the undo stack.

Ageable &	age (const RefPtr< ValuePool > &VP) const
	The age of this parameter (it's the value's age)

virtual RefPtr< VValueBase >	createLocalVariable (const RefPtr< ValuePool > &GhostValues) const =0
	Cast a shadow of the current parameter's value onto the given ValuePool.

const RefPtr< VCreationPreferences > &	CreationPreferences () const
	The creation preferences.

const RefPtr< VValueBase > &	DefaultValue () const override
	Return a reference to an eventually associated default or global value of the associated variable.

const WeakPtrToVSlotContainer &	getCreator () const
	Return the creator of this object, i.e.

RefPtr< VValueBase >	getLocalValue (const RefPtr< ValuePool > &VP, const string &member, bool forceLocal) const
	Get the local shadow of the variable.

const SourceObject_t &	getOwner () const
	Retrieve source object of the value (alias for Source() )

RefPtr< VValueBase >	getProperty (const string &PropertyName) const
	Retrieve a certain property with yet unknown type.

template<typename T >
RefPtr< VTypedValueBase< T > >	getProperty (const string &PropertyName) const
	Retrieve a certain property with known type.

template<typename T >
bool	getProperty (const string &PropertyName, T &value) const
	Retrieve a certain property of a parameter.

const SourceObject_t &	getSource () const
	Retrieve source object of the value (alias for Source() )

const type_info &	getType () const
	Get the parameter type.

const type_info &	getType (const string &member) const
	Get the parameter type.

template<class Type >
bool	getValue (Type &Variable, const RefPtr< ValuePool > &Context, const string &theMember) const
	Get the current value of the parameter.

string	getValueAsText (const RefPtr< ValuePool > &, const string &member, bool forceLocalCreation)
	Get the parameter to a certain value as some textual description.

RefPtr< VValueBase >	getValueBase (const RefPtr< ValuePool > &Context, const string &member, bool forceLocal) const
	Retrieve a local value, if one exists, or the global value otherwise.

void	Globalize (const RefPtr< ValuePool > &GhostValues)
	Make the values of this parameter global, initializing the values from the given value pool.

void	includeUser (const WeakPtr< VManagedObject > &UsingObject, const string &alias)
	Inform the VParameter that some object will be using it under a specific name.

bool	isLocal () const
	Tell if the current parameter is local relative to a given context.

int	iterateProperties (ValueMap::iterator &it)
	Iterate over all properties of this parameter.

int	iterateUserAliases (const UserIterator &, const WeakPtr< VManagedObject > &TheUsingObject) const
	Iterate over all aliases of this parameter as seen from a a specific object.

int	iterateUsers (const UserIterator &) const
	Iterate over all users of this object, providing the alias names for this parameter.

void	Localize ()
	Set a parameter to have local values relative to some value pool.

string	Name () const
	Retrieve the name of this parameter.

virtual RefPtr< VValueBase >	newValue () const =0
	Create a new value with same value as this global one.

void	notifyInputs (const ValuePoolPtr &Context, const ValueNotifierList *Exclude, const WeakPtr< ValueNotifier > &issuer=NullPtr()) const
	Broadcast a value change event to all listening notifiers.

size_t	NumberOfProperties () const
	How many properties are associated at this parameter.

void	removeUser (const WeakPtr< VManagedObject > &UsingObject, const string &alias)
	Inform a VParameter that some object will no longer be using it under the given alias name.

void	sendNotification (const WeakPtr< ValueNotifier > &issuer=NullPtr(), const ValueNotifierList *Exclude=0, const ValuePoolPtr &VP=NullPtr())
	If some parameter properties have been changed, send a notification event to all input instances.

void	setCreator (VSlotContainer *Crec)
	Set the creator from a native pointer, which allows forward declaration of class VSlotContainer.

void	setName (const string &s)
	Modify the name of this parameter.

void	setProperty (const string &s, const RefPtr< VValueBase > &V, const WeakPtr< ValueNotifier > &issuer=nullptr, const ValueNotifierList *Exclude=0, const ValuePoolPtr &Ctx=nullptr)
	Set a property of this parameter, and issue a notification event relative to the global context to all listening input instances.

template<class Type >
void	setPropertyValue (const string &s, const Type &V, const WeakPtr< ValueNotifier > &issuer=NullPtr(), const ValueNotifierList *Exclude=0)
	Set a typed property of this parameter and issue a notification event to all connected input instances.

template<class Type >
bool	setPropertyValueIfNotExists (const string &theName, const Type &defaultValue, const WeakPtr< ValueNotifier > &issuer=NullPtr(), const ValueNotifierList *Exclude=0)
	Set a certain property of this parameter if it does not exist yet, and issue a notification event for the parameter's input object if it was created.

void	setSilentProperty (const string &s, const RefPtr< VValueBase > &V)
	Set a parameter's property without sending out a notification event.

template<class Type >
bool	setValue (const Type &Variable, const RefPtr< ValuePool > &Context, const string &member, bool forceLocalCreation, const WeakPtr< ValueNotifier > &issuer, const ValueNotifierList Exclude=0, const ValueMap vParam=0) const
	Set the parameter to a certain value and inform all input listeners about this change.

bool	setValueFromText (const string &VariableText, const RefPtr< ValuePool > &VP, const string &member, bool forceLocalCreation, const WeakPtr< ValueNotifier > &issuer, const ValueNotifierList Exclude=0, const ValueMap vParam=0) const
	Set the parameter to a certain value from some textual description and inform all input listeners about this change.

const SourceObject_t &	Source () const
	Retrieve source object of the value.

void	touchValue (const RefPtr< ValuePool > &Context) const
	Touch the parameter.

time_t	update (const RefPtr< ValuePool > &Context, const Ageable &Other)
	Update from time parameter.

void	updateProperties (const ValueMap &ThePropertyList, const WeakPtr< ValueNotifier > &issuer=NullPtr(), const ValueNotifierList *Exclude=0)
	Update all properties from the given list.

	VParameter (const RefPtr< VValueBase > &value, const string &initial_name, const RefPtr< VCreationPreferences > &CP)

	~VParameter ()
	Destructor.

Public Member Functions inherited from Wizt::ValueNotifierList
bool	addNotifier (const WeakPtr< ValueNotifier > &who) const

bool	addShadow (const WeakPtr< ValuePool, ValuePool > &ShadowPool) const
	Add an optional shadow of a certain variable, which means to remember the ValuePool's which contains an instance of the related value.

bool	contains (const WeakPtr< ValueNotifier > &who) const
	Checks if a certain ValueNotifier is contained here.

int	copyShadows (const ValueNotifierListPtr &Source)
	For each shadow found in the source's ValuePool, create a shadow for the current ValueNotifierList as well.

RefPtr< ValuePool, ValuePool >	findShadowByName (const string &ValuePoolName) const
	Find a value pool from a name, if this variable has a shadow in this pool.

int	iterate_shadows (const std::function< bool(const RefPtr< ValuePool, ValuePool > &ShadowPool, const RefPtr< VValueBase > &ShadowValue)> &ShadowValueIterator) const
	Iterator function, traverses all shadows (i.e. ValuePools)

int	iterateShadows (ValueShadowIterator &SI) const
	Iterator function, traverses all shadows (i.e. ValuePools)

int	iterateValues (NotifiedValueIterator &NVI) const
	Iterate overall notified values.

void	notify (const RefPtr< VValueBase > &value, const ValuePoolPtr &, const WeakPtr< ValueNotifier > &who, const ValueNotifierList Exclude, const ValueMap VP=0) const
	Broadcast a value change event to all listening notifiers.

bool	removeAllShadows ()
	Remove all shadows of a certain variable, i.e.

	ValueNotifierList ()
	Constructor.

	~ValueNotifierList ()
	Destructor.

Public Member Functions inherited from MemCore::ReferenceBase< ValueNotifierList >
auto	getObjectCountID () const noexcept
	Get a unique ID for this object in the given domain.

bool	isIdentical (const WeakPtr< ValueNotifierList, ValueNotifierList > &PossibleSelf) const noexcept
	Check if this object is identical to the one used by the given pointer.

void	mkAutoDestructive ()
	Marks this object as being automatically destructed, e.g.

refcount_t	refcount () const noexcept
	The strong reference count.

	ReferenceBase (ValueNotifierList *that) noexcept
	Constructor, initializes reference counter to zero.

const auto &	self () const
	Return weak pointer to the object self.

refcount_t	wrefcount () const noexcept
	The weak reference count.

Public Member Functions inherited from MemCore::Intercube
void	addInterface (const RefPtr< InterfaceBase > &I) const
	Add an interface class object.

template<class Data >
void	addInterfaceData (const Data &D)
	Add data via an interface class object.

template<class Data , typename TypeSelector >
void	addInterfaceData (const Data &D)
	Add data via an interface class object.

void	clearInterfaces ()
	Remove all interfaces.

bool	const_iterateInterfaces (const RefPtr< InterfaceIterationParameter > &IIP) const
	Constant iterator.

virtual RefPtr< InterfaceBase >	createInterface (const type_info &) const
	Virtual function which allows derived objects to create Interface objects on demand.

RefPtr< InterfaceBase >	findInterface (const type_info &t) const
	Find a certain interface of specified type.

RefPtr< InterfaceBase >	getInterface (const type_info &t)
	Retrieve an interface object from a certain type.

std::string	getInterfaceNames (const char delim=';') const
	Debug function retrieving all interfaces as human-readable string.

template<class Data >
bool	gotNewInterfaceData (const Data &D)
	Check whether data on the given interface have changed, and if so, set new data as interface.

template<class Data >
bool	gotNewInterfaceData (mutex &M, const Data &D)
	Check whether interface data have changed, if so, then set new interface data and return true.

template<class Data , typename Selector >
bool	gotNewInterfaceData (mutex &M, const Data &D)
	Check whether interface data have changed, if so, then set new interface data and return true.

template<class Data , typename Selector >
bool	gotNewInterfaceData (mutex &M, const Data &D, const Selector &S)
	Check whether interface data have changed, if so, then set new interface data and return true.

template<class Data , typename Selector >
bool	gotNewInterfaceData (mutex &M, const Data &D, const Selector *S)
	Check whether interface data have changed, if so, then set new interface data and return true.

template<class Data >
bool	hasChangedInterfaceData (const Data &D) const
	Check whether interface data have changed.

template<class Data , typename Selector >
bool	hasChangedInterfaceData (const Data &D) const
	Check whether interface data have changed.

template<class Data , typename Selector >
bool	hasChangedInterfaceData (const Data &D, const Selector &) const
	Check whether interface data have changed.

template<class Data , typename Selector >
bool	hasChangedInterfaceData (const Data &D, const Selector *) const
	Check whether interface data have changed.

bool	hasInterface (const type_info &t) const
	Check if some Interface might exist.

	Intercube ()
	Constructor.

bool	iterateInterfaces (const RefPtr< InterfaceIterationParameter > &IIP)
	Modifyable iterator.

void	printInterfaces () const
	Debug function that prints the names of all interfaces.

void	registerInterface (const type_info &t)
	Register an interface type; when the interface is actually required, the virtual createInterface() function will be called.

template<class InterfaceType >
void	removeInterface ()
	Remove an interface.

void	removeInterfaceBase (const type_info &InterfaceBaseID)
	Remove an interface.

virtual	~Intercube ()
	Destructor.

Public Attributes
int	relevance = 0
	An optional setting to specify how relevant this parameter is for the entire scene.

Additional Inherited Members
Protected Member Functions inherited from MemCore::ReferenceBase< ValueNotifierList >
virtual void	extremeUnction ()
	A virtual function that will be called just before the object is destroyed.

ReferenceBase &	operator= (const ReferenceBase &R)
	Protected assignment operator (should not be called).

void	suicide ()
	Delete this.

virtual	~ReferenceBase ()
	Virtual destructor.

Detailed Description

A VParameter enables VObjects to retrieve certain values.

It provides

name information
type information
value retrieval functionality
value modification and notification broadcasting. Certain VObjects may listen to the same VParameter instance. Also, a specific VParameter object may be managed through one or many input objects.

A parameter that is associated with one or more VObjects. The same VParameter may be shared among multiple VObjects. For each VObject, it may be accessed via another name which is relative to this VObject. Moreover, there may be many VInputBase objects associated with the same VParameter.

VParameters moreover possess

Creation Preferences - used during construction, originating from the Creator of this VParameter
Properties - used at lifetime to specify inputs, for instance a range of a slider, to be used across all possible Creators, if possible

Member Typedef Documentation

◆ UserIterator

using Wizt::VParameter::UserIterator = std::function<bool(const WeakPtr<VManagedObject>&TheUsingObject, const string&alias)>

Iterator object that allows to inspect the objects that (might) be using the current VParameter under a given alias name.

This "user list" for VParameters is similar to a backlink.

Constructor & Destructor Documentation

◆ VParameter()

Wizt::VParameter::VParameter	(	const RefPtr< VValueBase > &	value,
		const string &	initial_name,
		const RefPtr< VCreationPreferences > &	CP
	)

Parameters

value An initial default value, preferably an actually stored value such as VValue<>. Note that child class VValueParameter<> implements the creation of such a default value by virtue of an provided initial type, so using this child class is more convenient than the generic VParameter class in most cases. Only exception is when this initial value should not be a VValue<>, but something else.

However, note that VParameter is an abstract class and cannot be instantiated anyway on their own.

Member Function Documentation

◆ createLocalVariable()

virtual RefPtr< VValueBase > Wizt::VParameter::createLocalVariable ( const RefPtr< ValuePool > & GhostValues ) const

pure virtual

Cast a shadow of the current parameter's value onto the given ValuePool.

It the same ValuePool is specified on future retrieval, then all getValue()/setValue() calls will operate on this shadow instead of the global image.

Implemented in Wizt::VAbstractValueParameter< Type >, Wizt::VAbstractValueParameter< VSocketAction >, Wizt::VValueParameter< Type >, Wizt::VValueParameter< Wizt::VThreadManager >, Wizt::VValueParameter< VThreadManager >, and Wizt::VValueParameter< Action >.

Referenced by getLocalValue().

◆ getCreator()

const WeakPtrToVSlotContainer & Wizt::VParameter::getCreator ( ) const

inline

Return the creator of this object, i.e.

for which slot container this parameter was originally created. This information is used to generate the name of this parameter.

◆ getLocalValue()

RefPtr< VValueBase > Wizt::VParameter::getLocalValue	(	const RefPtr< ValuePool > &	VP,
		const string &	member,
		bool	forceLocal
	)		const

Get the local shadow of the variable.

Returns: NullPtr() if no such shadow exists.

Looking for eventual shadow value in value pool VP.

References createLocalVariable(), MemCore::DynPtr< Object, ObjectBase >::getType(), and MemCore::ReferenceBase< ValueNotifierList >::self().

Referenced by age().

◆ getValue()

template<class Type >

bool Wizt::VParameter::getValue	(	Type &	Variable,
		const RefPtr< ValuePool > &	Context,
		const string &	theMember
	)		const

inline

Get the current value of the parameter.

Parameters

VP	An eventual ValuePool storing shadow copies of the main variable.

◆ iterateUserAliases()

int Wizt::VParameter::iterateUserAliases	(	const UserIterator &	UI,
		const WeakPtr< VManagedObject > &	TheUsingObject
	)		const

Iterate over all aliases of this parameter as seen from a a specific object.

The UserIterator::apply() function will be called with the same object.

◆ Name()

string Wizt::VParameter::Name ( ) const

Retrieve the name of this parameter.

Provide a dynamically generated name for this parameter stemming from its original creator.

Referenced by AddUndoAction(), Wizt::VValueParameter< Type >::createLocalVariable(), Wizt::VValueParameter< Action >::createLocalVariable(), includeUser(), and removeUser().

◆ notifyInputs()

void Wizt::VParameter::notifyInputs	(	const ValuePoolPtr &	Context,
		const ValueNotifierList *	Exclude,
		const WeakPtr< ValueNotifier > &	issuer = `NullPtr()`
	)		const

inline

Broadcast a value change event to all listening notifiers.

Required for VInputBase::notify().

Parameters

Exclude If the notify request is issued from such a notifier, then it is not broadcasted.

Referenced by Globalize().

◆ setName()

void Wizt::VParameter::setName ( const string & s )

inline

Modify the name of this parameter.

The actual name will be this text plus the name of the associated creator object, of there is such.

◆ setProperty()

void Wizt::VParameter::setProperty	(	const string &	s,
		const RefPtr< VValueBase > &	V,
		const WeakPtr< ValueNotifier > &	issuer = `nullptr`,
		const ValueNotifierList *	Exclude = `0`,
		const ValuePoolPtr &	Ctx = `nullptr`
	)

Set a property of this parameter, and issue a notification event relative to the global context to all listening input instances.

Note that properties are NOT context-local (which might be some TODO to change later).

References Wizt::ValueNotifierList::notify().

◆ setPropertyValueIfNotExists()

template<class Type >

bool Wizt::VParameter::setPropertyValueIfNotExists	(	const string &	theName,
		const Type &	defaultValue,
		const WeakPtr< ValueNotifier > &	issuer = `NullPtr()`,
		const ValueNotifierList *	Exclude = `0`
	)

inline

Set a certain property of this parameter if it does not exist yet, and issue a notification event for the parameter's input object if it was created.

Returns: true if the parameter was set first time.

See also: forceSetProperty Set a property unconditionally.

◆ setSilentProperty()

void Wizt::VParameter::setSilentProperty	(	const string &	s,
		const RefPtr< VValueBase > &	V
	)

inline

Set a parameter's property without sending out a notification event.

A call to sendNotification() MUST be issued ASAP by the caller.

References Wizt::ValueMap::setValue().

◆ setValue()

template<class Type >

bool Wizt::VParameter::setValue	(	const Type &	Variable,
		const RefPtr< ValuePool > &	Context,
		const string &	member,
		bool	forceLocalCreation,
		const WeakPtr< ValueNotifier > &	issuer,
		const ValueNotifierList *	Exclude = `0`,
		const ValueMap *	vParam = `0`
	)		const

inline

Set the parameter to a certain value and inform all input listeners about this change.

Todo:: Add shadow parameterization!!

Member Data Documentation

◆ relevance

int Wizt::VParameter::relevance = 0

An optional setting to specify how relevant this parameter is for the entire scene.

This value can be used by a GUI or some logging mechanism, where it is valued against some verbosity. The relevance parameter differs from an Expert Level in that it is not necessarily related to a certain type, but rather its role in a certain session. It may be changed at any time, but it is recommended that objects defining parameters also set their relevance. The initial value is zero. It may be negative to state that the parameter is irrelevant and should not be exposed to the end-user, or positive to state its importance.

Public Types

Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ UserIterator

Constructor & Destructor Documentation

◆ VParameter()

Member Function Documentation

◆ createLocalVariable()

◆ getCreator()

◆ getLocalValue()

◆ getValue()

◆ iterateUserAliases()

◆ Name()

◆ notifyInputs()

◆ setName()

◆ setProperty()

◆ setPropertyValueIfNotExists()

◆ setSilentProperty()

◆ setValue()

Member Data Documentation

◆ relevance