PCL
pcl::ProcessInstance Class Reference

High-level interface to a process instance. More...

#include <ProcessInstance.h>

+ Inheritance diagram for pcl::ProcessInstance:

Public Member Functions

 ProcessInstance (const Process &process)
 
 ProcessInstance (const ProcessInstance &p)
 
virtual ~ProcessInstance ()
 
bool AllocateTableRows (const ProcessParameter &table, size_type rowCount)
 
bool AllocateTableRows (const IsoString &tableId, size_type rowCount)
 
bool Assign (const ProcessInstance &p)
 
bool CanExecuteGlobal (String &whyNot) const
 
bool CanExecuteOn (const View &view, String &whyNot) const
 
bool CanExecuteOn (const ImageVariant &image, String &whyNot) const
 
bool CanLaunchInterface () const
 
ProcessInstance Clone () const
 
String Description () const
 
double ElapsedTime () const
 
bool ExecuteGlobal ()
 
bool ExecuteOn (View &view, bool swapFile=true)
 
bool ExecuteOn (ImageVariant &image, const IsoString &hints=IsoString())
 
void GetExecutionTimes (double &startJD, double &elapsedSecs) const
 
bool IsHistoryUpdater (const View &view) const
 
bool IsMaskable (const View &view, const ImageWindow &mask) const
 
bool Launch ()
 
bool LaunchInterface ()
 
ProcessInstanceoperator= (const ProcessInstance &p)
 
Variant ParameterValue (const ProcessParameter &parameter, size_type rowIndex=~size_type(0)) const
 
Variant ParameterValue (const IsoString &parameterId, size_type rowIndex=~size_type(0)) const
 
Process ParentProcess () const
 
void SetDescription (const String &text)
 
bool SetParameterValue (const Variant &value, const ProcessParameter &parameter, size_type rowIndex=~size_type(0))
 
bool SetParameterValue (const Variant &value, const IsoString &parameterId, size_type rowIndex=~size_type(0))
 
double StartJD () const
 
size_type TableRowCount (const ProcessParameter &table) const
 
size_type TableRowCount (const IsoString &tableId) const
 
String ToSource (const IsoString &language="JavaScript", const IsoString &varId=IsoString(), int indent=0) const
 
bool Validate (String &whyNot)
 
- Public Member Functions inherited from pcl::UIObject
virtual ~UIObject () noexcept(false)
 
virtual void EnsureUnique ()
 
bool IsAlias () const
 
bool IsGarbage () const
 
bool IsNull () const
 
bool IsSameObject (const UIObject &o) const
 
bool IsUnique () const
 
String ObjectId () const
 
IsoString ObjectType () const
 
bool operator< (const UIObject &o) const
 
bool operator== (const UIObject &o) const
 
size_type RefCount () const
 
void SetObjectId (const String &id)
 

Static Public Member Functions

static ProcessInstance FromIcon (const IsoString &iconId)
 
static ProcessInstance FromSource (const String &source, const IsoString &language="JavaScript")
 
static IsoStringList Icons ()
 
static IsoStringList IconsByProcessId (const IsoString &processId)
 
static ProcessInstanceNull ()
 
- Static Public Member Functions inherited from pcl::UIObject
static UIObjectNull ()
 

Additional Inherited Members

- Protected Member Functions inherited from pcl::UIObject
 UIObject ()=default
 
 UIObject (const UIObject &x)
 
 UIObject (UIObject &&x)
 
UIObjectoperator= (const UIObject &x)
 
UIObjectoperator= (UIObject &&x)
 

Detailed Description

ProcessInstance, along with Process, provides access to any installed process through intermodule communication.

ProcessInstance represents a live instance of an installed process that can be edited (by setting parameter values) and executed.

See also
Process

Definition at line 86 of file ProcessInstance.h.

Constructor & Destructor Documentation

◆ ProcessInstance() [1/2]

pcl::ProcessInstance::ProcessInstance ( const Process process)

Constructs this object as a reference to a new instance of the specified process. The newly created instance has a set of default parameter values.

◆ ProcessInstance() [2/2]

pcl::ProcessInstance::ProcessInstance ( const ProcessInstance p)
inline

Copy constructor. The newly constructed object references the same server-side process instance as the specified object p.

Note
Note that this constructor does not generate a new process instance. It just constructs a high-level reference to an existing process instance.

Definition at line 105 of file ProcessInstance.h.

