InputScalar Class Reference

Scalar input class (only one output can connect to it at a time).

#include <Workspace/DataExecution/InputOutput/inputscalar.h>

Inheritance diagram for InputScalar:

Public Member Functions
	InputScalar (const QString &name, DataObject &obj, InputArray &owner)
	InputScalar (const QString &name, DataObject &obj, Operation &op, bool modifiedInPlace=false)
	~InputScalar () override
void	addConnection (Connection &connection)
template<typename T >
void	assign (const T &t)
bool	canConnect (const DataFactory &factory) const override
bool	canSerialize () const override
bool	connected () const override
void	disconnect () override
void	ensureHasData () override
const Connection *	getConnection () const
Connection *	getConnection () override
QString	getDataPathUsingId (bool scoped=true) const override
InputArray *	getOwner ()
const InputArray *	getOwner () const
template<typename T >
T &	getRawData ()
template<typename T >
const T &	getRawData () const
bool	getUpToDate () const override
bool	isConnectedToAsynchronous () const override
virtual bool	isFactoryCompatible (const DataFactory &factory) const
bool	isModifiedInPlace () const override
bool	isScalar () const override
bool	isWaitingForAsynchronousUpdate () const override
bool	load (const SerializedItem &item) override
void	markUpToDateWhereSafe () override
bool	rebuilt ()
void	removeConnection ()
bool	save (SerializedItem &item) const override
void	setUpToDate (bool b) override
bool	update (Updater *updater=nullptr) override
Public Member Functions inherited from Input
	~Input () override
virtual bool	canConnect (const DataFactory &factory) const =0
virtual void	ensureHasData ()=0
virtual Connection *	getConnection ()=0
bool	getIgnoreModifiedInPlaceDependency () const
QString	getTagName () const override
virtual bool	isModifiedInPlace () const =0
virtual bool	isScalar () const =0
void	setIgnoreModifiedInPlaceDependency (bool ignore)
Public Member Functions inherited from IOBase
	~IOBase () override
void	addConnectorThatRequiresQueuing ()
void	clearWidgetPropertyValues ()
virtual bool	connected () const =0
virtual void	disconnect ()=0
bool	getAllowedToSerialize () const
DataObject &	getDataObject ()
const DataObject &	getDataObject () const
virtual QString	getDataPath () const
virtual QString	getDataPathUsingId (bool scoped=true) const
const QString &	getDeprecationMessage () const
const QString &	getDescription () const
const DataFactory &	getFactory () const
IOBase *	getFromPath (const QString &path, Workspace &relativeTo, QStringList &errors) const override
QString	getIdPath (bool scoped=true) const override
const QString &	getName () const
Operation *	getOperation ()
const Operation *	getOperation () const
const QString &	getPreferredWidget () const
const Workspace *	getRootWorkspace () const override
Workspace *	getRootWorkspace () override
virtual QString	getTagName () const =0
bool	getUpToDate () const override=0
bool	getVisible () const
const QMap< QString, QVariant > &	getWidgetPropertyValueMap (const QString &widgetClassName) const
QValidator *	getWidgetValidator ()
const QValidator *	getWidgetValidator () const
const Workspace *	getWorkspace () const override
Workspace *	getWorkspace () override
bool	isDeprecated () const
void	markAsDeprecated (bool b, const QString &message="")
virtual void	markUpToDateWhereSafe ()
void	removeConnectorThatRequiresQueuing ()
void	setAllowedToSerialize (bool b)
void	setDataObject (DataObject &obj)
void	setDescription (const QString &description)
void	setName (const QString &name)
void	setOperation (Operation *op)
void	setPreferredWidget (const QString &name)
void	setUpToDate (bool b) override=0
void	setVisible (bool b)
void	setWidgetPropertyValue (const QString &widgetClassName, const QString &propertyName, const QVariant &value)
void	setWidgetValidator (QValidator *validator)
bool	shouldQueueChangesWhileUpdating () const
bool	update (Updater *updater=nullptr) override=0
Public Member Functions inherited from Updatable
	~Updatable () override
