Provides an input to a workspace. More...

#include <Workspace/DataExecution/Operations/Builtin/workspaceinput.h>

Inheritance diagram for WorkspaceInput:

Public Member Functions
	WorkspaceInput ()

	~WorkspaceInput () override

bool	canChangeDataFactory (const DataFactory &factory) const override

bool	canChangeDataName (const QString &name) const override

bool	execute () override

QString	getHelpPage () const override

Output &	getMainOutput ()

const Output &	getMainOutput () const

InputScalar *	getWorkspaceInput ()

const InputScalar *	getWorkspaceInput () const

void	setUpToDate (bool b) override

void	workspaceChanged (Workspace *oldWorkspace) override

Public Member Functions inherited from PolymorphicDataOperation
	PolymorphicDataOperation (const OperationFactory &opFactory, const QString &opName, const DataFactory &dataFactory, const QString &dataName=QString(), bool isNameable=true)

	~PolymorphicDataOperation () override

virtual bool	canChangeDataFactory (const DataFactory &factory) const =0

virtual bool	canChangeDataName (const QString &name) const =0

Presentation::CustomOperationProperties *	createCustomPropertiesHandler () override

virtual QString	getAcceptableDataName (const QString &proposedName) const

const DataFactory &	getDataFactory () const

const QString &	getDataName () const

DataObject &	getDataObject ()

template<typename T >
bool	isDataType () const

bool	isDataType (const DataFactory &type) const

bool	isNameable () const

bool	isPolymorphicType () const override

bool	isUserConfigurable () override

bool	matchesDataType (const DataObject &otherObject) const

bool	setDataFactory (const DataFactory &factory)

bool	setDataName (const QString &name)

Public Member Functions inherited from Operation
	~Operation () override

bool	addInput (Input &input, bool modifiedInPlace=false)

bool	addOutput (Output &output)

template<typename T >
bool	assignInput (const QString &inputName, const T &value)

bool	canSerialize () const override

bool	connectProgressEvents (QProgressBar *progressBar)

virtual Presentation::CustomOperationProperties *	createCustomPropertiesHandler ()

virtual void	ensureHasData ()

bool	getBroadcastUpdateEvents () const

QColor	getColor () const

virtual QString	getDefaultIconPath () const

QString	getDefaultUiPath () const

QString	getDeprecationMessage () const

const QString &	getDescription () const

SerializedItem	getExtras ()

const OperationFactory &	getFactory () const

Operation *	getFromPath (const QString &path, Workspace &relativeTo, QStringList &errors) const override

virtual GraphicsSize	getGraphicsSize () const

virtual QString	getHelpPage () const

QString	getIconPath () const

const QUuid &	getId () const

QString	getIdPath (bool scoped=true) const override

QString	getIdPath (const Workspace &relativeTo) const

difference_type	getIndex (const Input &input, IndexCountingOptions options=SkipNone) const

difference_type	getIndex (const Output &output, IndexCountingOptions options=SkipNone) const

void	getIndexPair (InputScalar &input, difference_type &mainIndex, difference_type &arrayIndex)

Input *	getInput (const QString &name)

const Input *	getInput (const QString &name) const

Input *	getInput (size_type index)

const Input *	getInput (size_type index) const

InputArray *	getInputArray (const QString &name)

const InputArray *	getInputArray (const QString &name) const

IOBaseIteratorRange< Input, false >	getInputs ()

IOBaseIteratorRange< Input, true >	getInputs () const

InputScalar *	getInputScalar (const QString &name)

const InputScalar *	getInputScalar (const QString &name) const

template<typename T >
T &	getInputValue (const QString &inputName)

template<typename T >
const T &	getInputValue (const QString &inputName) const

const QString &	getLabel () const

QString	getLabelRelativeToRoot () const

Output *	getOutput (const QString &name)

const Output *	getOutput (const QString &name) const

Output *	getOutput (size_type index)

const Output *	getOutput (size_type index) const

IOBaseIteratorRange< Output, false >	getOutputs ()

IOBaseIteratorRange< Output, true >	getOutputs () const

template<typename T >
T &	getOutputValue (const QString &outputName)

template<typename T >
const T &	getOutputValue (const QString &outputName) const

bool	getProfilingEnabled () const

int	getProgress () const

int	getProgressContribution () const

bool	getProgressResetByNotUpToDate () const

virtual SchedulerFeatures	getRequiredSchedulerFeatures () const

InputScalar *	getScalarInput (size_type mainIndex, difference_type arrayIndex)

QString	getShortLabel () const

QString	getTagName () const

bool	getTerminateExecution () const

QString	getUiPath () const

bool	getUpToDate () const override

virtual bool	hasRequiredSchedulerFeatures () const

void	idPathChanged () override