◆ ~ProcessInstance()

virtual pcl::ProcessInstance::~ProcessInstance ( )
inlinevirtual

Destroys a process instance.

After destruction of this object, the server-side process instance is also destroyed (garbage-collected) if it is no longer referenced by other ProcessInstance objects.

Definition at line 116 of file ProcessInstance.h.

Member Function Documentation

◆ AllocateTableRows() [1/2]

bool pcl::ProcessInstance::AllocateTableRows ( const ProcessParameter table,
size_type  rowCount 
)

Allocates table rows for a table process parameter.

Parameters
tableReference to a table parameter in the parent process.
rowCountNumber of table rows to allocate. If the parameter has table row limitations, this value must be within the acceptable range.

Calling this member function deallocates all previously existing table rows in this instance, if there were any. Table rows cannot be appended neither deleted selectively; the whole table parameter is reallocated as a whole each time this member function is called. Calling this function with rowCount set to zero (if zero rows are acceptable for the specified table parameter) effectively deallocates the whole table parameter in this instance.

Returns true if the specified number of rows could be allocated successfully in this process instance; false in the event of error.

◆ AllocateTableRows() [2/2]

bool pcl::ProcessInstance::AllocateTableRows ( const IsoString tableId,
size_type  rowCount 
)
inline

Allocates table rows for a table process parameter.

This is an overloaded member function, provided for convenience. It allows reallocating a table parameter rows using a parameter identifier instead of a reference to a ProcessParameter object. Otherwise this member function behaves exactly like AllocateTableRows( const ProcessParameter&, size_type )

Definition at line 665 of file ProcessInstance.h.

◆ Assign()

bool pcl::ProcessInstance::Assign ( const ProcessInstance p)

Assigns the parameters of a process instance referenced by the specified object p to the instance referenced by this object. Returns true if the assignment operation was successful; false in the event of error.

Note that this member function does not do the same as an assignment operator or a copy constructor, because the latter two operations simply cause this object to reference an existing server-side instance (and possibly leave a previous instance unreferenced). This member function does not generate a new process instance and does not change existing references to server-side objects; it just copies process parameters (and probably other module-dependent data) from one existing instance to another.

Note
For this member function to success, the parent Process has to be an assignable process. Assignable processes return true from reimplemented Process::IsAssignable() virtual functions.

◆ CanExecuteGlobal()

bool pcl::ProcessInstance::CanExecuteGlobal ( String whyNot) const

Returns true iff this process instance can be executed in the global context.

If this member function returns false, the process should return in the string whyNot a description of the reasons why this instance cannot be executed on the global context. If the function returns true, the string whyNot will be cleared (so it will be empty and its previous contents will be lost).

A process is executed in the global context when it is not explicitly executed on a particular view. Two well-known examples of global processes are Preferences and ReadoutOptions. Note that a process can work both globally and on views. For example, the PixelMath process can work globally to generate new images, or locally when it is executed on a target view.

◆ CanExecuteOn() [1/2]

bool pcl::ProcessInstance::CanExecuteOn ( const View view,
String whyNot 
) const

Validates execution of this process instance on the specified view. Returns true iff this instance can be executed on the view.

If this member function returns false, the process should return in the string whyNot a description of the reasons why this instance cannot be executed on the specified view. If the function returns true, the string whyNot will be cleared (so it will be empty and its previous contents will be lost).

◆ CanExecuteOn() [2/2]

bool pcl::ProcessInstance::CanExecuteOn ( const ImageVariant image,
String whyNot 
) const

Validates execution of this process instance on the specified image. Returns true iff this instance can be executed on the image.

If this member function returns false, the process should return in the string whyNot a description of the reasons why this instance cannot be executed on the specified image. If the function returns true, the string whyNot will be cleared (so it will be empty and its previous contents will be lost).

◆ CanLaunchInterface()

bool pcl::ProcessInstance::CanLaunchInterface ( ) const

Returns true iff this process instance is able to open and activate a process interface.

Normally, each process has an associated interface that can always be launched through any existing (and valid) instance of the appropriate process class. However, there are some processes for which an interface does not make sense. A well-known example is the Invert process.

◆ Clone()

ProcessInstance pcl::ProcessInstance::Clone ( ) const

Generates a uniquely referenced, newly created process instance as a duplicate of the instance referenced by this object, and returns a high-level reference to it as a new ProcessInstance object.