virtual bool	comesFromExternal () const
QString	getEnclosingScope () const
virtual Updatable *	getFromPath (const QString &path, Workspace &relativeTo, QStringList &errors) const =0
const QString &	getGlobalName () const
virtual QString	getIdPath (bool scoped=true) const =0
virtual Workspace *	getRootWorkspace ()
virtual const Workspace *	getRootWorkspace () const
QString	getScopedGlobalName () const
virtual bool	getUpToDate () const =0
virtual const Workspace *	getWorkspace () const =0
virtual Workspace *	getWorkspace ()=0
virtual void	idPathChanged ()
virtual bool	isConnectedToAsynchronous () const =0
virtual bool	isWaitingForAsynchronousUpdate () const =0
void	setGlobalName (const QString &name)
virtual void	setUpToDate (bool b)=0
virtual bool	update (Updater *updater=nullptr)=0
Public Member Functions inherited from Observable
virtual	~Observable ()
void	attachObserver (Observer &observer)
void	destroy ()
void	detachObserver (Observer &observer)
void	notifyEvent (const ObservableEvent &event)
Public Member Functions inherited from Serialize
virtual	~Serialize ()=default
virtual bool	canSerialize () const =0
virtual bool	load (const SerializedItem &item)=0
virtual bool	save (SerializedItem &item) const =0

Additional Inherited Members
Static Public Member Functions inherited from IOBase
static IOBase *	getIOBaseFromDataPath (const QString &dataPath, Operation &relativeTo, QStringList &errors)
Static Public Member Functions inherited from Updatable
static InputScalar *	findInputScalarGlobalName (const QString &scopedGlobalName, Workspace &relativeTo)
static IOBase *	findIOBaseGlobalName (const QString &scopedGlobalName, Workspace &relativeTo)
static Operation *	findOperationGlobalName (const QString &scopedGlobalName, Workspace &relativeTo)
Protected Member Functions inherited from Input
	Input (const QString &name, DataObject &obj)
Protected Member Functions inherited from IOBase
	IOBase (const QString &name, DataObject &obj)
virtual void	operationChanged (Operation *oldOp)
void	setVerifiedName (const QString &name)
Protected Member Functions inherited from Updatable
	Updatable ()
	Updatable (const Updatable &up)
void	notifyUpdated ()
Updatable &	operator= (const Updatable &up)
Protected Member Functions inherited from Observable
	Observable ()
	Observable (const Observable &)

Constructor & Destructor Documentation

InputScalar() [1/2]

InputScalar	(	const QString &	name,
		DataObject &	obj,
		Operation &	op,
		bool	modifiedInPlace = false
	)

Parameters

name	The name of the input. An input with the same name must not already exist in op.
obj	The DataObject to use for this input.
op	The operation owning this scalar input. The input will be added to op by the constructor.
modifiedInPlace	If op will modify the data held by this input, then modifiedInPlace must be set to true.

The input does not take ownership of obj.

See also

Operation::addInput()

InputScalar() [2/2]

InputScalar	(	const QString &	name,
		DataObject &	obj,
		InputArray &	owner
	)

Parameters

name	The name of the input. An input with the same name must not already exist in op.
obj	The DataObject to use for this input.
owner	The input array owning this scalar input. The scalar input must be an element of the owner input array.

The input does not take ownership of obj.

~InputScalar()

~InputScalar ( )

override

Removes the input from its operation, if it has been added to one.

Member Function Documentation

addConnection()

void addConnection

(

Connection &

connection

)

Parameters

connection

A Connection object that has this input as its destination.

Adds connection to this input. There can be only one connection for a given input, despite what the function name may suggest. It is likely that the name of this function will change to something less misleading at some stage.

Precondition

There must not already be a connection to this input.

We assume that the caller has already checked that connection is permitted to connect to this input (ie they checked that canConnect returned true), so callers of addConnection can then assume that addConnection always succeeds.

assign()

void assign ( const T &  t )

inline

Parameters

t	The object to be assigned to the input. The underlying type of t must support the assignment operator.

If the data object for this input has not yet been created, it will be created as part of this call. Thus, the function provides a very convenient way to set values of operation inputs.

The up to date status of the input is left unchanged by this function. If the input has no connection, then it will retain the value assigned to it here when it is updated. If the input does have a connection, then the value you assign here will be discarded.

See also

getRawData()

canConnect()

bool canConnect ( const DataFactory &  factory ) const

overridevirtual

Parameters

factory

The data factory of the output to be tested for connection to this input.

Returns

True if an output of type factory can be connected to this input. Reasons for not being able to connect include wrong type, already have a connection or have already reached the maximum number of allowed connections for this input.

Implements Input.

canSerialize()

bool canSerialize ( ) const

overridevirtual

Returns

True if this object can be serialized.

For objects that can be serialized, the save and load functions will be used to do the serialization. If this function returns false, both load() and save() must also return false.

Implements Serialize.

connected()

bool connected ( ) const

overridevirtual

Returns

True if a connection exists to this input. Inputs can still exist, even without a connection. In that case, the data is local to the input.

Implements IOBase.

disconnect()

void disconnect ( )

overridevirtual

Clients should call this function in preference to removeConnection(). If the input has a connection, that connection is destroyed and removeConnection() will be called automatically as part of that process.