virtual bool	inputRebuilt (InputScalar &input)

virtual bool	isAsynchronous () const

virtual bool	isAtomicUpdate () const

bool	isConnectedToAsynchronous () const override

bool	isDeprecated () const

bool	isEditable () const

bool	isIdPathCachingEnabled () const

virtual bool	isPolymorphicType () const

virtual bool	isRunningAsynchronously () const

virtual bool	isThreadSafe () const

template<typename T >
bool	isType () const

bool	isType (const OperationFactory &type) const

bool	isUpdating () const

virtual bool	isUserConfigurable ()

bool	isUsingDefaultColor () const

bool	isUsingDefaultIconPath () const

bool	isUsingDefaultUiPath () const

bool	isWaitingForAsynchronousUpdate () const override

bool	isWorkspaceType () const

bool	load (const SerializedItem &item) override

void	markUpToDateWhereSafe ()

bool	matchesType (const Operation &otherOperation) const

size_type	numInputs (IndexCountingOptions=SkipNone) const

size_type	numOutputs (IndexCountingOptions=SkipNone) const

bool	removeInput (const QString &name)

bool	removeInput (Input &input)

bool	removeOutput (const QString &name)

bool	removeOutput (Output &output)

virtual void	resetExecutionDependencies ()

bool	save (SerializedItem &item) const override

virtual bool	saveWithData (SerializedItem &item) const

virtual void	setAtomicUpdate (bool atomic)

void	setBroadcastUpdateEvents (bool enable)

void	setColor (const QColor &c)

void	setDescription (const QString &description)

void	setEditable (bool b)

void	setIconPath (const QString &path)

void	setId (const QUuid &id)

virtual void	setIdPathCachingEnabled (bool b)

virtual void	setInputNotUpToDate (InputScalar &input)

virtual void	setIsAsynchronous (bool asynchronous)

virtual void	setIsRunningAsynchronously (bool asynchronous)

void	setLabel (const QString &label)

virtual void	setOutputNotUpToDate (Output &output)

void	setProfilingEnabled (bool enable)

virtual void	setProgress (int percent)

void	setProgressContribution (int percent)

void	setProgressResetByNotUpToDate (bool b)

virtual void	setRequiredSchedulerFeatures (const SchedulerFeatures &)

void	setTerminateExecution (bool b)

void	setUiPath (const QString &path)

void	setUpToDate (bool b) override

bool	update (Updater *updater=nullptr) override

Public Member Functions inherited from WorkspaceElement
	~WorkspaceElement () override

const Workspace *	getWorkspace () const override

Workspace *	getWorkspace () override

virtual void	workspaceChanged (Workspace *oldWorkspace)

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

Public Member Functions inherited from TextLogger
	TextLogger ()

	TextLogger (const DataExecution::IOBase &io)

	TextLogger (const DataExecution::Operation &operation)

	TextLogger (const TextLogger &logger)

	TextLogger (TextLogger &&logger)

virtual	~TextLogger ()

void	logLine (const Application::LogManager::MessageCategory &category, const QString &msg) const

void	logLine (const QString &msg) const

void	logText (const Application::LogManager::MessageCategory &category, const QString &msg) const

void	logText (const QString &msg) const

TextLogger &	operator= (TextLogger)

Protected Member Functions
bool	bringInputsUpToDate () override

void	dataNameChanged (const QString &name) override

void	dataObjectChanged (DataObject &oldDataObject) override

bool	prepareInputsOutputsForLoad (const SerializedItem &item) override

Protected Member Functions inherited from PolymorphicDataOperation
virtual void	dataNameChanged (const QString &name)

virtual void	dataObjectAboutToChange ()

virtual void	dataObjectChanged (DataObject &oldDataObject)

bool	loadPolyPart (const QString &dataPlugin, const QString &dataType, const QString &dataName)

bool	postSave (SerializedItem &item) const override

bool	prepareInputsOutputsForLoad (const SerializedItem &item) override

Protected Member Functions inherited from Operation
	Operation (const OperationFactory &factory, const QString &label)

bool	bringArrayOfInputsUpToDate (Input *&array, size_type arraySize)

bool	bringArrayOfInputsUpToDate (std::vector< Input * > &array)

virtual bool	bringInputsUpToDate ()

bool	bringInputUpToDate (Input &input)

virtual void	cancelExecution (bool b)

virtual bool	execute ()=0

virtual bool	finishInputsOutputsAfterLoad (const SerializedItem &item)

Updater *	getCurrentUpdater ()

virtual const Input *	getRenamedInput (const QString &name) const

virtual const Output *	getRenamedOutput (const QString &name) const

virtual bool	inputsAreUpToDate () const

virtual bool	makeOutputsValid ()

virtual void	markOutputsUpToDate ()