◆ Description()

String pcl::ProcessInstance::Description ( ) const

Returns the descriptive text currently associated with this process instance, or an empty string if this instance has no description.

In PixInsight, each process instance has an associated text that the user can edit to describe the purpose and conditions of the applied processes. This feature is an extremely useful and efficient way to document a processing procedure.

◆ ElapsedTime()

double pcl::ProcessInstance::ElapsedTime ( ) const
inline

Returns the total elapsed time in seconds for the latest execution of this process instance, or zero if either this instance has never been executed, or if the execution time has not been recorded for some reason.

Definition at line 404 of file ProcessInstance.h.

◆ ExecuteGlobal()

bool pcl::ProcessInstance::ExecuteGlobal ( )

Executes this process instance on the global context. Returns true upon successful execution; false in the event of error.

See the documentation for CanExecuteGlobal() for additional comments on process execution contexts.

◆ ExecuteOn() [1/2]

bool pcl::ProcessInstance::ExecuteOn ( View view,
bool  swapFile = true 
)

Executes this process instance on the specified view. Returns true upon successful execution; false in the event of error.

The optional swapFile argument allows the caller to control generation of swap data as part of the instance execution. If swapFile is true (the default value), the PixInsight core application will save the previous state of the target view before instance execution. In this case the executed instance will be appended to the view's process history in the usual way, and the process will be undoable.

If swapFile is false, the previous state of the view is not saved, the instance is not added to the view's history, and the process cannot be undone after execution. In this case the caller module is responsible for leaving the image transported by view in a valid and predictable state. Keep in mind that if no swap data are generated before excution, the user has no way to restore the previous state of the image, and also has no way to control the sequence of processes that have given rise to the current state of the image. If these side effects are not correctly controlled and handled by the calling module, they will violate basic design principles of the PixInsight platform, and hence they can be a good reason for denying certification of a module.

This member function is typically called with the swapFile argument set to false by processes that execute other processes to implement their own tasks. For example, the standard ProcessContainer process (which is internal to the core application) does exactly this to execute a sequence of processes as a unique step in a view's process history. Another case where swapFile should be set to false is when a process generates a new image as a result of running a sequence of processes, but it wants to appear as the unique process in the initial state element of the view's process history.

◆ ExecuteOn() [2/2]

bool pcl::ProcessInstance::ExecuteOn ( ImageVariant image,
const IsoString hints = IsoString() 
)

Executes this process instance on the specified image. Returns true upon successful execution; false in the event of error.

Parameters
imageReference to an ImageVariant object that transports the image to be processed.
hintsA string containing a (possibly empty) list of hints intended to modify the way an image is processed. A process can simply ignore all of these hints, or just look for one or more hints that it recognizes and supports, ignoring others. When two or more hints are specified, they must be separated by space characters (0x20). File formats also support hints in a similar way; see for example the FileFormatInstance::Open() member function for more information. The default value is an empty string.

◆ FromIcon()

static ProcessInstance pcl::ProcessInstance::FromIcon ( const IsoString iconId)
static

Returns a process instance generated as a duplicate of the instance transported by a process icon with the specified identifier iconId.

Returns a null instance if the specified icon does not exist, or if an icon exists with the specified identifier but it is not a process icon (e.g., an image icon).

◆ FromSource()

static ProcessInstance pcl::ProcessInstance::FromSource ( const String source,
const IsoString language = "JavaScript" 
)
static

Returns a process instance generated from the specified source code.

Note
This member function is still not implemented; it will be implemented in a future version of PCL. For now, this function always returns a null process instance.

◆ GetExecutionTimes()

void pcl::ProcessInstance::GetExecutionTimes ( double &  startJD,
double &  elapsedSecs 
) const

Gets the running times for the latest execution of this process instance.

Parameters
[out]startJDStarting execution time as a Julian day number.
[out]elapsedSecsTotal elapsed execution time in seconds.

If this instance has never been executed, or if the execution times have not been recorded for some reason, both output values are set to zero.

◆ Icons()

static IsoStringList pcl::ProcessInstance::Icons ( )
static

Returns a string list with the identifiers of all existing process icons, or an empty list if there are no process icons.

◆ IconsByProcessId()

static IsoStringList pcl::ProcessInstance::IconsByProcessId ( const IsoString processId)
static

Returns a string list with the identifiers of all existing process icons transporting instances of the specified process, or an empty list if no such icons exist.