Implements IOBase.

ensureHasData()

void ensureHasData ( )

overridevirtual

Ensures that the underlying data is a valid object(s). For array inputs, all array elements will have valid data objects after this call.

Note that this call may need to trace back through connections in order to guarantee that the data for this input is valid, since the data may be supplied by a connection. Depending on the connection types and workspace elements involved, this could chain back through a substantial part of the workspace.

This function is not strictly necessary, since scalar inputs provide the data object they hold and array inputs can be iterated over to do the same. The ensureHasData function here is merely a convenience for providing one place to do this for all input types.

Implements Input.

getConnection() [1/2]

const Connection * getConnection

(

)

const

Returns

The connection associated with this scalar input. If there is currently nothing connected, a null pointer will be returned.

getConnection() [2/2]

Connection * getConnection ( )

overridevirtual

Returns

The connection associated with this scalar input. If there is currently nothing connected, a null pointer will be returned.

Implements Input.

getDataPathUsingId()

QString getDataPathUsingId ( bool  scoped = true ) const

overridevirtual

Parameters

scoped

If true then return full scope of the item. If false, only return identifier local to its workflow.

Returns

The data path of the input/output using an operation ID path. The default implementation returns an empty string, which means an invalid data path (ie the input/output cannot support data manipulation).

Client code would not normally call this function, but rather would call getDataPath() instead because that function prefers to return the global name form of data path. A global name data path is more flexible than an operation ID data path, but it also has potential non-uniqueness issues if a global name is used more than once. A data path based on an operation ID path, on the other hand, is always unique, but it is broken by operations being moved to a different workspace or by them (or any parent workspace) being renumbered.

See also

getDataPath()

Reimplemented from IOBase.

getOwner() [1/2]

InputArray * getOwner

(

)

Returns

If the input is an element of an InputArray, a pointer to that InputArray will be returned. Otherwise, this function returns a null pointer to indicate that it has no owner, in which case it is most likely just a regular scalar input for an operation.

getOwner() [2/2]

const InputArray * getOwner

(

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getRawData() [1/2]

T & getRawData ( )

inline

Convenience wrapper around DataObject::getRawData() for the data object returned by getDataObject(). See the requirements for DataObject::getRawData() before using this function. In addition to those requirements, callers should ensure that it is actually safe to even use this input's data object. No checks on the input's up to date status are performed by this function, since it is assumed that the caller really knows the state of things and just wants to have convenient access to the underlying data.

See also

assign()

getRawData() [2/2]

const T & getRawData ( ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getUpToDate()

bool getUpToDate ( ) const

overridevirtual

Returns

True if this input or output is up to date. For array inputs, it must return true only if all connected inputs are up to date.

Implements IOBase.

isConnectedToAsynchronous()

bool isConnectedToAsynchronous ( ) const

overridevirtual

Returns

True if the updatable object is connected to an asynchronous updatable.

See also

isWaitingForAsynchronousUpdate(), update()

Implements Updatable.

isFactoryCompatible()

bool isFactoryCompatible ( const DataFactory &  factory ) const

virtual

isModifiedInPlace()

bool isModifiedInPlace ( ) const

overridevirtual

Returns

True if this input is potentially modified in place by the operation. This is used to ensure the up to date status is properly maintained.

Implements Input.

isScalar()

bool isScalar ( ) const

overridevirtual

Returns

True if this input is a simple, scalar input.

See also

InputScalar, InputArray

Implements Input.

isWaitingForAsynchronousUpdate()

bool isWaitingForAsynchronousUpdate ( ) const

overridevirtual

Returns

True if the updatable object is waiting for an asynchronous update.

See also

update()

Implements Updatable.

load()

bool load ( const SerializedItem &  item )

overridevirtual

Parameters

item	Supplies the state to be loaded into this object.

This function will load the state of this object from item. For many object types, this is most easily implemented in terms of the object's input operator (>>).

It would be reasonable for subclass implementations to assume that the data provided in item is in the same form as would have been saved from a call to save.

Returns

If the state of the object could not be loaded, the function returns false. A return value of true implies that the object state was successfully loaded. If canSerialize() returns false, this function must do nothing except return false as well.

Implements Serialize.

markUpToDateWhereSafe()

void markUpToDateWhereSafe ( )

overridevirtual

This function can be called after client code modifies the data of this input/output. It's purpose is to try to mark the input/output as up to date if it can be determined that it is safe to do so. This allows the input/output to potentially be brought up to date sooner than would otherwise occur, such as having to wait until an execution thread is started. One of the cases where this proves useful is when loading in data while a workspace is not executing and wanting widgets attached to the inputs/outputs to immediately show the modified values. Without this feature, the values would still be changed but the widgets would not reflect the change until after the execution thread is started and gets around to bringing the inputs and outputs up to date.

The default implementation of this function is to do nothing. Subclasses should only mark themselves as up to date if they do not depend on anything, such as an Operation or a connection with the input as its destination. They must also handle the execution thread correctly by ensuring that the up to date state is only modified directly if no execution thread is running.

Reimplemented from IOBase.

rebuilt()

bool rebuilt

(

)

When a connection to an input is requested to rebuild itself, it will also rebuild the data for the destination (ie input) it is attached to. If the input belongs to an Operation, this function gives that operation a chance to perform any required action after the input is rebuilt by calling its Operation::inputRebuilt() function. Once that is done, the input raises an InputRebuilt notification before returning the result of the call to Operation::inputRebuilt(). It is important to note that the event notifications occurs regardless of whether or not the Operation::inputRebuilt() function is successful.

Returns

True if the input does not belong to an operation or else it returns the result of the Operation::inputRebuilt() function call.

removeConnection()

void removeConnection

(

)

Removes any existing connection from this input. Since scalar inputs can only have one connection, the input will have no connections after this function returns. If the input already has no connection, it is not an error and no action is taken. If a connection was removed, the inputs up-to-date status is set to false and rebuilt() is called just before returning.

Note

This function does not destroy the connection. Rather, it is meant to be called by the connection object in its destructor. If clients want to ensure an input has a connection destroyed, use disconnect() instead.

save()

bool save ( SerializedItem &  item ) const

overridevirtual

Parameters

item	Where to save the state of this object.

This function will serialise the object by saving it to item. For most object types, this is most easily implemented in terms of the object's output operator (<<).

It is allowable for an object to only serialize part of itself. This would be useful if the data it represents has a set of defaults and only those values different to the defaults need to be serialized. Such an implementation then needs to be careful how it handles the complimentary load member function.

Returns

If an object could not be serialised or if the underlying object type does not support serialisation, this function should return false. A return value of true implies that the object was successfully saved to item. If canSerialize() returns false, this function must do nothing except return false as well.

Implements Serialize.

setUpToDate()

void setUpToDate ( bool  b )

overridevirtual

Parameters

b	Boolean value specifying the new up-to-date status of the object.

Precondition

If this object belongs to a workspace and that workspace's execution thread is running, setUpToDate() must only be called from that execution thread. If the execution thread is not running or there is no execution thread (or perhaps not even a workspace), then setUpToDate() may be called from any thread with appropriate thread protection being the responsibility of the caller.

If b is false, the call must also try to propagate forward the not up-to-date status through the workspace. The forward propagation must continue until it reaches something already not up to date. Note that for container-type objects (eg array inputs), the up-to-date status is controlled by all items in the container, so calling setUpToDate() doesn't actually change the status for a container as a whole. In that case, all it does is propagate forward the status as necessary.

Note that when is true, some subclasses may choose to raise some kind of event notification to let clients know that they have been brought up to date. Since this will have an impact on performance even if nothing is observing the event, subclasses should avoid making such notifications if it is not necessary.

See also

update(), getUpToDate()

Inputs and outputs do generate event notifications when setUpToDate() is called with a true parameter. In such cases, subclasses will normally call notifyUpdated() in their implementation of setUpToDate().

Implements IOBase.

update()

bool update ( Updater *  updater = nullptr )

overridevirtual

Parameters

updater

The execution thread that is calling the function. When the object is being updated from within a workspace, this parameter will normally hold the execution thread that is calling this function. If the object is not part of a workspace or is being updated from client code directly in some other way, this parameter should be a null pointer to indicate that execution is not under the control of an Updater object. This is crucial for robust handling of things like logging messages.

Calling this function attempts to bring the object up to date. For objects connected in a workspace, this must first bring all upstream dependencies up to date as required. Some updatables can update themselves asynchronously. In such instances update() will return false if an updatable is still being updated (asynchronously). In order to determine if an update() returned false because of a genuine failure or because the update is asynchronous (and still in progress) the isWaitingForAsynchronousUpdate() method should be queried to help determine the cause of the update failure.

Returns

True if the update was successful.

Postcondition

Exactly what "up to date" means is up to the subclass, but if update() returns true, then getUpToDate() must also return true immediately after update() returns.

See also

setUpToDate(), getUpToDate(), isWaitingForAsynchronousUpdate()

If this input is associated with an operation and it has no connections, then if the data object is created as part of the call to this input, it will also be set to its default value as determined by the operation.

Implements IOBase.