void	pauseUpdate ()

virtual bool	postSave (SerializedItem &item) const

virtual bool	prepareInputsOutputsForLoad (const SerializedItem &item)

void	saveExtras (SerializedItem &item) const

virtual bool	shouldPutInExtras (const QString &tagName) const

Protected Member Functions inherited from WorkspaceElement
	WorkspaceElement ()

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
Public Types inherited from Operation
enum	ConfigStatus { GoodConfig = 0x00 , UnknownConfig = 0x01 , InvalidConfig = 0x02 }

using	difference_type = ptrdiff_t

enum	GraphicsSize { Default = 100 , Small = 65 }
	Options for the graphical size of an operation, able to be changed by derived classes. Values are percentages. More...

enum	IndexCountingOption { SkipNone = 0x0 , SkipInvisible = 0x1 , SkipDependencies = 0x2 }

using	size_type = size_t

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

Adding a WorkspaceInput operation to a workspace is the way to define an input for that workspace. For every WorkspaceInput, a corresponding input is created in the workspace containing it. The data name associated with the WorkspaceInput operation will be used as the name of the input for the containing workspace. Note, however, that since no operation can have two or more inputs with the same name, the workspace will ensure that input names are unique by appending a number to the name if necessary.

A WorkspaceInput operation can only provide a scalar input in the containing workspace (ie an InputScalar). There is currently no way to have an array input (ie InputArray) for the containing workspace. It may be possible to provide similar behaviour by creating an input with data type ObjectArray, but there is no general way to map an ObjectArray to an InputArray.

Also note that it is not currently possible to have a WorkspaceInput operation represent the Dependency input of the workspace or to represent an input with the name Dependency.

When an input to the containing workspace has its up to date status changed from true to false, the up to date status is propagated forward into the workspace itself where possible. Thus, some parts of the workspace may remain up to date if they don't depend on the input(s) becoming not up to date. Users should not rely on this, however, because in a future version, workspaces may be run remotely and this behaviour might not be preserved. It should be thought of as an optimization rather than a hard rule.

When a workspace is asked to execute, all of its inputs are brought up to date as the first step, regardless of whether the internal logic of the workspace requires them or not. This is important, since it means things like caching of data can't typically cross a workspace nesting level.

Note: This operation used to be called DataSource.

See also: WorkspaceOutput, Workspace

Constructor & Destructor Documentation

◆ WorkspaceInput()

WorkspaceInput ( )

Constructs as an input with the data type set to integer by default.

◆ ~WorkspaceInput()

~WorkspaceInput ( )

override

Ensures the input in the containing workspace is handled safely during the destruction sequence.

Member Function Documentation

◆ bringInputsUpToDate()

bool bringInputsUpToDate ( )

overrideprotectedvirtual

This function is responsible for first bringing the dependency input up to date, then determining all the inputs required to update the operation's outputs and bring those inputs up to date as well.

The default implementation assumes all inputs need to be brought up to date, but some operations may only require some of the inputs to be up to date in order to calculate the outputs. Indeed, some of the inputs may need to be up to date, their values checked and then some combination of the rest brought up to date. An example where this could be useful is where an operation should behave differently for different iterations of a loop.

Subclasses which choose to override this function should call the other overloaded version of this function as necessary to actually bring the inputs it needs up to date, since it will handle multi-threading in a future implementation. It must update the dependency input first on its own before anything else.

Returns: True if required inputs were able to be brought up to date.

See also: update(), execute(), bringInputUpToDate(), bringArrayOfInputsUpToDate()

Reimplemented from Operation.

◆ canChangeDataFactory()

bool canChangeDataFactory ( const DataFactory & factory ) const

overridevirtual

Parameters

factory The new factory that will be set.

This function is called by setDataFactory to determine if the data factory can indeed be changed. The old factory is still available by calling getDataFactory, since nothing has actually been changed at the point where canChangeDataFactory is called. It may also be called by other clients who are interested in knowing if a particular data factory change will be allowed before actually requesting the factory change.

Returns: True if the subclass is happy for the data factory to be set to factory. The subclass can return false to indicate that the data factory cannot be changed to factory, or indeed that it cannot be changed at all (ie to anything).

Implements PolymorphicDataOperation.

◆ canChangeDataName()

bool canChangeDataName ( const QString & name ) const

overridevirtual

Parameters

name	The new data name that will be set.

This function is called by setDataName to determine if the data name can indeed be changed. The old name is still available by calling getDataName, since nothing has actually been changed at the point where canChangeDataName is called. It may also be called by other clients who are interested in knowing if a particular name change will be allowed before actually requesting the name change.

Returns: True if the subclass is happy for the data name to be set to name. The subclass can return false to indicate that the data name cannot be changed to name, or indeed that it cannot be changed at all (ie to anything).