◆ IsHistoryUpdater()

bool pcl::ProcessInstance::IsHistoryUpdater ( const View view) const

Returns true iff this process instance will modify the process history of the specified view, in case it is executed on it.

If this member function returns false, then this instance can be safely executed on the view as a read-only process; the view won't be modified in any way.

◆ IsMaskable()

bool pcl::ProcessInstance::IsMaskable ( const View view,
const ImageWindow mask 
) const

Returns true iff this process instance can be masked with the specified image window when executed on the specified view.

When a process is masked, its result is mixed with the image in the state it was before execution, according to the values of a mask image. This process is carried out automatically by the PixInsight core application.

◆ Launch()

bool pcl::ProcessInstance::Launch ( )

Launches this process instance.

If this process has an associated default interface, then its top level window is shown and activated, and this instance is imported by the interface. After importing this instance, the interface will show its parameter values.

If this process has no default interface, then the core application attempts to execute this instance. If the process prefers global execution (see the Process::PrefersGlobalExecution() member function), then this instance will be executed in the global context; otherwise it will be executed on the current view, if there is at least one image available.

Returns true if this instance was successfully launched; false in the event of error, or if the core application was unable to launch or execute the instance.

◆ LaunchInterface()

bool pcl::ProcessInstance::LaunchInterface ( )

Opens and activates the interface associated to this process, and causes it to import this instance. After importing this instance, the interface will show its parameter values. Returns true if the interface could be successfully launched; false in the event of error.

◆ Null()

static ProcessInstance& pcl::ProcessInstance::Null ( )
static

Returns a reference to a null process instance. A null ProcessInstance object does not correspond to an existing process instance in the PixInsight core application.

◆ operator=()

ProcessInstance& pcl::ProcessInstance::operator= ( const ProcessInstance p)
inline

Assignment operator. Returns a reference to this object.

Makes this object reference the same server-side process instance as the specified object p. If the previous instance becomes unreferenced, it will be garbage-collected by the PixInsight core application.

Definition at line 140 of file ProcessInstance.h.

◆ ParameterValue() [1/2]

Variant pcl::ProcessInstance::ParameterValue ( const ProcessParameter parameter,
size_type  rowIndex = ~size_type(0) 
) const

Returns the value of a process parameter.

Parameters
parameterReference to an existing parameter in the parent process of this instance (see Process::Parameters()).
rowIndexZero-based index of the table row, when the specified parameter is a table column parameter. Must be within the range of existing rows for the corresponding table parameter in this instance, that is, from zero to the number of table rows minus one. If parameter is not a table column parameter this argument is ignored.

If the specified parameter is a table process parameter, this member function throws an Error exception. A table process parameter does not have a value, and its contents cannot be retrieved directly as a whole.

Note that the default value of the rowIndex argument is an impossible row index number: ~size_type(0). This value has been selected on purpose in order to force the caller to specify a row index when parameter is a table column parameter. This is a simple but effective security mechanism to robustify parameter access code: if no row index is specified for a table column parameter, this member function will always return an invalid Variant object (see below).

This member function returns a Variant object with the current value of the specified parameter or table cell parameter in this instance. An invalid Variant object is returned in the following cases:

  • If the specified parameter is not a valid parameter of the parent process.
  • If parameter is a table column parameter and the specified rowIndex is larger than or equal to the number of existing rows for the parent table parameter in this instance.

The calling process should always check Variant::IsValid() for the objects returned by this function.

◆ ParameterValue() [2/2]

Variant pcl::ProcessInstance::ParameterValue ( const IsoString parameterId,
size_type  rowIndex = ~size_type( 0 ) 
) const
inline

Returns the value of a process parameter.

This is an overloaded member function, provided for convenience. It allows retrieving parameter values using parameter identifiers instead of references to ProcessParameter objects. Otherwise this member function behaves exactly like ParameterValue( const ProcessParameter&, size_type ) const

Definition at line 529 of file ProcessInstance.h.

◆ ParentProcess()

Process pcl::ProcessInstance::ParentProcess ( ) const

Returns a Process object that represents the installed process that this instance belongs to.

◆ SetDescription()

void pcl::ProcessInstance::SetDescription ( const String text)

Sets the descriptive text for this process instance.

Instance descriptions can make use of the whole formating capabilities of PixInsight consoles; see the Console class for more information.

◆ SetParameterValue() [1/2]

