Array input class (multiple outputs can connect to it at a time). More...

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

Inheritance diagram for InputArray:

Public Types
typedef Application::IndexBasedIterator< InputArray, true >	const_iterator

using	difference_type = ptrdiff_t

using	iterator = Application::IndexBasedIterator< InputArray, false >

using	size_type = size_t

using	value_type = InputScalar

Public Member Functions
	InputArray (const QString &name, DataObject &obj, Operation &op, bool modifiedInPlace=false)

	~InputArray () override

virtual InputScalar &	addInput (difference_type beforeIndex=-1)

iterator	begin ()

const_iterator	begin () const

bool	canConnect (const DataFactory &factory) const override

bool	canSerialize () const override

bool	connected () const override

void	disconnect () override

bool	empty () const

iterator	end ()

const_iterator	end () const

void	ensureHasData () override

virtual void	eraseAllInputs ()

virtual void	eraseInput (InputScalar &input)

Connection *	getConnection () override

QString	getDataPathUsingId (bool scoped=true) const override

ObjectArray	getElementDataAsObjectArray ()

virtual difference_type	getIndex (const Connection &connection) const

virtual difference_type	getIndex (const InputScalar &input) const

InputScalar &	getInput (size_type i)

const InputScalar &	getInput (size_type i) const

template<typename T >
QList< T * >	getRawElementData ()

template<typename T >
QList< const T * >	getRawElementData () const

bool	getUpToDate () const override

bool	isConnectedToAsynchronous () const override

bool	isModifiedInPlace () const override

bool	isScalar () const override

bool	isWaitingForAsynchronousUpdate () const override

bool	load (const SerializedItem &item) override

	operator InputScalar ** () const

InputScalar &	operator[] (size_type i)

const InputScalar &	operator[] (size_type i) const

bool	save (SerializedItem &item) const override

void	setUpToDate (bool b) override

size_type	size () const

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

Protected Member Functions
void	operationChanged (Operation *oldOp) override

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 &)

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)

Detailed Description

Array inputs differ from scalar inputs in that more than one output can be connected to it. An input array is implemented as an array of InputScalar objects.

Input arrays generate event notifications when elements are added or removed from the array. This allows clients to respond to the input array changing size and having elements come and go. This capability is particularly useful for widgets that form some sort of visual representation of the input array (see OperationIOWidget for a good example).

See also: InputElementAddedEvent, InputElementRemovalEvent

Member Typedef Documentation

◆ const_iterator

typedef Application::IndexBasedIterator<InputArray, true> const_iterator

◆ difference_type

using difference_type = ptrdiff_t

◆ iterator

using iterator = Application::IndexBasedIterator<InputArray, false>

◆ size_type

using size_type = size_t

◆ value_type

using value_type = InputScalar

Constructor & Destructor Documentation

◆ InputArray()

InputArray	(	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 array 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. Unlike InputScalar, the object itself is not actually used for holding data. It is only used for cloning to produce new objects as elements are added to the input array, and for destroying those same objects when the corresponding array element is deleted.

Apart from the underlying data, obj should otherwise be just like a normal fully configured DataObject.

See also: Operation::addInput()

◆ ~InputArray()

~InputArray ( )

override

Removes the input from its operation. All child inputs of the array input will also be removed as part of the destruction sequence.

Member Function Documentation

◆ addInput()

InputScalar & addInput ( difference_type beforeIndex = -1 )

virtual

Parameters

beforeIndex The index before which to insert the new input. If set to a negative number (the default if omitted), the new input is appended to the list. No checks are performed to ensure that beforeIndex is valid.

Returns: A new input, which will have been added to the input array at the specified index.

This function inserts a new input into the input array. It will initially have no underlying data and no connection. Just before it returns, it will raise a notification for an InputElementAddedEvent.

Postcondition: If the input array belongs to an Operation, that Operation will have its up to date status set to false.

◆ begin() [1/2]

iterator begin ( )

inline

◆ begin() [2/2]

const_iterator begin ( ) const

inline

◆ 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

Array inputs are always serializable, although their elements might not be. This arrangement is necessary so that information about how many array elements are present will always be saved/loaded as part of the serialization mechanism.

Implements Serialize.

◆ connected()

bool connected ( ) const

overridevirtual

Returns: True if a connection exists to any element of this input array.

Implements IOBase.

◆ disconnect()

void disconnect ( )

overridevirtual

If any connection exists to this input or output, this function is responsible for destroying it. For some subclasses (notably InputArray), this may mean forwarding the call to other objects eg the InputScalar elements of an InputArray).

Implements IOBase.

◆ empty()

bool empty ( ) const

Returns: True if there are no inputs in this input array.

◆ end() [1/2]

iterator end ( )

inline

◆ end() [2/2]

const_iterator end ( ) const

inline

◆ 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.

◆ eraseAllInputs()

void eraseAllInputs ( )

virtual

Erases all inputs.

◆ eraseInput()

void eraseInput ( InputScalar & input )

virtual

Parameters

input The input to remove and delete.

Precondition: input should not have a connection.

Postcondition: input will be permanently deleted.; If the input array belongs to an Operation, that Operation will have its up to date status set to false.

Before it does anything, this function first raises a notification for an InputElementRemovalEvent to give interested parties a chance to modify themselves for the pending removal. Note that the removal cannot be prevented, but the notification is a good oportunity for doing things like removing observers, deleting widgets related to the input being removed, etc.

◆ getConnection()

Connection * getConnection ( )

overridevirtual

Returns: The connection for this input, or a null pointer if there is no connection. Note that array inputs can only ever return a null pointer from this function, since a connection can only be made to a scalar input.

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.

◆ getElementDataAsObjectArray()

ObjectArray getElementDataAsObjectArray ( )

Returns: An object array containing references to the underlying data associated with each element.

Note: The data is referenced in the returned array - not cloned - so the InputArray still maintains ownership of the data.

◆ getIndex() [1/2]

InputArray::difference_type getIndex ( const Connection & connection ) const

virtual

Parameters

connection The connection to search for.

Returns: The index of the specified input connected to connection, or -1 if no element of the input array is connected to connection.

◆ getIndex() [2/2]

InputArray::difference_type getIndex ( const InputScalar & input ) const

virtual

Parameters

input The input to search for.

Returns: The index of the specified input, or -1 if input is not an element of the input array.

◆ getInput() [1/2]

InputScalar & getInput ( size_type i )

This is the safe version of the array indexing operator. It first ensures that an input at the specified index exists, creating new inputs as necessary until the index i is valid.

Note: The above paragraph describes deprecated behavior. New code should not rely on getInput() creating the input if it does not exist.

Precondition: i must be a non-negative integer.

Returns: The input at index i.

◆ getInput() [2/2]

const InputScalar & getInput ( size_type i ) const

This identical to calling operator[](int) const. Unlike the non-const version of getInput(), this function does not create the specified input if it does not exist.

Returns: The input at index i.

◆ getRawElementData() [1/2]

QList< T * > getRawElementData

Template Parameters

T	Must match the type of the underlying data factory associated with this input.

Returns: A QList containing the raw data underlying each of the elements of the InputArray

◆ getRawElementData() [2/2]

QList< const T * > getRawElementData

Template Parameters

T	Must match the type of the underlying data factory associated with this input.

Returns: A QList containing the raw data underlying each of the elements of the InputArray

◆ 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.

◆ 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.

◆ operationChanged()

void operationChanged ( Operation * oldOp )

overrideprotectedvirtual

Parameters

oldOp The previous operation assigned to this input/output.

This function is called by setOperation() if the operation being set is different to the one that was previously assigned. Subclasses can reimplement operationChanged() to do any further processing that might be necessary, such as raising event notifications. The new operation is available by calling getOperation(). The default implementation does nothing.

Reimplemented from IOBase.

◆ operator InputScalar **()

operator InputScalar ** ( ) const

Returns: The array of objects. This array should not be modified, but the objects themselves can be, although this should be avoided unless you are sure it is safe to do so.

Precondition: There must be at least one object in the array for this call to be safe. Clients should test with empty() first.

Clients can use the result as an iterator over the inputs. For example:

if (!inputArray.empty())
{
  unsigned      numInputs = inputArray.size();
  InputScalar** itBegin   = inputArray;
  InputScalar** itEnd     = itBegin + numInputs;
 
  for (InputScalar** it = itBegin; it != itEnd; ++it)
  {
    // Do something with the input ....
  }
}

◆ operator[]() [1/2]

InputScalar & operator[] ( size_type i )

No check is made to determine if i refers to a valid input.

Returns: The input at index i.

◆ operator[]() [2/2]

const InputScalar & operator[] ( size_type i ) const

No check is made to determine if i refers to a valid input.

Returns: The input at index i.

◆ 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.

◆ size()

InputArray::size_type size ( ) const

Returns: The number of inputs in this input array.

◆ 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()

Calling this function ensures that the input or output holds a valid, up to date data object. If this is an input with a connection, that connection will be updated as required. If this is an input with no connection and the input is not an array, a valid data object must still be created which can be assigned to or read from. For outputs, this will essentially just forward the request to the operation it is associated with.

See also: notifyUpdated()

Implements IOBase.

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ const_iterator

◆ difference_type

◆ iterator

◆ size_type

◆ value_type

Constructor & Destructor Documentation

◆ InputArray()

◆ ~InputArray()

Member Function Documentation

◆ addInput()

◆ begin() [1/2]

◆ begin() [2/2]

◆ canConnect()

◆ canSerialize()

◆ connected()

◆ disconnect()

◆ empty()

◆ end() [1/2]

◆ end() [2/2]

◆ ensureHasData()

◆ eraseAllInputs()

◆ eraseInput()

◆ getConnection()

◆ getDataPathUsingId()

◆ getElementDataAsObjectArray()

◆ getIndex() [1/2]

◆ getIndex() [2/2]

◆ getInput() [1/2]

◆ getInput() [2/2]

◆ getRawElementData() [1/2]

◆ getRawElementData() [2/2]

◆ getUpToDate()

◆ isConnectedToAsynchronous()

◆ isModifiedInPlace()

◆ isScalar()

◆ isWaitingForAsynchronousUpdate()

◆ load()

◆ operationChanged()

◆ operator InputScalar **()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ save()

◆ setUpToDate()

◆ size()

◆ update()