Implements PolymorphicDataOperation.

◆ dataNameChanged()

void dataNameChanged ( const QString & name )

overrideprotectedvirtual

Parameters

name	The new data name. This is the same as the return value from getDataName(). It is provided as a parameter merely for convenience and consistency.

This function is called by setDataName() once the data name has been changed. We reimplement the function here so that the output from the operation also has its name changed to name.

Reimplemented from PolymorphicDataOperation.

◆ dataObjectChanged()

void dataObjectChanged ( DataObject & oldDataObject )

overrideprotectedvirtual

Parameters

oldDataObject The old data object, which will be destroyed immediately after dataObjectChanged() returns. The new data object can be obtained by calling getDataObject().

Precondition: The up to date status of the operation will not yet have been reset. This will be done immediately after dataObjectChanged() returns.

This function is called by setDataFactory once the data object has been changed. It allows the subclass to take additional action to update itself before the process of changing the data factory is completed. After exit, the only thing setDataFactory will subsequently do is call setUpToDate(false) on the operation.

The default implementation does nothing.

Note: This function cannot do anything which might fail.

See also: dataObjectAboutToChange()

Reimplemented from PolymorphicDataOperation.

◆ execute()

bool execute ( )

overridevirtual

Subclasses need to implement this function to do the actual processing of the operation. Clients should not call this function directly, but should instead call the update() function, since it ensures all inputs are updated first and all outputs have setUpToDate called on each one.

Precondition: When called, this function can assume that all of its required inputs have already been brought up to date.

Postcondition: When this function exits, all of the operation's outputs need to have had their values set. It is not required that setUpToDate be called for each output, since this is done by the update() function after execute() returns.

Returns: True if the operation was able to execute successfully.

Implements Operation.

◆ getHelpPage()

QString getHelpPage ( ) const

overridevirtual

Returns: The file name of the help page for this operation. The file name should be unique within this plugin's help documentation and would normally correspond to the name given to a \page in doxygen-generated documentation sets. For example, the operation's help page is often defined like so:

\page helpmyoperation MyOperation

In this case, getHelpPage() should return the string "helpmyoperation".

Note: Due to issues with how doxygen handles lower/uppercase keywords, you should use only lowercase names for your \page's. Otherwise you may find that cross-references to these pages do not work.

Reimplemented from Operation.

◆ getMainOutput() [1/2]

Output & getMainOutput ( )

Returns: The output of this WorkspaceInput operation, i.e. the output that supplies data to the workflow.

◆ getMainOutput() [2/2]

const Output & getMainOutput ( ) const

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

◆ getWorkspaceInput() [1/2]

InputScalar * getWorkspaceInput ( )

Returns: The input in the parent workspace which corresponds to this WorkspaceInput. If the WorkspaceInput is not in a Workspace, the function returns a null pointer.

◆ getWorkspaceInput() [2/2]

const InputScalar * getWorkspaceInput ( ) const

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

◆ prepareInputsOutputsForLoad()

bool prepareInputsOutputsForLoad ( const SerializedItem & item )

overrideprotectedvirtual

Loads the details of the data type this operation will be associated with. If subclasses override prepareInputsOutputsForLoad() for themselves, they would normally call PolymorphicDataOperation::prepareInputsOutputsForLoad() as their first step before performing any processing specific to the subclass.

Reimplemented from PolymorphicDataOperation.

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

Implements Updatable.

◆ workspaceChanged()

void workspaceChanged ( Workspace * oldWorkspace )

overridevirtual

Parameters

oldWorkspace The previous workspace before it was changed.

Sub-classes should override this if they want to be notified whenever setWorkspace is called with a workspace different to the currently assigned workspace. The last thing setWorkspace will do before returning is call workspaceChanged with the old workspace as the parameter (this could be a null pointer).

Client code can also call this function if they change something which affects the workspace and which may affect operations in it. An example might be when a workspace has its own parent workspace set, so all WorkspaceInput operations need to be notified so they can change their internal data routing to reflect this.

Warning: The workspace oldWorkspace used to point to might no longer exist, so it is not safe to dereference this pointer.

Reimplemented from WorkspaceElement.

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ WorkspaceInput()

◆ ~WorkspaceInput()

Member Function Documentation

◆ bringInputsUpToDate()

◆ canChangeDataFactory()

◆ canChangeDataName()

◆ dataNameChanged()

◆ dataObjectChanged()

◆ execute()

◆ getHelpPage()

◆ getMainOutput() [1/2]

◆ getMainOutput() [2/2]

◆ getWorkspaceInput() [1/2]

◆ getWorkspaceInput() [2/2]

◆ prepareInputsOutputsForLoad()

◆ setUpToDate()

◆ workspaceChanged()