bool pcl::ProcessInstance::SetParameterValue ( const Variant value,
const ProcessParameter parameter,
size_type  rowIndex = ~size_type(0) 
)

Sets the value of a process parameter.

Parameters
valueNew parameter value. The specified Variant object must transport an object of either the same type as the parameter whose value will be changed, or of a type that can legally be converted to the corresponding parameter type. The value must also observe the limits imposed by the parent process regarding acceptable values, numeric ranges, etc.
parameterReference to an existing parameter in the parent process of this instance (see Process::Parameters()).
rowIndexZero-based index of the table row, when the specified parameter is a table column parameter. Must be within the range of existing rows for the corresponding table parameter in this instance, that is, from zero to the number of table rows minus one. If parameter is not a table column parameter this argument is ignored.

If the specified parameter is a table process parameter, this member function throws an Error exception. A table process parameter does not have a value, and its contents cannot be set directly as a whole.

Note that the default value of the rowIndex argument is an impossible row index number: ~size_type(0). This value has been selected on purpose in order to force the caller to specify a row index when parameter is a table column parameter. This is a simple but effective security mechanism to robustify parameter access code: if no row index is specified for a table column parameter, this member function will always return false.

The value must observe the limits imposed by the parent process regarding valid numeric ranges, length limits, acceptable characters, etc., depending on parameter types. This member function returns true iff the parameter value could be set correctly. If the type of value cannot be converted to the required parameter type, an Error exception is thrown with the appropriate error message.

Note
To set the values of table column parameters, the necessary table rows must be allocated before calling this member function. To allocate table rows, use the AllocateTableRows() member function.

◆ SetParameterValue() [2/2]

bool pcl::ProcessInstance::SetParameterValue ( const Variant value,
const IsoString parameterId,
size_type  rowIndex = ~size_type( 0 ) 
)
inline

Sets the value of a process parameter.

This is an overloaded member function, provided for convenience. It allows changing parameter values using parameter identifiers instead of references to ProcessParameter objects. Otherwise this member function behaves exactly like SetParameterValue( const Variant&, const ProcessParameter&, size_type )

Definition at line 595 of file ProcessInstance.h.

◆ StartJD()

double pcl::ProcessInstance::StartJD ( ) const
inline

Returns the time when this process instance was last executed as a Julian day number. If this instance has never been executed, or if the execution time has not been recorded for some reason, this function returns zero.

Definition at line 392 of file ProcessInstance.h.

◆ TableRowCount() [1/2]

size_type pcl::ProcessInstance::TableRowCount ( const ProcessParameter table) const

Returns the number of existing rows in a table process parameter.

Parameters
tableReference to a table parameter in the parent process.

If the specified parameter is not a table process parameter of the parent process, this member function returns zero.

◆ TableRowCount() [2/2]

size_type pcl::ProcessInstance::TableRowCount ( const IsoString tableId) const
inline

Returns the number of existing rows in a table process parameter.

This is an overloaded member function, provided for convenience. It returns the number of existing table rows using parameter identifiers instead of references to ProcessParameter objects. Otherwise this member function behaves exactly like TableRowCount( const ProcessParameter& ) const

Definition at line 624 of file ProcessInstance.h.

◆ ToSource()

String pcl::ProcessInstance::ToSource ( const IsoString language = "JavaScript",
const IsoString varId = IsoString(),
int  indent = 0 
) const

Returns a source code representation of this process instance.

Parameters
languageThe language to use for the source code representation. Currently the only languages supported are "JavaScript" and "XPSM 1.0". The default language is JavaScript.
varIdThe identifier of a variable that will be used to represent this instance. If an empty string is specified (which is the default value), the PixInsight core application wll assign a default identifier. This identifier only applies to JavaScript source code representations, not to XML representations.
indentIndentation distance in characters. This is a constant number of white space characters (0x20) that will be prepended to each source code line. The default value is zero.

The source code generated by this function can be used directly for serialization of process instances in the specified language.

◆ Validate()

bool pcl::ProcessInstance::Validate ( String whyNot)

Requests the parent process to validate this process instance. Returns true upon successful validation; false if the instance is not valid, or in the event of error.

If this member function returns false, the process should return a description of the reasons to not validate the instance in the string whyNot. If the function returns true, the string whyNot will be cleared (so it will be empty and its previous contents will be lost).


The documentation for this class was generated from the following file: